Antes de ter acesso ao ambiente de produção da API do Banco BS2 é necessário efetuar o processo de homologação em nosso ambiente de sandbox.

Para ter acesso ao ambiente de sandbox, por favor entre em contato conosco por meio do e-mail [email protected]

📝

Nota:

Utilizamos em nossas API’s de autenticação um rate-limit, que permite até 10 requisições de token e refresh por minuto, sendo necessário realizar o gerenciamento de token.

Gerar Token de Autenticação

Para usar a API é necessário obter o token de autenticação vinculado a um usuário BS2. Para e emissão do token de acesso reproduza os seguintes passos:

1. Realizar uma requisição Basic Auth no endpoint abaixo;
2. Definir o valor password para o campo grant_type;
3. Definir o valor onboarding-pj para o campo scope;
4. Inserir usuário e senha válidos nos campos de username e password

POST /auth/oauth/v2/token

{
  "grant_type":"password",
  "scope":"onboarding-pj",
  "username":"valid_username",
  "password":"valid_password"  
}

{
  "access_token": "seu_access_token_guid",
  "token_type": "tipo_de_token",
  "expires_in": "tempo_de_expiracao_em_segundos",
  "refresh_token": "seu_refresh_token_guid",
  "scope": "onboarding-pj"
}

Parâmetros

Resposta

⚠️

Importante:

O token de autenticação é necessário para todas as requisições em nossas APIs. Fique atento ao tempo de expiração (em segundos) informado no retorno de sua requisição. Gerencie sua aplicação para que atualize o token antes de sua expiração conforme o fluxo a seguir.

Gerenciamento do Token

É necessário realizar o gerenciamento do access_token _e do _refresh_token dentro da sua aplicação.

1. Gerar um token utilizando ClientId, ClientSecret, username e password. Fluxo de geração de token descrito no passo acima. O token possui uma validade em segundos, apresentada no campo expires_in. 420 segundos em sandbox e 300 segundos em Produção.
2. Utilizando o refresh_token gerado no passo anterior, deve-se fazer o fluxo de refresh_token. Desta forma, não se deve utilizar usuário e senha para gerar novo token.
3. Antes do refresh_token expirar (10 minutos de duração), é necessário renovar o token usando fluxo de refresh_token.

Pontos Importantes

Ao gerar um token utilizando username e password, deve-se apenas gerar novos tokens usando o fluxo de refresh_token (utilizando o refresh_token e não o username e password).

Só é necessário gerar um novo token, utilizando usuário e senha, caso não consiga realizar o fluxo de refresh_token.

O campo expires_in representa a validade do token em segundos, enquanto o token estiver válido, este token deve ser utilizado.

O refresh_token possui um tempo de validade maior que a validade do token (10 min), ou seja, mesmo se o token estiver inválido por tempo e o refresh_token estiver válido, ainda é possível fazer o fluxo de refresh_token para gerar um token válido.

Quando o token estiver próximo da validade, deve-se gerar um novo token, usando um refresh_token, para assim, receber um novo token valido pelo mesmo período.

Não há limite de requisições enquanto o token estiver válido.

Quando um novo token é gerado, o token anterior passa a ser inválido.

Atualização de token

Após a geração de um token de autenticação é recomendável que o gerenciamento do seu tempo de expiração seja feito pelo fluxo de atualização de token conforme os seguintes passos:

1. Realizar uma requisição Basic Auth no endpoint abaixo;
2. Definir o valor refresh_token para o campo grant_type;
3. Definir o valor onboarding-pj para o campo scope;
4. Definir o valor do refresh_token recebido previamente para o campo refresh_token.

{
  "grant_type": "refresh_token",
  "scope": "onboarding-pj",
  "refresh_token": "refresh_token"
}

{
  "access_token": "seu_access_token_guid",
  "token_type": "tipo_de_token",
  "expires_in": "tempo_de_expiracao_em_segundos",
  "refresh_token": "seu_refresh_token_guid",
  "scope": "onboarding-pj"
}

Parâmetros

Resposta

O fluxo de atualização de token elimina a necessidade de informar usuário e senha na obtenção de um novo token de autenticação.