Onboarding - bs2.pj.clientes.forFrontend - Versão: 1

Onboarding

O que é API de Onboarding?

API Onboarding disponibiliza operações relacionadas a cadastro de clientes através da parceria Powered By Bs2

• Autenticação
• Como funciona o cadastro de clientes via API
• Contrato para Pré-cadastro de Clientes
• Contrato para Cadastro Completo de Clientes
• Upload de Documentos
• Contrato para Upload de Documentos
• Consulta de Status
• Contrato para Consulta de Status

Quem pode usar a API de Onboarding

Todos os clientes e parceiros do banco BS2.

Quais são requisitos para a utilização da API de Onboarding ?

• Ser cliente do banco BS2
• Ter um token de acesso válido

Api Onboarding - Versões anteriores

• V1 URL antiga Acesse aqui os detalhes desta versão anterior - 02/2021

Autenticação

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 descrito abaixo:

Gerenciamento de Token

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

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

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

1.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.1 Realizar uma requisição Basic Auth no endpoint abaixo

1.2 Definir o valor password para o campo grant_type

1.3 Definir o valor onboarding-pj para o campo scope

1.4 Inserir usuário e senha válidos nos campos de username e password

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

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.1 Realizar uma requisição Basic Auth no endpoint abaixo

1.2 Definir o valor refresh_token para o campo grant_type

1.3 Definir o valor onboarding-pj para o campo scope

1.4 Definir o valor do refresh token recebido previamente para o campo refresh_token

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

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

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

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

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

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

Status	Descrição
AguardandoInicio	Cliente ainda não consumiu link de convite
EmAndamento	Cliente iniciou o processo de onboarding, mas ainda não concluiu
CadastroFinalizado	Cliente finalizou o cadastro e os dados estão sendo processados para análise
AnalisePendente	Os dados do cliente foram processados com sucesso e seus dados estão em análise
DocumentoPendente	A documentação completa do cliente não foi inicialmente enviada pelo parceiro ou foi enviada uma documentação inválida
Aprovado	Analise do cliente foi concluída e sua conta será aberta
Reprovado	Não foi possível realizar a abertura da conta

Contrato para Consulta de Status

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

{
    "statusCliente": "string",
    "conta": "string"
}

Parâmetros

Resposta

Models

Endereco

bs2.pJ.clientes.apis.web.forFrontend.parceiros.cadastrar.compartilhados.Endereco

Socio

bs2.pJ.clientes.apis.web.forFrontend.parceiros.cadastrar.compartilhados.Socio

RepresentanteLegal

bs2.pJ.clientes.apis.web.forFrontend.parceiros.cadastrar.compartilhados.RepresentanteLegal

Empresa

bs2.pJ.clientes.apis.web.forFrontend.parceiros.cadastrar.compartilhados.Empresa

ClienteParaCadastrar

bs2.pJ.clientes.apis.web.forFrontend.parceiros.cadastrar.compartilhados.ClienteParaCadastrar

CadastrarClienteResponse

bs2.pJ.clientes.apis.web.forFrontend.parceiros.cadastrar.clientes.CadastrarClienteResponse

DetalheBadRequest

bs2.pJ.clientes.apis.web.forFrontend.compartilhados.DetalheBadRequest

CadastrarClienteResponse

bs2.pJ.clientes.apis.web.forFrontend.parceiros.cadastrar.emBackground.CadastrarClienteResponse

StatusParceiroCliente

bs2.pJ.clientes.apis.web.forFrontend.parceiros.consultarStatus.StatusParceiroCliente