Pessoa Física
Parte do fluxo em Onboarding (visão geral). Pré-requisito: proposta concluída (Etapa 1).
Etapa 2A: Pessoa física
Documentos (files[]) e endereço completo entram no PATCH deste recurso, não no PATCH da proposta.
Passo 1: Iniciar abertura PF
| Método | POST |
| Path | /api/v2/baas/onboardings/{proposalId}/natural-persons |
Contrato: Cadastrar PF.
A resposta traz o id da pessoa (personId). Guarde para o Passo 2.
Campos obrigatórios:
| Campo | Regra |
|---|---|
document | CPF, exatamente 11 dígitos |
device.os_version_name | String |
Bearer, HMAC e scope baas.onboarding-natural-persons.write.
Passo 2: Completar cadastro PF
| Método | PATCH |
| Path | /api/v2/baas/onboardings/{proposalId}/natural-persons/{personId} |
Contrato: Atualizar PF.
Envie dados, endereço e documentos para análise. O cadastro só entra na esteira de compliance quando accepted_terms_at está presente (termos da conta PF, distintos dos termos da proposta).
Campos obrigatórios:
| Campo | Regra |
|---|---|
full_name, social_name, email, phone, birth_date | Mesmos dados da proposta; reenvie aqui |
accepted_terms_at | Data/hora Y-m-d H:i:s |
device | Objeto completo: Device |
email_verification_code | OTP do GET imediato |
address.zip_code | 8 dígitos |
address.street | String, máx. 255 |
address.number | String, máx. 255 |
address.city | Cidade |
address.neighborhood | Bairro |
address.state | UF, 2 letras |
address.complement | Opcional |
files | Mín. 3: identidade frente/verso (ou CNH) e selfie |
monthly_gross_income | Renda bruta mensal |
is_political_exposed | PEP (boolean) |
Faça GET antes do PATCH. Reenvie email_verification_code do GET no mesmo PATCH. O corpo JSON com base64 deve ser idêntico ao usado na assinatura HMAC.
Documentos (files[])
Cada item exige path (base64 com prefixo data:...;base64,...), type e, quando aplicável, side.
files.*.type | files.*.side | Uso |
|---|---|---|
document | front, back | Identidade (RG etc.), frente e verso |
drivers_license | front, back | CNH física |
digital_drivers_license | (não se aplica) | CNH digital |
selfie | (não se aplica) | Selfie do titular |
A API não valida a selfie, mas o banco exige para aprovar. Envie sempre: documento de identidade (frente + verso) e selfie.
Não envie slugs de PJ (social_contract, proof_address, etc.) neste endpoint.
Após reprovação KYC, reenvie apenas os pares type + side corrigidos. PATCH com files dispara ou reabre análise.
Schema completo: Referência API.
Erros comuns
- Proposta sem PATCH completo:
404Customer not found. filesausente ou com menos de 2 itens:422.- Corpo HMAC diferente do JSON enviado:
401.
Endpoints
Consultar
| Método | GET |
| Path | /api/v2/baas/onboardings/{proposalId}/natural-persons/{personId} |
Contrato: Consultar PF.
Bearer, HMAC. Scope baas.onboarding-natural-persons.read. Corpo [] na assinatura.
Retorna status KYC, OTP e metadados de files[] já enviados (sem base64 em path).
Criar
Ver Passo 1.
Atualizar
Ver Passo 2.