> 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 Contas (Onboarding)

As APIs de **Accreditation** permitem abrir contas para os seus clientes finais — pessoas físicas (PF) e pessoas jurídicas (PJ) — de forma programática, com verificação de identidade por **biometria facial**.

> **Habilitação**
>
> As APIs de onboarding estão em rollout controlado. Solicite a habilitação para o seu tenant ao nosso time de suporte antes de integrar.

## Como funciona

O processo tem três grandes etapas:

1. **Verificação de identidade (biometria facial)** — cada pessoa física envolvida (o titular no PF; cada sócio no PJ) precisa ter a identidade verificada por biometria facial.
2. **Documentos societários (só PJ)** — envie os PDFs exigidos pelo `company.legalForm` via `POST /v1/accreditations/{id}/documents` (em paralelo com a biometria). Detalhes em [Abertura PJ](/baas/guias/abertura-de-contas/pessoa-juridica).
3. **Análise** — dependendo do fluxo, a abertura é aprovada automaticamente ou passa por análise prévia de um analista.
4. **Abertura da conta no liquidante** — após aprovação, a conta é aberta e vinculada automaticamente ao seu tenant. Você recebe o `accountId` definitivo e pode começar a operar (PIX, boletos, extrato etc.).

> **CPF que já tem conta**
>
> Para PF, se o CPF já for correntista não existe conta nova a abrir. Para tenants com **portabilidade automática habilitada** (depende de contrato; não vem ligada), a accreditation nasce em `PENDING_CONSENT` e devolve um link para o **titular autorizar** que você opere a conta que ele já tem — com verificação de identidade e divulgação de saldo antes do aceite. Sem essa habilitação, a accreditation falha com `existing_partner_account` e a portabilidade é solicitada ao suporte. Veja [Titular que já tem conta](/baas/guias/abertura-de-contas/pessoa-fisica#titular-que-já-tem-conta-consent).

A verificação de identidade usa a **biometria CorpX**: nós geramos um **link de captura facial** (powered by Unico) para cada pessoa. Você entrega o link ao usuário final, que faz a jornada de captura no navegador ou celular.

| Fluxo               | Como funciona                                                          | Aprovação                                                      |
| ------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------- |
| **Biometria CorpX** | Link de captura facial por pessoa, gerado por nós e entregue por você. | **PF: automática** após a facial aprovada. PJ: análise prévia. |

> **O que você precisa fazer**
>
> Entregar o link ao usuário final e aguardar os webhooks. O resto da jornada — captura, validação, abertura da conta — acontece do nosso lado.

## Máquina de estados

Toda accreditation percorre a seguinte máquina de estados:

```mermaid
flowchart TD
  Start["POST /v1/accreditations/pf ou /pj"] --> PendingBiometry[PENDING_BIOMETRY]
  Start -->|"PF cujo CPF já tem conta"| PendingConsent[PENDING_CONSENT]
  PendingConsent -->|"Titular autoriza (identidade verificada)"| Active[ACTIVE]
  PendingConsent -->|"Recusa, expiração ou identidade não confirmada"| Failed[FAILED]
  PendingBiometry -->|"Biometria aprovada (todas as pessoas)"| BiometryApproved[BIOMETRY_APPROVED]
  PendingBiometry -->|"Reprovada ou expirada"| Failed
  BiometryApproved -->|"PF com biometria CorpX (automático)"| Integrating[INTEGRATING]
  BiometryApproved -->|"toda PJ (e PF sinalizada para análise)"| PendingReview[PENDING_REVIEW]
  PendingReview -->|"Aprovada pelo analista"| Integrating
  PendingReview -->|"Rejeitada"| Failed
  Integrating -->|"Conta aberta no liquidante"| Active
  Integrating -->|"Rejeitada pelo liquidante"| Failed
```

## Status

| Status              | Significado                                                                                                                                                                 | Ação esperada do integrador                                                                                                                                                   |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PENDING_BIOMETRY`  | Aguardando a biometria facial de uma ou mais pessoas.                                                                                                                       | Entregue o link de facial (ou de aceite) a cada pessoa pendente. Reenvie se necessário.                                                                                       |
| `PENDING_CONSENT`   | Só PF, e só com portabilidade automática habilitada: o CPF **já tem conta**, então não há conta nova a abrir — o titular precisa autorizar você a operar a conta existente. | Entregue o `consentLink` ao titular. Detalhes em [Titular que já tem conta](/baas/guias/abertura-de-contas/pessoa-fisica#titular-que-já-tem-conta-consent).                   |
| `BIOMETRY_APPROVED` | Todas as biometrias aprovadas. Estado transitório.                                                                                                                          | Nenhuma — aguarde o próximo webhook.                                                                                                                                          |
| `PENDING_REVIEW`    | Aguardando análise prévia de um analista.                                                                                                                                   | Nenhuma — aguarde. O prazo típico é de 1 dia útil.                                                                                                                            |
| `INTEGRATING`       | Conta sendo aberta no liquidante. Estado transitório.                                                                                                                       | Nenhuma — aguarde.                                                                                                                                                            |
| `ACTIVE`            | Conta aberta e pronta para operar.                                                                                                                                          | Guarde o `accountId` e comece a operar.                                                                                                                                       |
| `FAILED`            | Processo encerrado sem abertura de conta.                                                                                                                                   | Verifique `errorReason`. Em `consent_*`, o titular não autorizou (ou não concluiu) o acesso à conta que já tinha. Nos demais casos, retry de biometria ou nova accreditation. |

## Acompanhando o progresso

Você tem duas formas complementares de acompanhar cada accreditation:

* **Webhooks (recomendado)** — o evento `accreditation.updated` é emitido a **cada transição de estado**, além de eventos específicos (link de facial criado, conta ativa, falha). Veja [Webhooks de Onboarding](/baas/guias/abertura-de-contas/webhooks).
* **Polling** — `GET /v1/accreditations/pf` e `GET /v1/accreditations/pj` retornam o status agregado e o detalhe por pessoa (estado da biometria, link, expiração).

O campo opcional `callbackUri` traz o titular de volta ao seu app quando ele termina a etapa dele, com o desfecho na URI — útil para a experiência, mas **não substitui** nenhuma das duas formas acima. Veja [Retorno ao seu app](/baas/guias/abertura-de-contas/callback-uri).

## Vínculo com o seu tenant

O CPF/CNPJ **só é atrelado ao tenant após a biometria ser confirmada**. Enquanto `PENDING_BIOMETRY`, não há `accountId` e o `POST` **não deduplica**: repetir com o mesmo documento cria outra accreditation (`201`). Use `POST /v1/accreditations/{id}/cancel` para encerrar pendências abandonadas (`FAILED` / `errorReason=cancelled`).

Depois da confirmação, a conta aberta no liquidante fica **automaticamente vinculada ao tenant** que criou a accreditation — sem passo adicional de ativação. Um novo `POST` com o documento já claimado **pelo seu próprio tenant** retorna `409 already_accredited`.

### Conta compartilhada entre tenants

Uma conta PF pode ser operada por mais de um tenant, quando o **titular autoriza** cada um deles pelo fluxo de consent ([Titular que já tem conta](/baas/guias/abertura-de-contas/pessoa-fisica#titular-que-já-tem-conta-consent)). Nesse caso:

* É a **mesma conta** — saldo, extrato e chaves Pix são compartilhados. Cada tenant tem seu próprio `accountId` apontando para ela.
* **Todos** os tenants autorizados recebem os webhooks de cada movimento. Operações originadas fora da sua API (por outro tenant autorizado ou pelo próprio titular) chegam com `external: true`.
* Autorizações anteriores **não** são revogadas quando um novo tenant é autorizado. Se você já operava a conta e recebe `account.shared_access.granted`, outro tenant passou a operá-la também — se isso não faz sentido para o seu caso, fale com o suporte.
* O titular pode revogar qualquer um dos acessos pelo suporte; a partir daí as chamadas do tenant revogado para aquela conta respondem `403`.

## Arquivos comprobatórios

`GET /v1/accreditations/{accreditationId}/artifacts` devolve as evidências arquivadas do processo: os PDFs societários que você enviou, o **documento de identidade** capturado na biometria (`unico_id_document`, em geral o RG em PDF) e, quando o provedor libera, a **selfie** (`unico_selfie`) e o JWT do conjunto probatório (`unico_evidence_set`). Cada item já vem com uma `downloadUrl` pré-assinada, válida por cerca de 10 minutos.

```bash
curl -H "Authorization: Bearer $TOKEN" -H "X-Tenant-Id: $TENANT" \
  https://api.corpx.com/v1/accreditations/acr_891418ce2f67/artifacts
```

```json
{
  "accreditationId": "acr_891418ce2f67",
  "count": 2,
  "items": [
    {
      "artifactId": "art_7c1d90f2ab34",
      "kind": "unico_evidence_set",
      "cpf": "12345678901",
      "fileName": "unico_evidence_set.jwt",
      "contentType": "application/jwt",
      "sizeBytes": 14203,
      "createdAt": "2026-08-15T18:42:03Z",
      "scanStatus": "APPROVED",
      "metadata": { "unicoProcessId": "cst_3bd257e7201d441379256746" },
      "downloadUrl": "https://..."
    }
  ]
}
```

`downloadUrl` só aparece com `scanStatus: "APPROVED"`: todo upload passa por checagem de tipo, antivírus e sanitização antes de ser arquivado. Enquanto o arquivo está em `PENDING`, consulte de novo em alguns segundos.

> **Habilitação e escopo**
>
> A rota entrega **biometria do titular**, então depende de dois interruptores independentes:
>
> * a feature `kyc_artifacts` precisa estar habilitada no seu tenant (fale com o suporte — exige previsão contratual), senão a resposta é `403 feature_disabled`;
> * a credencial precisa carregar o escopo `kyc.read`. O escopo genérico `read` **não** é aceito, de propósito: nenhuma credencial existente passa a baixar rosto de cliente sem uma decisão explícita.

Os mesmos arquivos aparecem no detalhe da accreditation no seu backoffice, para quem tem a permissão `backoffice:accreditations` (nesse caso não há escopo envolvido, só a feature).

## Biometria centralizada

Alguns tenants não usam o link da Unico nem o objeto `biometry`. A abertura cria a verificação no provedor de biometria do próprio tenant e a conta chega pronta: você não chama o liquidante.

* Não envie `biometry`. A resposta é `422 biometry_not_accepted`.
* PJ exige exatamente um sócio com `isAdministrator: true` (`422 administrator_required`). Só essa pessoa faz a captura e recebe `biometryLink`; os demais sócios não têm link, e o retry para eles responde `422 administrator_required`.
* Sem conta própria do tenant no provedor, a verificação abre na conta da CorpX. A criação só responde `503 kyc_not_configured` quando nenhuma das duas está configurada.
* O `201` traz `persons[].biometryLink`, a página hospedada. Ao fim da captura ela volta ao seu `callbackUri` com `outcome` (`biometry_approved`, `biometry_pending`, `biometry_failed`, `biometry_expired`), como na biometria CorpX. Quem tem app próprio pede um token em `POST /v1/accreditations/{id}/capture` e relê os blobs do FaceTec nas rotas públicas `/start` e `/session`. O passo a passo do link, do SDK, do pedido do pacote (bundle id, application id, domínios) e das linguagens está no [guia de captura facial](/baas/guias/abertura-de-contas/captura-facial). O app não fala com o provedor.
* Documento societário, nesse modo, vai em `contentBase64` (PDF de até 4 MB) no `POST .../documents`, e só os kinds `company_articles`, `company_proof_of_address` e `financial_statements`. Sem o campo, `422 document_body_required`; outro kind, `422 invalid_kind`; recusado pelo provedor, `422 document_not_accepted`.
* A revisão, quando existe, é no provedor; o status fica em `PENDING_REVIEW` até a decisão. Decidir por aqui responde `409 review_in_kyc_provider`.
* `FAILED` traz um destes `errorReason`: `kyc_rejected`, `kyc_expired`, `kyc_cancelled` (cancelada no provedor), `kyc_misconfigured`, `kyc_unavailable`, `kyc_not_configured`, `document_claimed_elsewhere` (outro credenciamento do mesmo documento seguiu antes), `account_opening_timeout` (identidade aprovada, conta não chegou em 7 dias) ou `cancelled` (seu `POST .../cancel`).

Portabilidade e consent não mudam: CPF que já tem conta continua no fluxo de autorização, quando ele está habilitado.

## Próximos passos

* [Captura facial (link e SDK FaceTec)](/baas/guias/abertura-de-contas/captura-facial)
* [Abertura de conta PF](/baas/guias/abertura-de-contas/pessoa-fisica)
* [Abertura de conta PJ](/baas/guias/abertura-de-contas/pessoa-juridica)
* [Retorno ao seu app (`callbackUri`)](/baas/guias/abertura-de-contas/callback-uri)
* [Webhooks de Onboarding](/baas/guias/abertura-de-contas/webhooks)