A API de autenticação do BS2 é baseada no protocolo basic auth, e as demais APIs da Cobrança são baseadas no protocolo Bearer authentication.

Para iniciar, vá em Primeiros Passos e cadastre as APIs do Cobrança que você deseja utilizar.

Gerenciamento do Token

É necessário realizar o gerenciamento do access_token e do refresh_token pelo seu sistema para que o token nunca expire. Caso o refresh_token expire é necessário acessar a plataforma BS2 Empresas e gerar novo token (vide Primeiros Passos).

Utilizamos em nossas API's de autenticação, um rate-limit que permite até 10 requisições de access_token e refresh_token por minuto.

O campo expires_in_ representa a validade do token em segundos.

O refresh_token possui um tempo de validade maior (48 horas) do que a validade do access_token (05 minutos em PRD e 07 minutos em HML). Ou seja, mesmo que o token de acesso esteja inválido e o refresh_token válido, ainda é possível fazer o fluxo de refresh_token para gerar um novo token válido.

Quando um novo token é gerado, o token anterior é imediatamento invalidado.

É importante frisar que a cada novo token gerado, um novo refresh_token também é gerado.

Refresh Token

Para realiza o refresh token, siga as instruções:

1. Gere um novo refresh_token na plataforma BS2 Empresas https://app.empresashml.bs2.com/
2. Com a API Key, API Secret e Scope construa uma requisição HTTP POST para a URL ‘/auth/oauth/v2/token’;
3. No header Authorization, utilize tipo Basic Auth e insira suas credenciais em base64;
4. No Body, insira o parâmetro scope com valor igual ao Scope obtido junto às credenciais;
5. No Body, utilize o parâmetro grant_type com texto igual a refresh_token;
6. No Body, utilize o parâmetro refresh_token com valor igual ao último refresh_token válido gerado;
7. Realize a requisição e obtenha o access_token.

Para realizar um teste prático, acesse aqui: Access Token/RefreshToken