> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.api.corpx.com/_mcp/server.

# 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

```mermaid
sequenceDiagram
  participant Voce as Seu sistema
  participant API as CorpX API
  participant Socios as Socios (usuarios finais)
  participant Analista as Analista
  participant Liquidante as Liquidante

  Voce->>API: POST /v1/accreditations/pj
  API-->>Voce: 201 accreditationId + biometryLinks + missingDocumentKinds
  Voce->>API: POST /accreditations/id/documents (PDFs obrigatorios)
  Voce->>Socios: Entrega o link a cada socio
  Socios->>API: Cada socio realiza a captura facial
  Note over API: Aguarda socios aprovados (docs em paralelo)
  API-->>Voce: webhook accreditation.updated (PENDING_REVIEW)
  Analista->>API: Analise previa e aprovacao
  API-->>Voce: webhook accreditation.updated (INTEGRATING)
  API->>Liquidante: Abre a conta
  Liquidante-->>API: Conta criada
  API-->>Voce: webhook accreditation.active (accountId pronto)
```

## Passo 1: Criar a accreditation

### Request

```bash
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](/baas/guias/abertura-de-contas/callback-uri).                                |

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)

```json
{
  "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.

```bash
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:

```bash
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:

```bash
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

```bash
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.