A autenticação das APIs é realizada com a informação de um par de tokens no cabeçalho (header) das requisições. O seguinte par de tokens é esperado em cada requisição:
client_id: Identificação de acesso do cliente. Este token é gerado através de um rápido cadastro na área logada deste portal.
access_token: Armazena as regras de acesso permitidas ao client_id. Esse token pode ser obtido de forma processual, para qualquer ambiente, seguindo um fluxo de autenticação OAuth2.
Protocolo de Transporte
Todas as informações trafegadas pelas APIs são realizadas através do protocolo HTTPS, que garante um canal é seguro e dispensa a criptografia dos tokens de forma manual.
OAuth2
OAuth2 é um padrão de autenticação amplamente utilizado, que permite que sua aplicação não manipule diretamente nomes de usuários e senhas. Empresas como Google, Facebook e Twitter já utilizam esse padrão para prover o acesso a seus recursos de forma segura a aplicações de terceiros.
Abaixo você confere os passos necessários para conclusão do processo de integração OAuth2:
1. Obtenção do Client ID e Client Secret
Em nossa área logada, você deverá realizar um cadastro para obtenção do client_id e do client_secret que serão necessários no fluxo de OAuth.
2. Obtenção do Access Token
Tendo obtido o client_id e o client_secret, é hora de trocá-los pelo access_token, que permitirá o acesso às APIs da ANBIMA.
Na prática, é necessário realizar a chamada abaixo para nossa API de OAuth:
POST
https://api.anbima.com.br/oauth/access-token
HEADER
Content-Type: application/json
Authorization: Basic base64(client_id:client_secret)
REQUEST BODY
{
"grant_type": "client_credentials"
}As informações passadas para o campo Authorization devem ser codificadas em base 64. Assim, para gerar o header Authorization do par client_id = aC2yaac23 e client_secret = 1bhS45TT, por exemplo, deve ser gerada a base64 da string aC2yaac23:1bhS45TT, que resultará na chave YUMyeWFhYzIzOjFiaFM0NVRU. Desta forma, o header ficaria: ‘Authorization’: ‘Basic YUMyeWFhYzIzOjFiaFM0NVRU’.
Após essa chamada, será obtida a seguinte resposta de API de OAuth 2.0:
{
// O access_token gerado deve ser armazenado para ser utilizado nas chamadas à API
"access_token": "222rkya88",
"token_type": "access_token",
"expires_in": 3600
}Na resposta, é indicado o tempo de expiração em segundos para o access_token. Após sua expiração, o mesmo procedimento indicado deve ser repetido para obtenção de um novo token.
3. Chamadas à API
Agora que o access_token foi obtido, sua aplicação pode finalmente realizar chamadas à API utilizando os endpoints de Sandbox e Produção.
| URL de Produção | URL de Sandbox |
| https://api.anbima.com.br | https://api.sandbox.anbima.com.br |
Erros de Autenticação
Alguns erros serão tratados durante a autenticação dos Tokens (client_id e access_token). Abaixo a lista dos erros:
| Código | Tipo de erro | Descrição |
| 401 | Token inexistente/errado | Se qualquer um dos Tokens passados não existir ou estiver com algum erro (caso tenha sido alterado), será retornado o erro 401 Unauthorized. |
| 403 | Tokens revogados (inválidos) ou recursos da API indisponíveis para o plano contratado na ANBIMA | Se qualquer um dos Tokens tiver sido revogado ele será considerado inválido e será retornado o erro 403 Forbidden. Da mesma forma, caso o recurso acessado não for permitido para o plano contratado, este mesmo erro será retornado. |
Para os erros de ausência de um dos tokens e/ou token inexistente/errado, medidas podem ser tomadas do lado do desenvolvedor para validar se as informações que estão sendo passadas estão válidas. Para o erro de tokens revogados (inválidos) a única ação cabível será solicitar um novo token.