Abertura de Conta — Pessoa Jurídica (PJ)

Este guia mostra o passo a passo para abrir uma conta de pessoa jurídica. A diferença em relação ao PF: a biometria facial é exigida de cada sócio (ou diretor estatutário, em cooperativas), você deve enviar os PDFs societários exigidos pelo tipo da empresa, e toda abertura PJ passa por análise prévia de um analista antes da conta ser aberta.

Fluxo

Passo 1: Criar a accreditation

Request

curl -X POST "https://tenant.api.corpx.com/v1/accreditations/pj" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: onboard-empresa-9876" \
  -d '{
    "company": {
      "legalName": "Empresa Exemplo LTDA",
      "tradeName": "Exemplo",
      "cnpj": "12345678000199",
      "email": "financeiro@exemplo.com",
      "phone": "+5511333334444",
      "monthlyRevenue": 150000.00,
      "legalForm": "ltda"
    },
    "address": {
      "zipCode": "01310100",
      "street": "Avenida Paulista",
      "number": "1000",
      "complement": "Conjunto 101",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "cityIbgeCode": "3550308"
    },
    "partners": [
      {
        "name": "João Souza",
        "cpf": "11122233344",
        "birthDate": "1985-03-10",
        "email": "joao@exemplo.com",
        "phone": "+5511988887777",
        "ownershipPercent": 60,
        "isAdministrator": true
      },
      {
        "name": "Ana Lima",
        "cpf": "55566677788",
        "birthDate": "1992-11-02",
        "email": "ana@exemplo.com",
        "phone": "+5511977776666",
        "ownershipPercent": 40,
        "isAdministrator": false
      }
    ]
  }'

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`company.legalName`	string	Sim	Razão social.
`company.tradeName`	string	Sim	Nome fantasia. O liquidante exige o campo para CNPJ. Se a empresa não tiver nome fantasia registrado, repita a razão social.
`company.cnpj`	string	Sim	CNPJ (14 dígitos, sem pontuação).
`company.email` / `company.phone`	string	Sim	Contato da empresa.
`company.monthlyRevenue`	number	Não	Faturamento mensal declarado (BRL).
`company.legalForm`	string	Não	Tipo societário: `mei`, `ltda` (default), `sa`, `cooperative`. Define os PDFs obrigatórios.
`address.*`	object	Sim	Endereço da empresa. `neighborhood` (bairro) é obrigatório (ou `district` legado). `cityIbgeCode` com 7 dígitos (código IBGE).
`partners[]`	array	Sim	Quadro societário (ou diretores estatutários se `legalForm=cooperative`). Pelo menos um com `isAdministrator: true`.
`partners[].name` / `cpf` / `birthDate`	—	Sim	Dados de cada sócio/diretor. A biometria facial será exigida de todos.
`partners[].email` / `phone`	string	Sim	Contato — usado para a jornada de biometria.
`partners[].ownershipPercent`	number	Sim	Participação societária (%).
`partners[].isAdministrator`	boolean	Sim	Se o sócio/diretor é administrador. É obrigatório ter pelo menos um administrador; mais de um é aceito. Sem nenhum, o `POST` é recusado com `400 invalid_payload` e nenhum link de biometria é emitido.
`callbackUri`	string	Não	Para onde levar cada sócio de volta ao concluir a biometria. Exige cadastro prévio junto ao suporte — ver Retorno ao seu app.

Limites PIX iniciais são aplicados automaticamente com valores padrão conservadores. Alteração de limite (aumento ou redução) exige solicitação manual ao suporte.

Cooperativa

Com legalForm=cooperative, informe em partners[] os diretores estatutários (não a lista completa de cooperados). Os documentos obrigatórios são os mesmos de sa.

Resposta (201)

{
  "accreditationId": "acr_1a2b3c4d5e6f",
  "type": "pj",
  "status": "PENDING_BIOMETRY",
  "legalForm": "ltda",
  "requiredDocumentKinds": ["company_articles"],
  "missingDocumentKinds": ["company_articles"],
  "documents": [],
  "persons": [
    {
      "personId": "prs_3b1c9a7f2e4d",
      "cpf": "11122233344",
      "name": "João Souza",
      "biometryStatus": "PENDING",
      "biometryLink": "https://cadastro.unico.app/process/abc111...",
      "linkExpiresAt": "2026-07-14T18:00:00Z"
    },
    {
      "personId": "prs_8d2f4e6a1c0b",
      "cpf": "55566677788",
      "name": "Ana Lima",
      "biometryStatus": "PENDING",
      "biometryLink": "https://cadastro.unico.app/process/abc222...",
      "linkExpiresAt": "2026-07-14T18:00:00Z"
    }
  ],
  "createdAt": "2026-07-07T18:00:00Z"
}

Conta ainda não vinculada

Enquanto PENDING_BIOMETRY, o CNPJ não é atrelado ao tenant e o POST não deduplica — repetir com o mesmo CNPJ cria outra accreditation. Cancele pendências abandonadas com POST /v1/accreditations/{id}/cancel.

Link assíncrono

Os biometryLink são gerados em segundos, mas de forma assíncrona — podem vir ausentes na resposta do POST. Nesse caso, receba cada um pelo webhook accreditation.biometry.link.created (emitido por sócio) ou consulte o GET logo em seguida.

Passo 2: Enviar os PDFs societários

Depois do 201, suba os documentos obrigatórios do legalForm (sempre application/pdf):

legalForm	Obrigatórios	Opcionais
`mei`, `ltda`	`company_articles`	`company_proof_of_address`, `business_license`, `regulatory_license`, `other`
`sa`, `cooperative`	os de LTDA + `cnpj_card`, `financial_statements`	idem

Kinds tipados: um por accreditation (re-upload substitui).
other: vários arquivos (no máximo 10); fileName obrigatório.
O company_proof_of_address deixou de ser obrigatório, mas continua aceito — o operador pode pedi-lo na análise prévia, onde também confere a validade/atualidade dos documentos.

curl -X POST "https://tenant.api.corpx.com/v1/accreditations/acr_1a2b3c4d5e6f/documents" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "company_articles",
    "fileName": "contrato-social.pdf",
    "contentType": "application/pdf",
    "sizeBytes": 184320
  }'

A resposta traz uploadUrl (PUT, 1h). sizeBytes é o tamanho real do arquivo e entra na assinatura: o PUT tem que mandar exatamente esses bytes, sem cabeçalho de autenticação nosso. Repita para cada kind obrigatório.

O 201 não cumpre o requisito. O GET da accreditation lista o slot em documents[] com deliveryStatus: pending_upload e mantém o kind em missingDocumentKinds até o objeto existir no arquivo (tamanho > 0) e, com o pipeline ligado, passar pela varredura. Só então deliveryStatus vira delivered e uploadedAt aparece.

Depois do PUT, o arquivo passa por antivírus e sanitização (o PDF é rasterizado) antes de ser arquivado — leva poucos segundos. Um arquivo que não seja PDF de verdade, ou que esteja infectado ou corrompido, é recusado (deliveryStatus: rejected); nesse caso, repita o upload com o arquivo correto.

Passo 3: Entregar um link a cada sócio

Cada sócio recebe o seu próprio biometryLink e deve completar a jornada individualmente. A accreditation entra em review quando todos os sócios tiverem biometria aprovada (os PDFs podem ser enviados em paralelo).

Cada link expira em 7 dias — acompanhe linkExpiresAt por pessoa.
O evento accreditation.biometry.link.created é emitido uma vez por sócio.
Sócios pendentes aparecem com biometryStatus: "PENDING" no GET.

Passo 4: Análise prévia

Com todas as biometrias aprovadas, a accreditation entra em PENDING_REVIEW — toda PJ passa por análise prévia. Idealmente os PDFs obrigatórios já foram enviados (missingDocumentKinds vazio); o analista vê o que falta no detalhe. Você recebe accreditation.updated na entrada e na saída dessa etapa. O prazo típico é de 1 dia útil.

Aprovada (docs completos) → INTEGRATING e a conta é aberta no liquidante.
Aprovada com override — se ainda faltarem PDFs, o operador pode forçar com forceIncompleteDocuments: true + reason; fica registrado em documentsOverride* na accreditation.
Rejeitada → status muda para FAILED com errorReason explicando o motivo.

Passo 5: Conta pronta

Quando a conta é aberta você recebe accreditation.active. O accountId está vinculado ao seu tenant e pronto para operar.

Retry por sócio

Se o link de um sócio expirou ou a captura dele falhou, gere um novo link apenas para aquele sócio — os demais não são afetados:

curl -X POST "https://tenant.api.corpx.com/v1/accreditations/acr_1a2b3c4d5e6f/persons/55566677788/retry" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa"

Cancelar

Enquanto o status for PENDING_BIOMETRY, você pode cancelar a accreditation inteira:

curl -X POST "https://tenant.api.corpx.com/v1/accreditations/acr_1a2b3c4d5e6f/cancel" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Content-Type: application/json" \
  -d '{"reason":"company abandoned onboarding"}'

Consulta

curl -X GET "https://tenant.api.corpx.com/v1/accreditations/pj?document=12345678000199" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa"

A resposta traz o status agregado e o detalhe por sócio (biometryStatus, link e expiração de cada um), permitindo que você monte uma tela de acompanhamento no seu sistema.