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

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 ?

Api Onboarding - Versões anteriores

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

Nome Localizado em Descrição Requerido
grant_type body Define o tipo de requisição Sim
scope body Define qual o escopo da requisição Sim
username body Inserir um usuário previamente cadastrado no banco BS2 Sim
password body Inserir uma senha válida referente ao usuário informado no campo acima Sim

Resposta

Código Descrição
200 Success
400 Bad Request
401 Unauthorized
  SandBox Produção
Requisições Solicitar URL ao time BS2 https://api.bs2.com:8443/auth/oauth/v2/token

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

Nome Localizado em Descrição Requerido
grant_type body Define o tipo de requisição Sim
scope body Define qual o escopo da requisição Sim
refresh_token body Inserir o refresh token recebido previamente Sim

Resposta

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

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": "2021-6-15T21:38:57.128Z",
        "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": "2021-6-15T21:38:57.128Z",
            "telefone": "string",
            "email": "string",
            "nomeMae": "string",
            "participacao": 0,
            "usuario": false,
            "tipoDocumentoSocio": "string",
            "documentoIdentificacao": "string",
            "dataExpeditor": "2021-6-15T21:38:57.128Z",
            "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": "2021-6-15T21:38:57.128Z",
            "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

Nome Localizado em Descrição Requerido Schema
body body   Sim bs2.pJ.clientes.apis.web.forFrontend.parceiros.cadastrar.compartilhados.ClienteParaCadastrar

Resposta

Código Descrição Schema
201 Success bs2.pJ.clientes.apis.web.forFrontend.parceiros.cadastrar.clientes.CadastrarClienteResponse
400 Bad Request [ bs2.pJ.clientes.apis.web.forFrontend.compartilhados.DetalheBadRequest ]

Contrato para Cadastro Completo de Clientes


{
    "notificarCliente": false,
    "empresa": {
        "cnpj": "string",
        "naturezaJuridica": "string",
        "autorizacaoConsultaCnpj": false,
        "fundadaEm": "2021-6-15T21:38:57.129Z",
        "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": "2021-6-15T21:38:57.129Z",
            "telefone": "string",
            "email": "string",
            "nomeMae": "string",
            "participacao": 0,
            "usuario": false,
            "tipoDocumentoSocio": "string",
            "documentoIdentificacao": "string",
            "dataExpeditor": "2021-6-15T21:38:57.129Z",
            "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": "2021-6-15T21:38:57.129Z",
            "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

Nome Localizado em Descrição Requerido Schema
body body   Sim bs2.pJ.clientes.apis.web.forFrontend.parceiros.cadastrar.compartilhados.ClienteParaCadastrar

Resposta

Código Descrição Schema
201 Success bs2.pJ.clientes.apis.web.forFrontend.parceiros.cadastrar.emBackground.CadastrarClienteResponse
400 Bad Request [ bs2.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


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

Parâmetros

Nome Localizado em Descrição Requerido Schema
clienteId path ID do cliente gerado após executar as APIs de cadastro Sim string (uuid)

Resposta

Código Descrição Schema
204 Success  
400 Bad Request [ bs2.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:

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

Nome Localizado em Descrição Requerido Schema
clienteId path ID do cliente gerado após executar as APIs de cadastro Sim string (uuid)

Resposta

Código Descrição Schema
200 Success bs2.pJ.clientes.apis.web.forFrontend.parceiros.consultarStatus.StatusParceiroCliente
400 Bad Request [ bs2.pJ.clientes.apis.web.forFrontend.compartilhados.DetalheBadRequest ]

Models

Endereco

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

Nome Tipo Descrição Tamanho Requerido
logradouro string   100 Sim
numero string   8 Sim
complemento string   50 Não
bairro string   50 Sim
cidade string   30 Sim
estado string   2 Sim
cep string   8 Sim

Socio

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

Nome Tipo Descrição Tamanho Requerido
cpf string   11 Sim
nome string   155 Sim
nascimento dateTime   - Sim
telefone string   15 Sim
email string   50 Sim
nomeMae string   155 Sim
participacao double Percentual de participação no quadro societário da empresa - Sim
usuario boolean Se o representante legal não for informado, definir qual sócio será o usuário master da conta - Não
tipoDocumentoSocio string Documentos disponíveis: RG, CNH ou RNE - Sim
documentoIdentificacao string   50 Sim
dataExpeditor dateTime   - Sim
orgaoExpeditor string   10 Sim
ufExpeditor string   2 Sim
endereco bs2.pJ.clientes.apis.web.forFrontend.parceiros.cadastrar.compartilhados.Endereco   - Sim
nif string Número de Identificação Fiscal 9 Não
nacionalidade string   50 Não

RepresentanteLegal

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

Nome Tipo Descrição Tamanho Requerido
nome string   155 Sim
nascimento dateTime   - Sim
cpf string   11 Sim
email string   50 Sim
telefone string   15 Sim
nomeMae string   100 Sim
endereco bs2.pJ.clientes.apis.web.forFrontend.parceiros.cadastrar.compartilhados.Endereco   - Sim

Empresa

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

Nome Tipo Descrição Tamanho Requerido
cnpj string   14 Sim
naturezaJuridica string Naturezas disponíveis: MEI, EIRELI, LTDA e ME - Sim
autorizacaoConsultaCnpj boolean   - Não
fundadaEm dateTime Data de constituição da empresa - Sim
razaoSocial string   155 Sim
nomeFantasia string   155 Não
faturamentoMensal double   - Sim
endereco bs2.pJ.clientes.apis.web.forFrontend.parceiros.cadastrar.compartilhados.Endereco   - Sim
socios [ bs2.pJ.clientes.apis.web.forFrontend.parceiros.cadastrar.compartilhados.Socio ]   - Sim
representanteLegal bs2.pJ.clientes.apis.web.forFrontend.parceiros.cadastrar.compartilhados.RepresentanteLegal Administrador da empresa que será o usuário master da conta. Informar apenas se o administrador NÃO fizer parte do quadro societário da empresa - Não

ClienteParaCadastrar

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

Nome Tipo Descrição Tamanho Requerido
notificarCliente boolean Se verdadeiro, será enviado um e-mail para o cliente com o link de acesso para iniciar o processo de onboarding. O link não será devolvido no response da API. Caso falso, nenhum e-mail será enviado ao cliente e o link será devolvido no response da API - Não
empresa bs2.pJ.clientes.apis.web.forFrontend.parceiros.cadastrar.compartilhados.Empresa   - Sim

CadastrarClienteResponse

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

Nome Tipo Descrição Tamanho Requerido
clienteId string (uuid) Identificador do cliente cadastrado - Não
link string Link de acesso para o cliente criar seu usuário e iniciar o processo de onboarding. - Não

DetalheBadRequest

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

Nome Tipo Descrição Tamanho Requerido
tag string Chave para auxiliar na localização do erro - Não
descricao string Descrição do erro ocorrido - Não

CadastrarClienteResponse

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

Nome Tipo Descrição Tamanho Requerido
clienteId string (uuid) Identificador do cliente cadastrado - Não
link string Link de acesso para o cliente criar seu usuário e iniciar o processo de onboarding. - Não

StatusParceiroCliente

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

Nome Tipo Descrição Tamanho Requerido
statusCliente string Status do andamento do processo de onboarding do cliente - Não
conta string Conta corrente aberta quando o status do cliente for Aprovado - Não

Precisa de mais informações?

Se você ainda tem dúvidas, entre em contato conosco, estamos prontos para atende-lo:

empresas@bs2.com