Propostas

Parte do fluxo em Onboarding (visão geral). Após concluir esta etapa, siga para Pessoa física ou Pessoa jurídica.

A proposta é o registro inicial do titular (CPF). Ela concentra credenciais, termos e validação de canais (OTP). Documentos KYC não entram aqui: vão no PATCH de PF ou PJ.

Como o fluxo funciona

O integrador executa cinco operações HTTP em sequência na proposta. POST e PATCH têm papéis distintos: o POST só abre o processo; os PATCH criam o titular e confirmam os canais. Pular qualquer escrita obrigatória bloqueia PF e PJ com 404 Customer not found.

Antes de cada PATCH, faça GET na mesma proposta, faça merge local e reenvie campos voláteis (OTP). password não retorna no GET.

flowchart TD
  A["POST /proposals<br/>Abre proposta"] --> B["GET /proposals/{proposalId}<br/>Consulta step"]
  B --> C["PATCH /proposals/{proposalId}<br/>Pacote cadastral"]
  C --> D["GET /proposals/{proposalId}<br/>Obtém OTP"]
  D --> E["PATCH /proposals/{proposalId}<br/>Confirma OTP"]
  D -.->|OTP expirado| F["POST resend-email<br/>ou resend-sms"]
  F --> D
  E --> G["Proposta concluída<br/>Liberado PF ou PJ"]

Descrição de cada operação

Criar proposta

Abre a proposta e devolve proposalId, dados de contato enviados e o objeto journey (etapa atual do fluxo). É o primeiro passo obrigatório.

Campos mínimos: document (CPF, 11 dígitos) e device.os_version_name. Contato (full_name, email, phone, etc.) pode ir no POST ou no PATCH.

Guia: Criar proposta. Contrato: Referência API.

Consultar proposta

Consulta o estado da proposta: journey.step, pendências e arrays onboardingNaturalPersons / onboardingLegalPersons com IDs de PF/PJ filhos. Use antes de cada PATCH e após reenvio de OTP.

Não expõe password. Códigos OTP aparecem aqui quando disponíveis.

Guia: Consultar proposta. Contrato: Referência API.

Atualizar proposta (pacote cadastral)

Primeiro PATCH de escrita. Com o pacote completo, a API cria o titular.

Campos obrigatórios no PATCH (todos de uma vez, após merge do GET): full_name, social_name, email, phone, birth_date, password, password_confirmation, accepted_terms_at, device.os_version_name, email_verification_code, phone_verification_code.

Guia: Atualizar proposta. Contrato: Referência API.

Consultar proposta (OTP)

Repita a consulta para obter email_verification_code e phone_verification_code. São voláteis: copie do GET imediatamente antes do próximo PATCH.

Atualizar proposta (OTP)

Segundo PATCH de escrita (pode ser o mesmo request do pacote cadastral se os códigos já estiverem no GET).

Campos: email_verification_code, phone_verification_code. Sem eles, a compliance reprova mesmo com cadastro completo.

Reenviar e-mail ou SMS (se necessário)

Somente quando OTP expirou. Corpo []. Depois: novo GET + PATCH com os códigos frescos.

Guias: Reenviar e-mail, Reenviar SMS.

Campos obrigatórios (resumo)

No POST

Contato e endereço (full_name, email, phone, birth_date, address) são opcionais na abertura.

No PATCH (pacote cadastral + OTP)

Todos obrigatórios no mesmo request (após merge do GET):

Campo journey.step

A etapa do fluxo guiado fica em journey.step (e journey.last_step). Avançar etapa sem cumprir validações da anterior gera erro. Após cada operação, consulte a proposta para ver pendências e os arrays onboardingNaturalPersons / onboardingLegalPersons.

Checklist antes de abrir PF ou PJ

• POST executado (proposalId guardado)
• PATCH cadastral com password e accepted_terms_at
• PATCH com OTP quando exigido
• GET sem pendências na proposta

Erros comuns

• PATCH sem password (não vem no GET).
• device sem os_version_name.
• OTP expirado: reenvio + novo GET + PATCH.
• PF/PJ antes da proposta concluída: Customer not found.
• password_confirmation diferente de password: 422.

Mais cenários: Resolução de problemas.

Autenticação: Bearer da plataforma + HMAC. Ver Autenticação da plataforma BaaS.