Guia de Introdução a APIS da Admotion (REST)

O objetivos dessa guia é ajudar desenvolvedores a entender o funcionamento e a implementação das APIs da Admotion. São assumidos conhecimentos básicos sobre serviços web tipo REST e programação em geral.

Pré requisitos

Antes de começar a utilizar as APIS da Admotion, é necessário assegurar-se de cumprir os seguintes requisitos:

  • Deve ter um código de cliente (client code) e uma senha para API (API Key). Para obtê-los entre em contato com seu executivo de conta da Admotion. São pedidos os seguintes dados:
    • Nome do cliente
    • Dados de contato técnico (responsável, e-mail e telefone)
    • Produto e APIs que serão utilizados
    • Objetivo da utilização da API
  • No caso de serviços relacionados ao produto AMP, também será necessário utilizar uma conta de usuário da Admotion (Login e senha). Lembre-se que as permissões e dados a que todos terão acesso dependerá da conta de usuário utilizada. Se não possui uma conta da Admotion, solicite-a a seu executivo de conta da Admotion.

Tecnologia

As APIs da Admotion também podem ser utilizadas mediante REST ou SOAP. Essa guia oferece referência técnica e exemplos da implementação REST dos serviços para a plataforma C#.NET.

Autenticação

Para poder acessar as APIs da Admotion, o cliente deve ser autenticado e autorizado, para isso as APIS da Admotion possuem um serviço de autenticação (authentication servisse). Este tem os seguintes métodos:

Métodos

Descrição

Parâmetros

Parâmetros de cabeçalho

Retorno

login Autentica o cliente e o usuário. Inicia a sessão do usuário. username

password

clientcode

authtoken

ts

AccessToken
logout Finaliza a sessão clientcode accesstoken

Cada cliente com acesso a API deverá contar com certos dados que servirão para serem enviados ao método “login” do serviço de autenticação e assim poderem ser validados. Esses dados são:

  • Nome de usuário (User name): Nome de usuário dentro do sistema de Admotion Accounts.
  • Senha (Password): Senha privada do usuário para o acesso às aplicações da Admotion.
  • Código de cliente (Client Code): É um código de cliente fornecido pela Admotion.
  • Senha privada da API (API Key): É uma senha privada fornecida pela Admotion para cada cliente e para cada API, só é conhecida por estes e é utilizada para geração do token de autenticação. Este token será utilizado, por sua vez, para validar o pedido de autenticação.
  • Token de Autenticação (Authentication token): É um token gerado com a senha provada e o timestamp atual no GTM 0. (Explicado detalhadamente na próxima sessão)

Com esses dados e uma vez verificada a autenticação, o cliente terá um token de Acesso (Access Token), o qual deverá ser posteriormente utilizado em todas as solicitações de métodos de serviços da API.
O Token de Acesso atua como uma verificação de acesso para a API e também cumpre a função de gerador de sessão do usuário, que expira se não é utilizada por 20 minutos. Se isso ocorrer é necessário repetir o processo de autenticação para obter um novo token de acesso.

IMPORTANTE: Se você não possui algum desses dados, por favor, entre em contato com seu executivo de conta da Admotion.

Geração do Token de Autenticação (Authentication Token)

Para poder gerar este valor, é necessário uma senha privada da API. Essa senha, como mencionado anteriormente, é fornecida pela Admotion. O token é um hash, que será gerado a partir do algoritmo conhecido como “HMAC SHA256”. Este algoritmo de criptografia ou geração de hash, recebe os parâmetros, a senha privada e o valor a ser criptografado. Como o valor a criptografar usaremos o timestamp atual expressado em GTM 0.

Um hash é uma representação criptografada de uma sequência de texto resultando outra sequência de texto exclusiva que o representa.
Um timestamp é o número em segundos a partir das 00:00:00 de 1 de janeiro de 1970.

Vale ressaltar que o timestamp utilizado deve ser gerado a partir da hora atual, portanto o servidor onde o projeto estiver armazenado não deve ter seu horário desatualizado já que isso faz parte da validação da autenticação.

Uma sugestão de implementação para a plataforma.NET de desenvolvimento deste mecanismo de geração de Token seria a seguinte:

public string getAuthenticationToken(string timestamp)
{
    System.Security.Cryptography.HMACSHA256 sha256 = new System.Security.Cryptography.HMACSHA256(System.Text.ASCIIEncoding.Default.GetBytes(privateApiKey));
    Byte[] hash = sha256.ComputeHash(System.Text.ASCIIEncoding.Default.GetBytes(timestamp));
    System.Text.StringBuilder token = new System.Text.StringBuilder();
  
    foreach (byte xD in hash)
    {
       token.AppendFormat("{0:x2}", xD);
    }
  
    return token.ToString();
}

Onde private key é a senha privada da API (API Key).

No caso de precisar gerar-lo em JavaScript, pode ser utilizado uma biblioteca de criptografia JS como “CryptoJS“.

Obtenção do Token de Acesso (Access Token)

Para obter o token de acesso (acess token) será necessário usar o método “login” do serviço de autenticação (Authentication Service) da API.

login

É o método utilizado para realizar a autenticação do cliente e do usuário. Este retornará o Token de acesso (Access Token) necessário para utilizar a API.

Parâmetros do método:

Parâmetros

Tipo

Descrição

username String Nome de usuário
password String Senha de usuário
clientcode String Código de cliente (Client Code)

Parâmetros obrigatórios no cabeçalho:

Parâmetros

Tipo

Descrição

ts String Timestamp atual em GMT 0
authtoken String Token de Autenticação

Possíveis erros:

Código

Descrição

1

Access Denied

2

Invalid Client Code

3

Invalid Authentication Token

4

Authentaction Token Not Found

5

Expired Authentaction Token

100

General Unkown Error

101

Invalid Required Parameters

102

Invalid Header Format

Implementação
Será necessário enviar no cabeçalho da solicitação (request headers) dois parâmetros adicionais e esses são o Token de Autenticação (gerado a partir da senha privada) e o timestamp em GTM 0 que deve ser o mesmo que foi utilizado para gerar o Token de Autenticação.

A seguir segue um exemplo de obtenção do Token de acesso utilizando REST:

URL a utilizar:

https://api.admotion.com/AFAAuthenticationService.svc/rest/login?username=exampleuser&password=examplepassword&clientcode=exampleclientcode

Parâmetros de cabeçalho:

  • ts: Timestamp em GMT 0.
  • authtoken: Token de Autenticação gerado anteriormente.

IMPORTANTE: Por uma questão de segurança, sugere-se liberar a sessão quando não for necessário solicitar mais métodos da API. Para isso é necessário solicitar o método “logout” do Serviço de Autenticação.

logout

É o método utilizado para “liberar” ou finalizar a sessão fornecida pelo Token de Acesso e gerada previamente pelo cloinete. A finalização da sessão é útil para o controle por parte do cliente, prevenindo o acúmulo de tokens de acesso ativos e evitando alcançar o limite máximo de Tokens de acesso ativos de forma simultânea (ver sessão de limites e taxas de utilização).
É importante esclarecer que quando se finaliza a sessão, o Token de Acesso em questão não será válido.

Parâmetros do método:

Parâmetros

Tipo

Descrição

clientcode String Código de cliente

Parâmetros obrigatórios do cabeçalho:

Parámetros

Tipo

Descripción

accesstoken String Token de Acesso (Access Token)

Possíveis erros:

Código

Enum

2

Invalid Client Code

3

Authentication Token Not Found

7

Invalid Logout

100

General Unknown Error

101

Invalid Required Parameters

102

Invalid Header Format

Implementação
Será necessário enviar no cabeçalho da solicitação (request headers) o parâmetro adicional do Token de acesso (gerado a partir do método “login”).

A seguir segue um exemplo de liberação de token de acesso utilizando REST:

URL a utilizar:

https://api.admotion.com/AFAAuthenticationService.svc/rest/logout?clientcode=exampleclientcode

Parâmetro de cabeçalho:

  • accesstoken: Access Token gerado anteriormente.

Limite e taxas de utilização

As APIs da Admotion contam com certos limites ou taxas de utilização para cada cliente que as utilize. Esse controle é necessário para garantir um bom funcionamento e tempo de resposta das APIs, além de prevenir uma incorreta utilização da mesma.
É importante esclarecer que esses limites se aplicam ao uso de todos os serviços de cada API da Admotion (com exceção da autenticação). É por isso que os limites são controlados por API KEY.

As taxas de uso estão listadas abaixo:

  • A quantidade máxima permitida de solicitações em qualquer método de uma API por dia é de 10.000 por API key.
  • A quantidade máxima permitida de bytes transferidos por dia é de 100.000 (100 MB) por API Key. Isso inclui apenas o tamanho das respostas dos métodos.
  • A quantidade máxima permitida de Tokens de Acesso gerados por API Key de forma simultânea é de 1.000. Isso significa que não pode haver mais do que a quantidade de tokens de acesso ativos ao mesmo tempo gerados com a mesma API Key. Por esse motivo é importante finalizar a sessão. Esse limite previne a incorreta utilização das APIs onde, por exemplo, a autenticação é realizada por cada chamada aos métodos.

Boas práticas

Nessa sessão são descritas as práticas recomendadas para desenvolver aplicações que utilizem as APIs da Admotion.

Reutilizar Token de Acesso para múltiplas solicitações

Evitar pedir um Token de Acesso para cada solicitação. Um token de acesso pode ser utilizado sem limite até que expire. Os tokens de acesso expiram após um período de tempo desde a sua criação ou quando não é utilizado por mais de 20 minutos
Para aplicações interativas, solicite um token de acesso quando o usuário entrar em seu sistema e reutilize-o para fazer solicitações durante a sessão.
Para aplicações automatizadas, solicite um token de acesso quando for iniciada a aplicação e utilize-o para realizar solicitações durante a sua execução.

Finalizar a sessão de usuário quando não são necessárias mais petições

Utilizar o método para finalizar a sessão do usuário. Isso permitirá liberar rapidamente o token de acesso, evitando que se acumulem Access Tokens simultâneos.

Implemente o tratamento e erros

As APIs da Admotion fornecem uma ampla lista de erros. É recomendável utilizá-la para lidar com cada situação em particular.

Não realizar solicitações simultâneas aos serviços

Evitar solicitações em um loop ou use loops com temporizadores. Solicitações dentro de um loop podem fazer com que o limite de solicitações para o seu código de cliente seja atingido. Se for necessário realizar solicitações em loop, pode ser feito utilizando um temporizador que provoque uma pausa entre as solicitações.