Authentication

Before having access to the production environment of Banco BS2's API, it is necessary to carry out the homologation process in our sandbox environment. To access the sandbox environment, please contact us via email [email protected]

📝

Note:

We use a rate-limit in our authentication APIs, which allows up to 10 token and refresh requests per minute, and token management is necessary.

Token Management

É necessário fazer a gestão do token de acesso e do refresh_token dentro da sua aplicação.

  1. Generate a token using ClientId, ClientSecret, username and password. Token generation flow described in the step above. The token has an expiration date in seconds, shown in the expires_in field. 420 seconds in Sandbox and 300 seconds in Production;
  2. Using the refresh_token generated in the previous step, the refresh_token flow must be made. Therefore, the username and password should not be used to generate a new token;
  3. Before the refresh_token expires (10 minutes long), it is necessary to renew the token using refresh_token flow.

Important points

When generating a token using username and password, one should only generate new tokens using the refresh_token flow (using the refresh_token and not the username and password).

It is only necessary to generate a new token using username and password, if one is unable to perform the refresh_token flow.

The expires_in field represents the token's validity in seconds. As long as the token is valid, it must be used.

The refresh_token has an expiration time greater than the validity of the token (10 min), that is, even if the token is invalid for a while and the refresh_token is valid, it is still possible to run the refresh_token flow to generate a valid token.

When the token is close to expiring, a new token must be generated, using a refresh_token, to receive a new token valid for the same period.

There is no limit on requests while the token is valid.

When a new token is generated, the previous token becomes invalid.

Authentication Token

To use the API, it is necessary to obtain the authentication token linked to a BS2 user. To issue the access token, follow these steps:

  1. Make a Basic Auth request on the endpoint below;
  2. Set the password value for the grant_type field;
  3. Set the onboarding-pj value for the scope field;
  4. Enter a valid username and password in the username and password fields.

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"
}

Parameters

NameLocated inDescriptionRequired
grant_typebodyDefine o tipo de requisiçãoYes
scopebodyDefine qual o escopo da requisiçãoYes
usernamebodyInserir um usuário previamente cadastrado no banco BS2Yes
password bodyInserir uma senha válida referente ao usuário informado no campo acimaYes

Response

CodeDescription
200Success
400Bad Request
401Unauthorized

SANDBOXPRODUCTION
RequestsRequest URL from the Banco BS2 teamhttps://api.bs2.com:8443/auth/oauth/v2/token

⚠️

Important:

The authentication token is required for all requests to our APIs. Pay attention to the expiration time (in seconds) informed when returning your request. Manage your application so that it updates the token before its expiration as per the following flow.

Token update

After generating an authentication token, it is recommended that its expiration time be managed using the token update flow as per the following steps:

  1. Perform a Basic Auth request on the endpoint below;
  2. Set the refresh_token value for the grant_type field;
  3. Set the onboarding-pj value for the scope field;
  4. Set the amount of the previously received refresh token for the refresh_token field.

POST /auth/oauth/v2/token

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

Resposta
{
  "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"
}

Parameters

NameLocated inDescriptionRequired
grant_typebodyDefines the type of the requestYes
scopebodyDefines the scope of the requestYes
refresh_tokenbodyInsert the previously received refresh tokenYes

Response

CodeDescription
200Success
400Bad Request
401Unauthorized

The token update flow eliminates the need to enter a username and password when obtaining a new authentication token.

How client registration via API works

The Onboarding registration API provides the option for partners to invite their clients to open an account through the Powered by BS2 platform.

The API generates an invitation link that the client uses to start the Onboarding process. This link can be sent directly to the client's email provided by the partner. Through this link, the client creates their username to access the platform.

If the partner has provided all the mandatory information for us to carry out an account opening analysis, the client only needs to accept the platform's terms of use and wait for an email notification as to whether or not their account can be opened.

Pre-registration API

There are 2 APIs that the partner can use to invite their clients: the Pre-Registration API and the Complete Registration API.

The Pre-registration API is intended for partners who do not have all the mandatory information to open an account. In this scenario, the partner sends only the data it has about its client in the body of the request.

After the client creates the username, the client will need to go through all the onboarding pages, providing the data that the partner did not previously send. The data sent by the partner will appear filled in for the client, in order to facilitate the completion of onboarding.

Complete Registration API

In this API, the partner has all the mandatory information requested to open an account.

The partner can use this API to speed up the onboarding process for the client.

After the client uses the link to create the username, the client will be redirected to the terms acceptance page. By accepting the terms, the onboarding process is completed and the data is sent for analysis.

Client Pre-registration Contract

POST /pj/onboarding/v1/fluxos/Bs2PJ/parceiros/cadastros/clientes

{
    "notificarCliente": false,
    "empresa": {
        "cnpj": "string",
        "naturezaJuridica": "string",
        "autorizacaoConsultaCnpj": false,
        "fundadaEm": "2022-10-9T19:31:48.319Z",
        "razaoSocial": "string",
        "nomeFantasia": "string",
        "faturamentoMensal": 0,
        "endereco": {
            "logradouro": "string",
            "numero": "string",
            "complemento": "string",
            "bairro": "string",
            "cidade": "string",
            "estado": "string",
            "cep": "string"
        },
        "socios": [
        {
            "cpf": "string",
            "nome": "string",
            "nascimento": "2022-10-9T19:31:48.319Z",
            "telefone": "string",
            "email": "string",
            "nomeMae": "string",
            "participacao": 0,
            "usuario": false,
            "tipoDocumentoSocio": "string",
            "documentoIdentificacao": "string",
            "dataExpeditor": "2022-10-9T19:31:48.319Z",
            "orgaoExpeditor": "string",
            "ufExpeditor": "string",
            "endereco": {
                "logradouro": "string",
                "numero": "string",
                "complemento": "string",
                "bairro": "string",
                "cidade": "string",
                "estado": "string",
                "cep": "string"
            },
            "nif": "string",
            "nacionalidade": "string"
        }
        ],
        "representanteLegal": {
            "nome": "string",
            "nascimento": "2022-10-9T19:31:48.319Z",
            "cpf": "string",
            "email": "string",
            "telefone": "string",
            "nomeMae": "string",
            "endereco": {
                "logradouro": "string",
                "numero": "string",
                "complemento": "string",
                "bairro": "string",
                "cidade": "string",
                "estado": "string",
                "cep": "string"
            }
        }
    }
}
{
    "clienteId": "string",
    "link": "string"
}

Parameters

NameLocated inRequiredSchema
bodybodySimbs2.pJ.clientes.apis.web.forFrontend.parceiros.cadastrar.compartilhados.ClienteParaCadastrar

Response

CodeDescriptionSchema
201Successbs2.pJ.clientes.apis.web.forFrontend.parceiros.cadastrar.clientes.CadastrarClienteResponse
400Bad Requestbs2.pJ.clientes.apis.web.forFrontend.compartilhados.DetalheBadRequest

Client Complete Registration Contract

POST /pj/onboarding/v1/fluxos/Bs2PJ/parceiros/cadastros

{
    "notificarCliente": false,
    "empresa": {
        "cnpj": "string",
        "naturezaJuridica": "string",
        "autorizacaoConsultaCnpj": false,
        "fundadaEm": "2022-10-9T19:31:48.319Z",
        "razaoSocial": "string",
        "nomeFantasia": "string",
        "faturamentoMensal": 0,
        "endereco": {
            "logradouro": "string",
            "numero": "string",
            "complemento": "string",
            "bairro": "string",
            "cidade": "string",
            "estado": "string",
            "cep": "string"
        },
        "socios": [
        {
            "cpf": "string",
            "nome": "string",
            "nascimento": "2022-10-9T19:31:48.320Z",
            "telefone": "string",
            "email": "string",
            "nomeMae": "string",
            "participacao": 0,
            "usuario": false,
            "tipoDocumentoSocio": "string",
            "documentoIdentificacao": "string",
            "dataExpeditor": "2022-10-9T19:31:48.320Z",
            "orgaoExpeditor": "string",
            "ufExpeditor": "string",
            "endereco": {
                "logradouro": "string",
                "numero": "string",
                "complemento": "string",
                "bairro": "string",
                "cidade": "string",
                "estado": "string",
                "cep": "string"
            },
            "nif": "string",
            "nacionalidade": "string"
        }
        ],
        "representanteLegal": {
            "nome": "string",
            "nascimento": "2022-10-9T19:31:48.320Z",
            "cpf": "string",
            "email": "string",
            "telefone": "string",
            "nomeMae": "string",
            "endereco": {
                "logradouro": "string",
                "numero": "string",
                "complemento": "string",
                "bairro": "string",
                "cidade": "string",
                "estado": "string",
                "cep": "string"
            }
        }
    }
}
{
    "clienteId": "string",
    "link": "string"
}

Parameters

NameLocated inRequiredSchema
bodybodyYesbs2.pJ.clientes.apis.web.forFrontend.parceiros.cadastrar.compartilhados.ClienteParaCadastrar

Response

CodeDescriptionSchema
201Successbs2.pJ.clientes.apis.web.forFrontend.parceiros.cadastrar.emBackground.CadastrarClienteResponse
400Bad Requestbs2.pJ.clientes.apis.web.forFrontend.compartilhados.DetalheBadRequest

Uploading articles of association and partner documentation

After completing a complete registration, the documents need to be sent via API. If the documents are not sent and the client completes the registration, the client will fall into the flow of pending documents. The client will be asked, via email, to return to the onboarding platform and send the requested documentation.

How to upload via API

Documents must be sent via POST multipart/form-data. Always use the CNPJ or CPF value to which the file corresponds in the name field.

The CNPJ and CPF amounts must match those reported in the registration APIs. One (1) file must be sent at a time. If the identification document of one of the partners is double-sided, there will be 2 requests for the same CPF number.

We recommend that files do not exceed 5MB in size.

Below is an example in angular of how the request body is prepared.

const  formData = new  FormData();
formData.append(this.form.get('cnpj').value, this.form.get('doc').value);

Documents must be in the format below.

  • image/png
  • image/jpg
  • image/jpeg
  • application/pdf

Contract for uploading documents

POST /pj/onboarding/v1/fluxos/Bs2PJ/parceiros/cadastros


--curl
"POST": "/pj/onboarding/v1/fluxos/Bs2PJ/parceiros/cadastros/clientes/{clienteId}/documentos"

Parameters

NameLocated inDescriptionRequiredSchema
clienteIdpathID do cliente gerado após executar as APIs de cadastroYesstring (uuid)

Response

CodeDescriptionSchema
204Success
400Bad Requestbs2.pJ.clientes.apis.web.forFrontend.compartilhados.DetalheBadRequest

Status check

The status check provides the partner with the progress of their client's account opening process. From generating the invitation link to its homologation, the steps in the account opening process are described below:

StatusDescrição
AguardandoInicioClient has not yet consumed the invitation link
EmAndamentoClient started the onboarding process, but has not yet completed it
CadastroFinalizadoClient has completed registration and data is being processed for analysis
AnalisePendenteClient data has been successfully processed and the data is under analysis
DocumentoPendenteComplete client documentation was not initially sent by the partner or invalid documentation was sent
AprovadoClient analysis has been completed and the account will be opened
ReprovadoUnable to open account