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.

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

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.

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 feita 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

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.

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

Resposta

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

Resposta

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

Resposta

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: