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 através 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.

Aplicação de Consentimento

Deve-se cadastrar uma aplicação para o fluxo de consentimento, a partir dessa aplicação que seram feitas as requisições para solicitar o consentimento e obter o token de acesso.

É obrigatório informar a url de redirecionamento (callback url).

As funcionalidades selecionadas serão apresentadas na tela do consentimento para confirmação do cliente.

Obtenção do token

Para iniciar o fluxo de consentimento é necessário utilizar a url abaixo com os respectivos parâmetros.

GET - /api-banking/auth/oauth/v2/authorize

Parâmetros

Ao acessar a url do consentimento com os parâmetros válidos, a página abaixo será carregada para a autenticação do usuário.

Após validado usuário e senha, será solicitada a confirmação do consentimento com 2ª fator de autenticação (token sms).

Com o token validado, redirecionaremos para seu endpoint com o código de autorização.

O método do seu endpoint deve ser GET e estar preparado para receber os seguintes parâmetros:

Para obter o token de acesso a partir desse código, deve ser feito o fluxo de Authorization Code.

Gerenciamento de Token

É necessário fazer a gestão do token de acesso e do refresh_token dentro do seu sistema.

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

Caso perca o tempo de validade do refresh_token, será necessário refazer o fluxo de consentimento.

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

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

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

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

Pontos Importantes

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

O token de acesso é necessário para todas as requisições em nossas APIs.

Refresh Token

1. Realizar uma requisição Basic Auth no endpoint abaixo com apikey e apisecret da aplicação.

2. Informar o valor refresh_token para o campo grant_type.

3. Informar o escopo da aplicação para o campo scope.

4. Informar o valor do refresh token recebido previamente para o campo refresh_token.

POST /auth/oauth/v2/token

Headers
Content-Type: application/x-www-form-urlencoded
Authorization: basic auth com apikey e apisecret

Request body

grant_type: refresh_token
scope: escopo da aplicacao
refresh_token: último refresh token gerado (guid)

Response body

curl -k 
-H "Authorization: Basic bDczNDQ4ZDYzNGE3NDQ0NjU4ODI4ZWM1OTE4Mzk0ODc4Mjo5YjBkZGE1NDQxZDM0NmMwYjY5MWIyNzg1YTg1NWMzMg==" 
-d "grant_type=refresh_token&scope=saldo&refresh_token=04a8fb41-e28b-4956-b29f-ca59f47ec448" 
-X POST https://example.bancobonsucesso.com.br/auth/oauth/v2/token 

POST /auth/oauth/v2/token HTTP/1.1

Host: example.bancobonsucesso.com.br

Authorization: Basic bDczNDQ4ZDYzNGE3NDQ0NjU4ODI4ZWM1OTE4Mzk0ODc4Mjo5YjBkZGE1NDQxZDM0NmMwYjY5MWIyNzg1YTg1NWMzMg==

Content-Type: application/x-www-form-urlencoded

HTTP/1.1 200 OK

Content-Type: application/json;charset=UTF-8

Respostas

Authorization Code

1. Realizar uma requisição Basic Auth no endpoint abaixo com API Key e API Secret da aplicação.

2. Informar o valor authorization_code para o campo grant_type.

3. Informar o código de autorização recebido para o campo code.

4. Informar o endpoint utilizado para receber o código de autorização para o campo redirect_uri.

POST /auth/oauth/v2/token

Headers
Content-Type: application/x-www-form-urlencoded
Authorization: basic auth com apikey e apisecret

Request body

grant_type: authorization_code
code: código de autorização recebido na url de redirecionamento (callback url) 
redirect_uri: Seu endpoint cadastrado para receber o código de autorização

`

Response body

curl -k 
-H "Authorization: Basic bDczNDQ4ZDYzNGE3NDQ0NjU4ODI4ZWM1OTE4Mzk0ODc4Mjo5YjBkZGE1NDQxZDM0NmMwYjY5MWIyNzg1YTg1NWMzMg==" 
-d "grant_type=authorization_code&scope=saldo&redirect_uri=https://api.bs2.com/exemplo/consent" 
-X POST https://example.bancobonsucesso.com.br/auth/oauth/v2/token 

POST /auth/oauth/v2/token HTTP/1.1

Host: example.bancobonsucesso.com.br

Authorization: Basic bDczNDQ4ZDYzNGE3NDQ0NjU4ODI4ZWM1OTE4Mzk0ODc4Mjo5YjBkZGE1NDQxZDM0NmMwYjY5MWIyNzg1YTg1NWMzMg==

Content-Type: application/x-www-form-urlencoded

HTTP/1.1 200 OK

Content-Type: application/json;charset=UTF-8

Precisa de mais informações?

Se você ainda tem dúvidas, entre em contato conosco, estamos prontos para atendê-lo:

Acesse o link https://www.bancobs2.com.br/bs2cash/ e solicite o contato com um dos nossos especialistas.