Introdução Consentimento - bs2.pj.apibanking.consentimento - Versão: 2

Introdução Consentimento

Fluxo de Consentimento

O fluxo de consentimento é a forma de você fazer requisições em nome do seu cliente.

Quem pode utilizar?

Todos os parceiros do banco BS2.

Quais são requisitos para a utilização?

Autenticação Consentimento

Autenticação Consentimento

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.

image

Obtenção do Token

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

Parâmetros

Nome Localizado em Descrição Obrigatório
response_type query Informar code Sim
client_id query API Key da aplicação cadastrada para o consentimento Sim
scope query Escopo da aplicação Sim
state query Campo livre para identificação do cliente/usuário Sim
redirect_uri query Endpoint para receber o código de autorização (authorization_code) Sim

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.

image

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

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:

Nome Localizado em Obrigatório
code query Sim
state query Sim

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

image

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.

Caso tenha dúvidas sobre como cadastrar uma aplicação clique aqui.

Homologação: https://apihmz.bancobonsucesso.com.br

Produção: https://api.bs2.com

Refresh Token

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

1.2 Informar o valor refresh_token para o campo grant_type.

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

1.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

{
 "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": "escopo da aplicação"
}

Exemplo:

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

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

Host: apihmz.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

{
 "access_token":"61d741ab-3f4b-4623-8887-ecc943d8ce71",
 "token_type":"Bearer",
 "expires_in":420,
 "refresh_token":"f386e33a-d889-4221-9dba-fc8153112d1d",
 "scope":"saldo"
} 

Respostas

Código Descrição
200 Success
400 Bad Request
401 Unauthorized

Authorization Code

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

1.2 Informar o valor authorization_code para o campo grant_type.

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

1.3 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

{
 "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": "escopo da aplicação"
}

Exemplo:

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

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

Host: apihmz.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

{
 "access_token":"61d741ab-3f4b-4623-8887-ecc943d8ce71",
 "token_type":"Bearer",
 "expires_in":420,
 "refresh_token":"f386e33a-d889-4221-9dba-fc8153112d1d",
 "scope":"saldo"
} 

null

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.