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

# Webhooks de Onboarding

Todos os eventos de onboarding seguem o [envelope padrão de webhooks](/baas/guias/conta/webhooks#formato-das-notificações) da plataforma (mesmo formato de entrega, autenticação, retries e idempotência). Esta página documenta os eventos específicos de accreditation.

## Eventos

| Evento                                  | Quando é emitido                                                                                               |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `accreditation.pf.created`              | Uma accreditation PF foi criada.                                                                               |
| `accreditation.pj.created`              | Uma accreditation PJ foi criada.                                                                               |
| `accreditation.biometry.link.created`   | Um link de captura facial foi gerado para uma pessoa (emitido por pessoa; reemitido em retry).                 |
| `accreditation.acceptance.link.created` | Um link de aceite de termos foi gerado para uma pessoa (somente em fluxos habilitados sob demanda pela CorpX). |
| `accreditation.consent.link.created`    | Um link de autorização foi gerado porque o CPF **já tem conta** (reemitido em retry).                          |
| `account.shared_access.granted`         | Outro tenant passou a operar uma conta que **você já operava**, autorizado pelo titular.                       |
| `accreditation.updated`                 | **Toda transição de estado** da accreditation. Fonte de verdade do progresso.                                  |
| `accreditation.active`                  | Conta aberta com sucesso — `accountId` pronto para operar.                                                     |
| `accreditation.failed`                  | Processo encerrado sem abertura de conta.                                                                      |

> **Recomendação**
>
> Assine `accreditation.updated` como fonte de verdade do progresso, e use `accreditation.active` / `accreditation.failed` como gatilhos terminais no seu sistema. Os eventos de link servem para automatizar a entrega dos links aos usuários finais.

> **O \`callbackUri\` não substitui estes eventos**
>
> Se você usa o [retorno ao seu app](/baas/guias/abertura-de-contas/callback-uri), o `outcome` que chega na URI é uma **dica de interface**: ele viaja na barra de endereço e o próprio titular pode editá-lo. Use-o só para escolher que tela mostrar quando o usuário voltar. Todo gatilho com efeito no seu sistema continua vindo daqui — ou de `GET /v1/accreditations/{accreditationId}`.

## `accreditation.updated`

Emitido em **toda transição de estado**, com o status anterior, o atual e o detalhe por pessoa.

```json
{
  "id": "evt_acr_upd_001",
  "type": "accreditation.updated",
  "occurredAt": "2026-07-07T18:20:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accreditationId": "acr_9f8e7d6c5b4a",
    "type": "pf",
    "document": "12345678901",
    "previousStatus": "PENDING_BIOMETRY",
    "status": "INTEGRATING",
    "persons": [
      {
        "cpf": "12345678901",
        "name": "Maria da Silva",
        "biometryStatus": "APPROVED"
      }
    ]
  }
}
```

| Campo do `data`             | Descrição                                                                                                                                                                      |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `accreditationId`           | ID da accreditation.                                                                                                                                                           |
| `type`                      | `pf` ou `pj`.                                                                                                                                                                  |
| `document`                  | CPF (PF) ou CNPJ (PJ) do titular.                                                                                                                                              |
| `previousStatus` / `status` | Transição de estado (vocabulário da [Visão Geral](/baas/guias/abertura-de-contas/visao-geral#status)).                                                                         |
| `persons[]`                 | Detalhe por pessoa: `cpf`, `name`, `biometryStatus` (`PENDING`, `APPROVED`, `FAILED`, `EXPIRED`) e, quando houver termo de aceite, `acceptanceStatus` (`PENDING`, `ACCEPTED`). |
| `errorReason`               | Presente quando `status = FAILED`.                                                                                                                                             |

## `accreditation.biometry.link.created`

Emitido quando um link de captura facial é gerado para uma pessoa (na criação da accreditation e em cada retry).

```json
{
  "id": "evt_acr_link_001",
  "type": "accreditation.biometry.link.created",
  "occurredAt": "2026-07-07T18:00:05.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accreditationId": "acr_9f8e7d6c5b4a",
    "type": "pf",
    "cpf": "12345678901",
    "name": "Maria da Silva",
    "biometryLink": "https://cadastro.unico.app/process/abc123...",
    "linkExpiresAt": "2026-07-14T18:00:00Z"
  }
}
```

No PJ, este evento é emitido **uma vez por sócio** — use o `cpf` para saber a quem entregar cada link.

## `accreditation.acceptance.link.created`

Emitido quando um link de aceite de termos é gerado para uma pessoa. Só ocorre em fluxos habilitados sob demanda pela CorpX; no fluxo padrão este evento não é emitido.

```json
{
  "id": "evt_acr_acc_001",
  "type": "accreditation.acceptance.link.created",
  "occurredAt": "2026-07-07T18:05:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accreditationId": "acr_9f8e7d6c5b4a",
    "type": "pf",
    "cpf": "12345678901",
    "name": "Maria da Silva",
    "acceptanceLink": "https://tenant.api.corpx.com/v1/accreditations/accept/tok_...",
    "linkExpiresAt": "2026-07-14T18:00:00Z"
  }
}
```

## `accreditation.consent.link.created`

Emitido quando o CPF informado **já tem conta** e a accreditation nasce em `PENDING_CONSENT`: em vez de abrir conta nova, o titular precisa autorizar que você opere a conta existente. Entregue o `consentLink` a ele. Reemitido a cada retry.

```json
{
  "id": "acr-acr_5c4b3a2f1e0d-consent-12345678901-1",
  "type": "accreditation.consent.link.created",
  "occurredAt": "2026-07-23T18:00:05.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "data": {
    "accreditationId": "acr_5c4b3a2f1e0d",
    "type": "pf",
    "cpf": "12345678901",
    "name": "Maria da Silva",
    "consentId": "cns_8f2a1c9d4b70",
    "consentLink": "https://tenant.api.corpx.com/v1/accreditations/consent/cst_...",
    "linkExpiresAt": "2026-07-30T18:00:00Z",
    "status": "PENDING_CONSENT"
  }
}
```

Detalhes da jornada em [Titular que já tem conta](/baas/guias/abertura-de-contas/pessoa-fisica#titular-que-já-tem-conta-consent).

## `accreditation.active`

Evento terminal de sucesso — a conta está pronta para operar.

```json
{
  "id": "evt_acr_active_001",
  "type": "accreditation.active",
  "occurredAt": "2026-07-07T18:25:41.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accreditationId": "acr_9f8e7d6c5b4a",
    "type": "pf",
    "document": "12345678901",
    "status": "ACTIVE",
    "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8"
  }
}
```

Quando a accreditation veio do fluxo de consent, o `data` traz dois campos adicionais:

| Campo do `data`    | Descrição                                                                                                                            |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `sharedAccount`    | `true` — a conta **já existia** e continua sendo operada por quem o titular já havia autorizado. Saldo e extrato são compartilhados. |
| `partnerAccountId` | Identificador do titular no liquidante, comum a todos os tenants autorizados. Útil para reconciliação.                               |

## `account.shared_access.granted`

Emitido para os tenants que **já operavam** uma conta quando o titular autoriza um novo tenant a operá-la também. O seu acesso não muda — este evento existe para você saber que a conta passou a ser movimentada por mais alguém.

```json
{
  "id": "acr-acr_5c4b3a2f1e0d-shared-tenant-acme",
  "type": "account.shared_access.granted",
  "occurredAt": "2026-07-23T18:40:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
    "tenantId": "tenant-acme",
    "partnerAccountId": "hld_7c1e...",
    "grantedAt": "2026-07-23T18:40:00Z",
    "reason": "account_holder_authorized_another_tenant"
  }
}
```

| Campo do `data`    | Descrição                                                                      |
| ------------------ | ------------------------------------------------------------------------------ |
| `accountId`        | **A sua** conta (o identificador que você já usa), não a do tenant que entrou. |
| `partnerAccountId` | Titular no liquidante — é o que evidencia que se trata da mesma conta.         |
| `grantedAt`        | Momento da autorização do titular.                                             |
| `reason`           | `account_holder_authorized_another_tenant`.                                    |

> **Não reconheceu?**
>
> Se o compartilhamento não faz sentido para o seu caso, acione o suporte: o titular pode revogar o acesso concedido, e a partir da revogação as chamadas do tenant revogado para aquela conta respondem `403`.

## `accreditation.failed`

Evento terminal de falha — o processo foi encerrado sem abertura de conta.

```json
{
  "id": "evt_acr_failed_001",
  "type": "accreditation.failed",
  "occurredAt": "2026-07-08T10:00:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accreditationId": "acr_9f8e7d6c5b4a",
    "type": "pf",
    "document": "12345678901",
    "status": "FAILED",
    "errorReason": "biometry_expired",
    "errorMessage": "Biometria facial não concluída dentro do prazo de 7 dias"
  }
}
```

Valores comuns de `errorReason`:

| `errorReason`                | Significado                                                                                                                                                                                                                                                                  |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `biometry_failed`            | Biometria facial reprovada.                                                                                                                                                                                                                                                  |
| `biometry_expired`           | Link de facial expirou sem conclusão.                                                                                                                                                                                                                                        |
| `evidence_invalid`           | Evidência de biometria externa não validada no parceiro (fluxos habilitados sob demanda).                                                                                                                                                                                    |
| `acceptance_timeout`         | Termo de aceite não confirmado dentro do prazo (fluxos habilitados sob demanda).                                                                                                                                                                                             |
| `cancelled`                  | Cancelada pelo integrador via `POST /v1/accreditations/{id}/cancel` (ainda em `PENDING_BIOMETRY` ou `PENDING_CONSENT`).                                                                                                                                                      |
| `review_rejected`            | Rejeitada na análise prévia.                                                                                                                                                                                                                                                 |
| `partner_rejected`           | Rejeitada pelo liquidante na abertura da conta.                                                                                                                                                                                                                              |
| `partner_validation_failed`  | O liquidante recusou um dado do cadastro. Veja o bloco `partner` abaixo.                                                                                                                                                                                                     |
| `partner_unavailable`        | Indisponibilidade do liquidante. É transitório: reenvie o credenciamento.                                                                                                                                                                                                    |
| `consent_declined`           | O titular **recusou** autorizar o acesso à conta que já tinha.                                                                                                                                                                                                               |
| `consent_expired`            | O titular não concluiu a autorização no prazo (link de 7 dias, jornada de 30 dias).                                                                                                                                                                                          |
| `consent_facial_failed`      | A verificação de identidade não confirmou que a pessoa é a titular do CPF.                                                                                                                                                                                                   |
| `consent_link_failed`        | Não foi possível preparar ou concluir a autorização (ex.: dados do titular divergentes entre o pedido e a autorização). Acione o suporte.                                                                                                                                    |
| `castle_deny`                | A análise de dispositivo barrou o aceite — tanto no termo de aceite quanto na autorização de portabilidade. Acione o suporte.                                                                                                                                                |
| `existing_partner_account`   | CPF/CNPJ que **já tem conta**. A portabilidade é manual: o titular deve solicitá-la ao suporte. Em PF, se o seu tenant tiver a portabilidade automática habilitada, este motivo não ocorre — o caminho é o `consentLink`. Para PJ não existe fluxo de autorização em página. |
| `kyc_rejected`               | Só na biometria centralizada: o KYC do tenant recusou a verificação de identidade.                                                                                                                                                                                           |
| `kyc_expired`                | Só na biometria centralizada: a captura não foi concluída em 7 dias.                                                                                                                                                                                                         |
| `kyc_cancelled`              | Só na biometria centralizada: a verificação foi cancelada no provedor.                                                                                                                                                                                                       |
| `kyc_misconfigured`          | Só na biometria centralizada: o preset do KYC do tenant não pede biometria facial. Acione o suporte.                                                                                                                                                                         |
| `kyc_unavailable`            | Só na biometria centralizada: o provedor não abriu a verificação. Crie um novo credenciamento.                                                                                                                                                                               |
| `kyc_not_configured`         | Só na biometria centralizada: nem o tenant nem a CorpX tinham conta configurada no provedor quando a verificação foi aberta. Acione o suporte.                                                                                                                               |
| `document_claimed_elsewhere` | Outro credenciamento do mesmo documento seguiu antes deste.                                                                                                                                                                                                                  |
| `account_opening_timeout`    | Só na biometria centralizada: identidade aprovada, mas a conta não chegou em 7 dias. Acione o suporte.                                                                                                                                                                       |

Quando a recusa vem do liquidante, `data` traz também o bloco `partner` com o
que ele informou — o **mesmo** bloco aparece em `GET /v1/accreditations/{id}`,
para consulta e webhook não divergirem:

```json
"partner": {
  "code": "request.body.invalid",
  "field": "address.number",
  "message": "A solicitação é inválida: O número não pode exceder 10 caracteres.",
  "errors": [
    {
      "code": "request.body.invalid",
      "field": "address.number",
      "message": "A solicitação é inválida: O número não pode exceder 10 caracteres."
    }
  ]
}
```

`code`, `message` e `field` são o item que reconhecemos — ou só `message`,
quando nenhum código da lista é conhecido. `errors` traz cada item que o
liquidante enviou, na ordem dele, com as mesmas três chaves. Todas são
opcionais: há recusa que chega só com `message`, e credenciamento recusado
antes de `errors` existir não tem a lista. Use o bloco em log e suporte — a
decisão do seu código continua sendo por `errorReason`.

## `accreditation.pf.created` / `accreditation.pj.created`

Emitidos na criação da accreditation (início do workflow), como confirmação assíncrona do `POST`. Assine-os no portal (**Settings → Webhooks**) ou via `PUT` na subscription.

```json
{
  "id": "acr-acr_1a2b3c4d5e6f-created",
  "type": "accreditation.pj.created",
  "occurredAt": "2026-07-07T18:00:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "data": {
    "accreditationId": "acr_1a2b3c4d5e6f",
    "type": "pj",
    "document": "12345678000199",
    "status": "PENDING_BIOMETRY",
    "biometryMode": "external"
  }
}
```