Etapa 01 - Credenciamento de Pessoa Jurídica (PJ)

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 Jurídica (PJ)

POST /v1/marketplaces/{marketplace_id}/onboarding

{
  "external_reference_id": "identificador-idempotente-do-cliente",
  "type": "BUSINESS",
  "name": "Empresa Exemplo LTDA",
  "email": "[email protected]",
  "national_registration": "11222333000181",
  "registration_date": "2010-05-20",
  "mcc": "1234",
  "legal_name": "Empresa Exemplo LTDA",
  "cnae": "5611201",
  "legal_nature": "LTDA",
  "revenue": 1000000,
  "external_bank_account": {
    "bankCode": "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"
  },
  "partner": {
    "type": "INDIVIDUAL",
    "name": "Frodo Baggis",
    "national_registration": "12345678900",
    "email": "[email protected]",
    "birthdate": "1984-04-03",
    "mothers_name": "Primula Brandybuck",
    "pep": false,
    "revenue": 15000,
    "percentage": 0.5,
    "cbo": "317120",
    "legal_name": null,
    "cnae": null,
    "legal_nature": null,
    "phone": {
      "area_code": "21",
      "country_code": "55",
      "number": "33093829"
    },
    "address": {
      "street": "Av da América",
      "number": "100B",
      "complement": "Do lado Cittar América",
      "city": "Rio de Janeiro",
      "state": "RJ",
      "neighborhood": "Barra da Tijuca",
      "postal_code": "22783450",
      "country": "BR"
    }
  }
}

✅ Resposta 201 Created:

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

📋 Campos do payload PJ (WIP)

Campo	Tipo	Obrigatório	Nota
`type`	string	✅ Sim	`BUSINESS`
`name`	string	✅ Sim	Nome fantasia (2–255)
`email`	string	✅ Sim	E-mail de contato
`national_registration`	string	✅ Sim	CNPJ, apenas dígitos
`mcc`	string	✅ Sim	4 dígitos
`revenue`	integer	✅ Sim	Faturamento em centavos
`establishment_date`	string	✅ Sim	Data de constituição `YYYY-MM-DD`
`legal_name`	string	✅ Sim	Razão social (5–255)
`cnae`	string	✅ Sim	7 dígitos
`legal_nature`	string	✅ Sim	Natureza jurídica (ex.: `LTDA`)
`partner`	object	✅ Sim	Sócio responsável, tipo `INDIVIDUAL`
`mothers_name`	string	❌ Não	1–255
`cbo`	string	❌ Não	6 dígitos
`pep`	boolean	❌ Não	default `false`
`external_bank_account`	object	❌ Não	Conta externa de destino
`external_reference_id`	string	❌ Não	UUID de referência externa
`phone`	object	✅ Sim	`country_code`, `area_code`, `number`
`address`	object	✅ Sim	`street`, `city`, `state`, `neighborhood`, `postal_code`, `country`

Sócio responsável

O marketplace envia um único sócio responsável pela operação (owner/adm). A validação do quadro societário completo e do beneficiário final (UBO) é feita automaticamente via QSA Enrichment a partir do CNPJ — você não coleta os demais sócios.

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

Erro	Causa	Correção
400	Campo obrigatório faltando ou formato inválido	Verifique o payload
409	`reference` duplicada	Use novo `reference` (ou trate como retry idempotente)
422	Aprovação sem todos os documentos	Envie os documentos pendentes

2️⃣ Enviar documentos

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

Para PJ, obrigatórios:

🤳 Selfie do sócio que está sendo credenciado
🪪 Documento de identidade (CNH completa, ou RG frente+verso) do sócio que está sendo credenciado

Para PJ, opcionais:

Tipo de empresa	Documento societário	Documento do sócio
MEI	CCMEI	SELFIE + CNH ou RG
LTDA / ME / EPP / SA	Contrato social / estatuto	SELFIE + CNH ou RG

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).