Etapa 01 - Credenciamento de Pessoa Física (PF)

Como descrito na página Credenciamento - Instruções Gerais, o fluxo de credenciamento tem 3 passos: criar proposta → enviar documentos → solicitar análise.

1️⃣ Credenciar Pessoa Física (PF)

POST /v1/marketplaces/{marketplace_id}/onboarding

{
  "external_reference_id": "uuid-gerado-pelo-seu-sistema",
  "type": "INDIVIDUAL",
  "name": "Fulano de Tal",
  "email": "[email protected]",
  "national_registration": "12345678909",
  "registration_date": "1990-01-15",
  "mothers_name": "Nome da Mae",
  "pep": false,
  "mcc": "5812",
  "revenue": 1500000,
  "cbo": "252105",
  "external_bank_account": {
    "bank_code": "341",
    "agency": "1234",
    "account_number": "56789",
    "account_type": "CHECKING"
  },
  "phone": {
    "area_Code": "11",
    "country_code": "55",
    "number": "987654321"
  },
  "address": {
    "street": "Av Paulista",
    "number": "1000",
    "complement": "Sala 10",
    "city": "São Paulo",
    "state": "SP",
    "neighborhood": "Bela Vista",
    "postal_code": "01310-100",
    "country": "BR"
}

✅ Resposta 201 Created:

{
  "onboarding_id": "UUID",
  "status": "STARTED"
}

📋 Campos do payload PF

Campo	Tipo	Obrigatório	Descrição
external_reference_id	string	❌ Não	Referência externa — Chave de idempotência: gere um UUID único por proposta
type	string	✅ Sim	`INDIVIDUAL`
name	string	✅ Sim	Nome completo (2-255)
email	string	✅ Sim	E-mail válido
national_registration	string	✅ Sim	CPF, apenas dígitos
registration_date	string	✅ Sim	Data de nascimento `YYYY-MM-DD`
mothers_name	string	✅ Sim	Nome completo da mãe
pep	boolean	✅ Sim	Pessoa exposta politicamente
mcc	string	✅ Sim	Código de atividade (4 dígitos)
revenue	int	✅ Sim	Renda mensal em centavos
cbo	string	✅ Sim	Identificação da profissão da pessoa
phone	object	✅ Sim	`country_code` (55), `area_code`, `number`
address	object	✅ Sim	`street`, `number`, `city`, `state`, `neighborhood`, `postal_code`, `country`
external_bank_account	object	❌ Não	Conta externa de destino
external_reference_id	string	❌ Não	UUID de referência externa

Idempotência
O onboarding_id é gerado deterministicamente de marketplace_id + X-Idempotency-Key. Repetir o mesmo X-Idempotency-Key retorna a mesma proposta — seguro para retry.

⚠️ Erros comuns no Credenciamento PF

HTTP	Código	Causa
`400`	`INVALID_PAYLOAD`	Campo obrigatório faltando, formato inválido ou header `X-Idempotency-Key` ausente
`409`	`IDEMPOTENCY_PAYLOAD_MISMATCH`	Chave de idempotência reutilizada com payload diferente
`422`	`DOCUMENT_ALREADY_REGISTERED`	CPF já registrado no marketplace

2️⃣ Enviar documentos

POST /v1/marketplaces/{marketplace_id}/onboarding/{onboarding_id}/documents

Para mais detalhes dessa etapa, acesse Etapa 02 - Envio de Documentos.

Para PF, obrigatórios:

🤳 Selfie
🪪 Documento de identidade (CNH completa, ou RG frente+verso)

3️⃣ Solicitar análise

POST /v1/marketplaces/{marketplace_id}/onboarding/{onboarding_id}/approval

Para mais detalhes dessa etapa, acesse [Etapa 03 - Solicitação de Análise]().

A partir daí, aguarde o webhook onboarding.approved ou onboarding.rejected com o resultado (APPROVED ou REJECTED).