> 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 Física (PF)

Este guia mostra o passo a passo para abrir uma conta de pessoa física usando o fluxo padrão de **biometria CorpX**: nós geramos um link de captura facial, você entrega ao usuário final e, com a facial aprovada, a conta é aberta **automaticamente** — sem análise manual.

## Fluxo

```mermaid
sequenceDiagram
  participant Voce as Seu sistema
  participant API as CorpX API
  participant Usuario as Usuario final
  participant Liquidante as Liquidante

  Voce->>API: POST /v1/accreditations/pf
  API-->>Voce: 201 accreditationId + biometryLink
  Voce->>Usuario: Entrega o link (app, WhatsApp, e-mail...)
  Usuario->>API: Realiza a captura facial no navegador
  Note over API: Biometria aprovada - aprovacao automatica
  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/pf" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: onboard-cliente-12345" \
  -d '{
    "person": {
      "name": "Maria da Silva",
      "cpf": "12345678901",
      "birthDate": "1990-05-20",
      "email": "maria@email.com",
      "phone": "+5511999998888",
      "monthlyIncome": 5000.00
    },
    "address": {
      "zipCode": "01310100",
      "street": "Avenida Paulista",
      "number": "1000",
      "complement": "Apto 42",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "cityIbgeCode": "3550308"
    }
  }'
```

### Parâmetros

| Campo                  | Tipo   | Obrigatório | Descrição                                                                                                                                                             |
| ---------------------- | ------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `person.name`          | string | Sim         | Nome completo do titular.                                                                                                                                             |
| `person.cpf`           | string | Sim         | CPF (11 dígitos, sem pontuação).                                                                                                                                      |
| `person.birthDate`     | string | Sim         | Data de nascimento (`YYYY-MM-DD`).                                                                                                                                    |
| `person.email`         | string | Sim         | E-mail do titular.                                                                                                                                                    |
| `person.phone`         | string | Sim         | Telefone no padrão DDI + DDD + número (ex.: `+5511999998888`).                                                                                                        |
| `person.monthlyIncome` | number | Não         | Renda mensal declarada (BRL).                                                                                                                                         |
| `address.*`            | object | Sim         | Endereço completo. `neighborhood` (bairro) é **obrigatório** (ou `district` legado). `cityIbgeCode` é o código IBGE do município com **7 dígitos**.                   |
| `callbackUri`          | string | Não         | Para onde levar o titular de volta ao fim da jornada. 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.

### Resposta (201)

```json
{
  "accreditationId": "acr_9f8e7d6c5b4a",
  "type": "pf",
  "status": "PENDING_BIOMETRY",
  "persons": [
    {
      "personId": "prs_3b1c9a7f2e4d",
      "cpf": "12345678901",
      "name": "Maria da Silva",
      "biometryStatus": "PENDING",
      "biometryLink": "https://cadastro.unico.app/process/abc123...",
      "linkExpiresAt": "2026-07-14T18:00:00Z"
    }
  ],
  "createdAt": "2026-07-07T18:00:00Z"
}
```

O `personId` é o identificador estável da pessoa dentro do credenciamento. Use-o para correlacionar o retorno ao seu app (ver [Retorno ao seu app](/baas/guias/abertura-de-contas/callback-uri)) — é ele, e não o CPF, que aparece na URI de volta.

> **Conta ainda não vinculada**
>
> Enquanto o status for `PENDING_BIOMETRY`, o CPF **não** é atrelado ao tenant e o `accountId` ainda não existe. O `POST` **não deduplica** — repetir com o mesmo CPF cria outra accreditation. Guarde o `accreditationId` e cancele pendências abandonadas com `POST /v1/accreditations/{id}/cancel`. O `accountId` só aparece após a biometria confirmada (webhooks `accreditation.updated` / `accreditation.active`).

> **Link assíncrono**
>
> O `biometryLink` é gerado em segundos, mas de forma **assíncrona** — em raras situações ele pode vir ausente na resposta do `POST`. Nesse caso, receba-o pelo webhook `accreditation.biometry.link.created` ou consulte o `GET` logo em seguida.

> **CPF que já tem conta**
>
> Se o CPF **já for correntista** e o seu tenant tiver a portabilidade automática habilitada, a resposta vem com `status: "PENDING_CONSENT"` e um `consentLink` em vez do `biometryLink` — não existe conta nova a abrir, e sim uma autorização do titular para você operar a conta que ele já tem. Sem essa habilitação (o padrão), a accreditation falha com `existing_partner_account` e a portabilidade é feita via suporte. Veja [Titular que já tem conta](#titular-que-já-tem-conta-consent) mais abaixo.

## Passo 2: Entregar o link de facial

Entregue o `biometryLink` ao usuário final pelo canal que preferir (dentro do seu app, WhatsApp, SMS, e-mail). A jornada de captura roda no navegador do celular, sem instalação de app.

* O link **expira em 7 dias** (`linkExpiresAt`). Se expirar, use o endpoint de retry (Passo 4).
* O mesmo link também é entregue no webhook `accreditation.biometry.link.created`.

## Passo 3: Aguardar a conclusão

Assim que o usuário conclui a captura e a biometria é aprovada, a aprovação é **automática** — não há análise manual para PF no fluxo padrão. Acompanhe pelos webhooks:

1. `accreditation.updated` — `PENDING_BIOMETRY` → `INTEGRATING`;
2. `accreditation.active` — conta aberta; o `accountId` está pronto para operar.

Se a biometria for reprovada ou expirar, você recebe `accreditation.updated` com o detalhe da pessoa e pode fazer retry.

Você também pode consultar por polling:

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

```json
{
  "items": [
    {
      "accreditationId": "acr_9f8e7d6c5b4a",
      "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
      "type": "pf",
      "status": "ACTIVE",
      "persons": [
        {
          "cpf": "12345678901",
          "name": "Maria da Silva",
          "biometryStatus": "APPROVED"
        }
      ],
      "createdAt": "2026-07-07T18:00:00Z",
      "updatedAt": "2026-07-07T18:25:41Z"
    }
  ]
}
```

## Passo 4: Retry (link expirado ou biometria reprovada)

Se o link expirou ou a captura falhou, gere um novo link para a pessoa:

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

A resposta traz o novo `biometryLink` e o novo `linkExpiresAt`. O evento `accreditation.biometry.link.created` também é reemitido.

## Passo 5: Cancelar (pendência abandonada)

Se o usuário desistiu antes da biometria, cancele a accreditation enquanto o status for `PENDING_BIOMETRY` (ou `PENDING_CONSENT`):

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

A accreditation termina como `FAILED` com `errorReason=cancelled` (webhooks `accreditation.updated` / `accreditation.failed`). Depois da biometria confirmada o cancelamento não é mais permitido (`409 invalid_state`).

## Titular que já tem conta (consent)

Quando o CPF informado **já é correntista**, não há conta nova para abrir. O caminho passa a ser o titular autorizar você a operar a conta que ele já tem — e essa autorização é dada por ele mesmo, numa página nossa, com verificação de identidade.

O `POST /v1/accreditations/pf` é o mesmo: você não precisa detectar nada antes. A resposta é que muda.

> **Depende de habilitação contratual**
>
> A portabilidade automática **não vem habilitada**. Ela transfere o controle do dinheiro de uma conta que já existe, então depende de contrato específico e é liberada por tenant pelo nosso time.
>
> Sem essa habilitação, o CPF já correntista continua terminando em `FAILED` com `errorReason=existing_partner_account` e a mensagem orientando o titular a **solicitar a portabilidade ao suporte** — nesse caso o processo é conduzido manualmente por nós, e nenhum `consentLink` é emitido.
>
> Para habilitar, fale com o seu contato comercial na CorpX.

### Resposta (201) em modo consent

```json
{
  "accreditationId": "acr_5c4b3a2f1e0d",
  "type": "pf",
  "status": "PENDING_CONSENT",
  "persons": [
    {
      "personId": "prs_3b1c9a7f2e4d",
      "cpf": "12345678901",
      "name": "Maria da Silva",
      "biometryStatus": "PENDING",
      "consentStatus": "PENDING",
      "consentLink": "https://tenant.api.corpx.com/v1/accreditations/consent/cst_...",
      "consentExpiresAt": "2026-07-30T18:00:00Z"
    }
  ],
  "createdAt": "2026-07-23T18:00:00Z"
}
```

| Campo                        | Descrição                                                                         |
| ---------------------------- | --------------------------------------------------------------------------------- |
| `status`                     | `PENDING_CONSENT` — aguardando a autorização do titular.                          |
| `persons[].consentLink`      | Página de autorização. Entregue ao titular como você já entrega o link de facial. |
| `persons[].consentStatus`    | `PENDING`, `ACCEPTED`, `DECLINED`, `DENIED` ou `EXPIRED`.                         |
| `persons[].consentExpiresAt` | Validade do link (7 dias). A jornada como um todo expira em 30 dias.              |

O mesmo link chega no webhook `accreditation.consent.link.created` — assine esse evento se a sua integração pega links por webhook, porque o `accreditation.updated` não carrega link nenhum.

> **Reenviar o \`POST\` não reemite o consent**
>
> Enquanto a jornada estiver em `PENDING_CONSENT`, repetir o `POST /v1/accreditations/pf` para o mesmo CPF responde `409 already_accredited` — com `accountId: null`, `status: "PENDING_CONSENT"` e o `accreditationId` da jornada que está em andamento. Não é conta existente no seu tenant: é a autorização que ainda está pendente com o titular.
>
> Para recuperar o link em vez de reenviar:
>
> * `GET /v1/accreditations/{accreditationId}` devolve o link atual em `persons[].consentLink`, com o `consentExpiresAt`.
> * `POST /v1/accreditations/{accreditationId}/persons/{cpf}/retry` reemite o link com validade nova de 7 dias (o mesmo endpoint do Passo 4), desde que a jornada de 30 dias não tenha expirado.
>
> Se a intenção for realmente abandonar a jornada, cancele com `POST /v1/accreditations/{accreditationId}/cancel` (Passo 5) antes de criar outra.

### Fluxo

```mermaid
sequenceDiagram
  participant Voce as Seu sistema
  participant API as CorpX API
  participant Titular as Titular da conta

  Voce->>API: POST /v1/accreditations/pf (CPF já correntista)
  API-->>Voce: 201 status=PENDING_CONSENT + consentLink
  Voce->>Titular: Entrega o consentLink
  Titular->>API: Abre a página e lê o que está autorizando
  Titular->>API: Faz a verificação de identidade (selfie)
  API-->>Titular: Mostra conta, saldo atual e os poderes concedidos
  Titular->>API: Autoriza
  API-->>Voce: webhook accreditation.active (sharedAccount=true)
```

### O que o titular vê

1. **Antes de qualquer captura**, a página diz quem está pedindo acesso e o que a autorização permite — inclusive **movimentar e sacar** o dinheiro da conta.
2. **Verificação de identidade**: selfie com prova de vida, validada contra bases oficiais pelo CPF. Sem isso, a página não avança.
3. **Só depois da identidade confirmada**, aparecem **número da conta e saldo atual** — para ele autorizar sabendo exatamente qual dinheiro passa a ser operado por você.
4. **Autorização explícita**, registrada com data, hora, dispositivo e o saldo que foi exibido.

O aceite vale apenas na mesma sessão e no mesmo dispositivo que passou pela verificação de identidade. Encaminhar o link para outra pessoa, repetir o `POST` da página ou reaproveitar uma verificação antiga não autoriza nada.

### Depois da autorização

Você recebe `accreditation.active` com `sharedAccount: true` e um `accountId` para operar normalmente. Dois pontos importantes:

* **É a mesma conta**, não uma cópia: saldo, extrato e chaves Pix são os que já existiam. O `accountId` é o identificador dela no seu tenant.
* **Quem já operava a conta continua operando.** Todos os tenants autorizados pelo titular recebem os webhooks de cada movimento — inclusive os de operações que não partiram da sua API (que chegam com `external: true`).

Se o titular **não** autorizar, a accreditation termina em `FAILED` com um destes `errorReason`: `consent_declined`, `consent_expired`, `consent_facial_failed`, `castle_deny` ou `consent_link_failed` (detalhe em [Webhooks de Onboarding](/baas/guias/abertura-de-contas/webhooks#accreditationfailed)).

> **Revogação**
>
> O titular pode revogar o acesso concedido a qualquer momento pelo suporte. A partir da revogação, as chamadas do tenant revogado para aquela conta passam a responder `403` — a conta segue ativa para o titular e para os demais tenants autorizados.

## Conta pronta

Com o status `ACTIVE`, a conta já está vinculada ao seu tenant e pronta para operar. Use o `accountId` nos demais endpoints da API — PIX, extrato, boletos, QR Codes etc.

> **Tip**
>
> Guarde o par `accreditationId` + `accountId` no seu sistema. O `accountId` é o identificador que você usará em todas as operações bancárias dali em diante.