Visão geral
Abertura de conta titular pelo integrador na plataforma BaaS. O fluxo é stateful: guarde proposalId e personId entre chamadas. Contrato HTTP: Onboarding na Referência API e mapa de endpoints.
Cada recurso segue o padrão POST (abre) + PATCH (completa). A aprovação da conta é assíncrona: não há endpoint síncrono de “aprovar conta”.
Fluxo completo
Depois da proposta, o integrador escolhe pessoa física ou pessoa jurídica. São caminhos excludentes: uma proposta segue PF ou PJ, não os dois.
flowchart TD
subgraph proposta["Proposta (obrigatória)"]
P1["POST /proposals"] --> P2["GET /proposals/{proposalId}"]
P2 --> P3["PATCH cadastral"]
P3 --> P4["GET /proposals/{proposalId}"]
P4 --> P5["PATCH OTP"]
end
P5 --> escolha{"PF ou PJ?"}
escolha -->|Pessoa física| F1["POST /natural-persons"]
F1 --> F2["GET /natural-persons/{personId}"]
F2 --> F3["PATCH KYC PF"]
escolha -->|Pessoa jurídica| J1["POST /legal-persons"]
J1 --> J2["GET /legal-persons/{personId}"]
J2 --> J3["PATCH KYC PJ"]
F3 --> A["GET polling análise"]
J3 --> A
A --> W["Webhook AccountCredentials"]
Pré-requisito em todas as chamadas: Bearer da plataforma BaaS + HMAC.
Fase 1: Proposta
Registra o CPF do titular, senha, termos e OTP. Cinco operações HTTP na sequência do diagrama (um POST e dois PATCH de escrita, mais GET entre eles). Detalhes: Propostas.
| Operação | Path |
|---|---|
| POST | /api/v2/baas/onboardings/proposals |
| GET | /api/v2/baas/onboardings/proposals/{proposalId} |
| PATCH | /api/v2/baas/onboardings/proposals/{proposalId} |
Só o POST não libera a fase seguinte. O titular só existe após o PATCH cadastral completo.
Fase 2: PF ou PJ
Escolha um caminho conforme o tipo de conta.
Pessoa física
Guia: Pessoa física.
| Operação | Path |
|---|---|
| POST | /api/v2/baas/onboardings/{proposalId}/natural-persons |
| GET | /api/v2/baas/onboardings/{proposalId}/natural-persons/{personId} |
| PATCH | /api/v2/baas/onboardings/{proposalId}/natural-persons/{personId} |
O cadastro entra na esteira quando accepted_terms_at e files[] estão no PATCH (termos da conta PF, distintos da proposta).
Pessoa jurídica
Guia: Pessoa jurídica.
| Operação | Path |
|---|---|
| POST | /api/v2/baas/onboardings/{proposalId}/legal-persons |
| GET | /api/v2/baas/onboardings/{proposalId}/legal-persons/{personId} |
| PATCH | /api/v2/baas/onboardings/{proposalId}/legal-persons/{personId} |
O titular do CPF da proposta é o responsável pela empresa. files[] deve bater com company_type.
Fase 3: Análise e conta
Após o PATCH de PF ou PJ com accepted_terms_at, a análise KYC é assíncrona. Consulte o personId com GET até concluir.
Quando aprovado:
| Evento | Detalhe |
|---|---|
| Conta | Criada com chave Pix EVP |
| Webhook plataforma | AccountCredentials + created com client_id, client_secret e scopes |
| Webhooks da conta | Titular cadastra em /api/v2/baas/webhooks. Ver Webhooks da conta |
Cadastre o webhook da plataforma antes da análise para receber credenciais.
Em reprovação KYC, reenvie só os files[] corrigidos no PATCH da pessoa.
Próximo passo: Conta BaaS.
Pré-requisitos
| Item | Detalhe |
|---|---|
| Token plataforma | Scopes baas.onboarding-* conforme a operação |
| HMAC | Obrigatório na maioria das rotas /api/v2/baas/... |
| Webhook plataforma | AccountCredentials + created antes da análise |
IDs a guardar
| ID | Onde obter | Uso |
|---|---|---|
proposalId | POST /proposals | Path da proposta e de PF/PJ |
personId | POST de PF ou PJ | GET e PATCH da pessoa |
Erros frequentes
| Situação | Resposta típica |
|---|---|
| PF/PJ sem proposta concluída | 404 Customer not found |
company_type não bate com files[] | 422 Invalid documents from company type |
| OTP da proposta ausente | Reprovação em compliance |
password_confirmation ≠ password | 422 |
| Assinatura HMAC inválida | Invalid request signature |
Mais cenários: Resolução de problemas.