As APIs do Cobrança são baseadas no protocolo OAuth 2, especificamente, com fluxo de refresh_token.

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 (veja a página Primeiros Passos).

Utilizamos em nossas APIs 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 (5 minutos em PRD e 7 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 é imediatamente invalidado.

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

⚠️

Importante:

Ao gerar um novo access_token a chave existente será automaticamente invalidada, caso exista.

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 Body, utilize os valores recuperados da aplicação para preencher os parâmetros abaixo:
   1. scope com valor igual ao Scope obtido junto às credenciais;
   2. grant_type com texto igual a refresh_token;
   3. refresh_token com valor igual ao último refresh_token válido gerado;
   4. client_id com valor de client_id;
   5. client_secret com valor de client_secret;
4. Realize a requisição e obtenha o access_token.

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