Autenticação

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.

Gerenciamento de Token

É necessário fazer a gestão do token de acesso 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 de tempo.

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.

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

NomeLocalizado emDescriçãoRequerido
grant_typebodyDefine o tipo de requisiçãoSim
scopebodyDefine qual o escopo da requisiçãoSim
usernamebodyInserir um usuário previamente cadastrado no banco BS2Sim
password bodyInserir uma senha válida referente ao usuário informado no campo acimaSim

Resposta

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

SANDBOXPRODUÇÃO
RequisiçõesSolicitar URL ao time BS2https://api.bs2.com:8443/auth/oauth/v2/token

⚠️

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.

Token de Atualização

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

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

Parâmetros

NomeLocalizado emDescriçãoRequerido
grant_typebodyDefine o tipo de requisiçãoSim
scopebodyDefine qual o escopo da requisiçãoSim
refresh_tokenbodyInserir o refresh token recebido previamenteSim

Resposta

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

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.

Como funciona o cadastro de clientes via API

A API de cadastros do onboarding disponibiliza a opção do parceiro convidar seus clientes a abrir uma conta por meio da plataforma Powered By Bs2.

A API gera um link de convite que o cliente utiliza para iniciar o processo de onboarding. Este link pode ser enviado direto para o e-mail do cliente informado pelo parceiro. Por meio deste link o cliente cria seu usuário de acesso a plataforma.

Se o parceiro forneceu todas as informações obrigatórias para realizarmos uma análise de abertura de contas, o cliente só precisa aceitar os termos de uso da plataforma e aguardar e-mail de notificação se sua conta pode ou não ser aberta.

API de Pré-cadastro

Existem 2 APIs que o parceiro pode utilizar para convidar seus clientes: A API de Pré-cadastro e a API de Cadastro completo.

A API de Pré-cadastro é destinada aos parceiros que não possuem todas as informações obrigatórias para a abertura de conta. Neste cenário, o parceiro envia no corpo da requisição apenas os dados que possui de seu cliente.

Após o cliente criar seu usuário, ele precisará avançar por todas as páginas do onboarding, informando os dados que o parceiro não enviou previamente. Os dados enviados pelo parceiro aparecerão preenchidos para o cliente, de modo a facilitar a conclusão do onboarding.

API de Cadastro completo

Nesta API, o parceiro possui em mãos todas as informações obrigatórias solicitadas para uma abertura de conta.

O parceiro pode utilizar esta API para agilizar o processo de onboarding de seu cliente.

Após a utilização do link pelo cliente para criação de seu usuário, o cliente será encaminhado para a página de aceite de termos. Aceitando os termos, o processo de onboarding é finalizado e os dados são encaminhados para análise.

Contrato para Pré-cadastro de Clientes

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

Parâmetros

NomeLocalizado emRequeridoSchema
bodybodySimbs2.pJ.clientes.apis.web.forFrontend.parceiros.cadastrar.compartilhados.ClienteParaCadastrar

Resposta

CódigoDescriçãoSchema
201Successbs2.pJ.clientes.apis.web.forFrontend.parceiros.cadastrar.clientes.CadastrarClienteResponse
400Bad Requestbs2.pJ.clientes.apis.web.forFrontend.compartilhados.DetalheBadRequest

Contrato para Cadastro Completo de Clientes

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

Parâmetros

NomeLocalizado emRequeridoSchema
bodybodySimbs2.pJ.clientes.apis.web.forFrontend.parceiros.cadastrar.compartilhados.ClienteParaCadastrar

Resposta

CódigoDescriçãoSchema
201Successbs2.pJ.clientes.apis.web.forFrontend.parceiros.cadastrar.emBackground.CadastrarClienteResponse
400Bad Requestbs2.pJ.clientes.apis.web.forFrontend.compartilhados.DetalheBadRequest

Upload de contrato social e documentação de sócios

Após realizar um cadastro completo, os documentos precisam ser enviados via API. Caso os documentos não sejam enviados e o cliente finalize o cadastro, o cliente cairá no fluxo de documentos pendentes. Será solicitado do cliente, via e-mail, que retorne a plataforma do onboarding e envie a documentação solicitada.

Como realizar o upload via API

Os documentos deverão ser enviados via POST multipart/form-data. Use sempre no campo name, o valor do CNPJ ou CPF que o arquivo corresponde.

Os valores de CNPJ e CPF precisam corresponder ao informado nas APIs de cadastro. É preciso enviar 1 arquivo por vez. Se o documento de identificação de um dos sócios possuir frente e verso, serão 2 requisições para o mesmo CPF.

Recomentamos que os arquivos não ultrapassem 5mb de tamanho.

Abaixo um exemplo em angular de como é preparado o corpo da requisição.

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

Os documentos precisam estar no formato abaixo.

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

Contrato para Upload de Documentos

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


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

Parâmetros

NomeLocalizado emDescriçãoRequeridoSchema
clienteIdpathID do cliente gerado após executar as APIs de cadastroSimstring (uuid)

Resposta

CódigoDescriçãoSchema
204Success
400Bad Requestbs2.pJ.clientes.apis.web.forFrontend.compartilhados.DetalheBadRequest

Consulta de status

A consulta de status fornece ao parceiro o andamento do processo de abertura de conta de seu cliente. Deste a geração do link de convite até sua aprovação, as etapas do processo de abertura de contas são descritas abaixo:

StatusDescrição
AguardandoInicioCliente ainda não consumiu link de convite
EmAndamentoCliente iniciou o processo de onboarding, mas ainda não concluiu
CadastroFinalizadoCliente finalizou o cadastro e os dados estão sendo processados para análise
AnalisePendenteOs dados do cliente foram processados com sucesso e seus dados estão em análise
DocumentoPendenteA documentação completa do cliente não foi inicialmente enviada pelo parceiro ou foi enviada uma documentação inválida
AprovadoAnálise do cliente foi concluída e sua conta será aberta
ReprovadoNão foi possível realizar a abertura da conta