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

# Verificação de identidade

Esta API é paga à parte.

A API de verificação de identidade comprova que uma pessoa controla o CPF
informado antes de uma ação sensível. Ela é independente de abertura de conta e
de uma conta bancária: você cria a jornada, a pessoa faz a captura facial e você
consome a aprovação uma única vez no seu backend.

Há dois métodos de captura, escolhidos por `method` na criação:

* **`link`** (padrão): a API devolve um `verificationLink` que abre a página
  hospedada do provedor (Unico ou DracmaTrust). Não exige nada no seu app.
* **`facetec_sdk`**: seu app embute o **SDK FaceTec v10**, abre a câmera e envia
  cada captura para `POST /v1/identity-verifications/{id}/facetec/process`.
  Exige `provider: dracma_trust`, a feature `identity_verification_facetec_sdk`
  e as chaves do SDK cadastradas pela CorpX. **Peça o pacote** (bundle id,
  application id, domínios) antes de embutir — o pedido e as linguagens
  aceitas estão no [guia de captura facial](/baas/guias/abertura-de-contas/captura-facial#pedir-o-sdk).
  O protocolo no app está em [Captura pelo SDK FaceTec](#captura-pelo-sdk-facetec).

## Pré-requisitos

* credencial **master M2M** (`client_credentials`), nunca sessão de usuário ou
  credencial delegada;
* header `X-Tenant-Id`;
* escopo `identity_verification.manage`;
* feature `identity_verification` habilitada para criar jornadas;
* `callbackUri` cadastrada em **Verificações de identidade** no painel, com comparação **exata**.

Para baixar as evidências KYC, a credencial precisa do escopo dedicado
`kyc.read`.

## Criar a verificação

```bash
curl -X POST "https://tenant.api.corpx.com/v1/identity-verifications" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "12345678909",
    "purpose": "password_reset",
    "referenceId": "usr_01J8Y6N7M8P9Q0R1S2T3",
    "displayMessage": "Confirme sua identidade para redefinir a senha.",
    "callbackUri": "https://app.example.com/identity-verification/return",
    "ttlMinutes": 30,
    "consumeTtlMinutes": 10
  }'
```

| Campo               | Regra                                                                                                     |
| ------------------- | --------------------------------------------------------------------------------------------------------- |
| `document`          | CPF, 11 dígitos sem pontuação                                                                             |
| `purpose`           | `password_reset`, `second_factor_reset`, `high_value_transaction` ou `sensitive_action`                   |
| `referenceId`       | Obrigatório; id da ação no seu sistema e vínculo usado no consumo                                         |
| `displayMessage`    | Opcional, texto simples, até 240 caracteres                                                               |
| `callbackUri`       | URI cadastrada exatamente como enviada                                                                    |
| `ttlMinutes`        | Validade da jornada; padrão 30, máximo 60                                                                 |
| `consumeTtlMinutes` | Janela para consumir depois da aprovação; padrão 10, máximo 60                                            |
| `provider`          | Opcional: `unico` ou `dracma_trust`; padrão é o provedor configurado para o tenant                        |
| `method`            | Opcional: `link` (padrão) ou `facetec_sdk` (exige `provider: dracma_trust`)                               |
| `referenceMatch`    | Só com `facetec_sdk`: `none`, `dracma` (padrão) ou `image` — veja [os modos de match](#os-modos-de-match) |

Não envie `Idempotency-Key`: cada `POST` abre intencionalmente uma prova nova e
consome uma unidade da cota quando responde `201`. Reaproveitar uma prova facial
para uma segunda finalidade reduziria a segurança do vínculo.

Resposta `201` com `method: link`:

```json
{
  "verificationId": "idv_01J8Y7C8D9E0F1G2H3J4",
  "status": "PENDING",
  "provider": "unico",
  "method": "link",
  "verificationLink": "https://tenant.api.corpx.com/v1/identity-verifications/verify#capability-redacted",
  "expiresAt": "2026-09-24T14:30:00Z"
}
```

Entregue `verificationLink` somente à pessoa dona do CPF. Não use
`callbackUri` como prova de aprovação: consulte o recurso ou processe o webhook
e, depois, chame o endpoint de consumo.

> **Cota mensal por tipo**
>
> A cota é contada **por tipo de verificação**, por tenant e por mês-calendário em
> BRT: `link_unico`, `link_dracma`, `liveness` (`facetec_sdk` + `none`),
> `face_match_image` (`facetec_sdk` + `image`) e `face_match_cpf`
> (`facetec_sdk` + `dracma`). Os tipos `link` nascem com **10**; os tipos do SDK
> nascem com **0** e respondem `403 identity_verification_kind_not_enabled` até a
> CorpX liberar o tipo para o tenant. Cada `201` consome uma unidade do seu tipo,
> mesmo se a verificação falhar, expirar ou nunca for consumida, e não há estorno.
> Com a cota fechada a API responde HTTP `429` com
> `identity_verification_monthly_limit_exceeded` e `details.kind`. O erro
> `rate_limited` também usa HTTP `429`, mas é um controle de tráfego separado e
> compartilhado por todos os tipos. Os headers `X-RateLimit-*` do `201` descrevem
> o tipo da verificação criada.

## Captura pelo SDK FaceTec

Com `method: facetec_sdk` o seu app controla a câmera. O `201` não traz
`verificationLink`; traz o bloco `facetec` com o que o SDK precisa:

```json
{
  "verificationId": "idv_01J8Y7C8D9E0F1G2H3J4",
  "status": "PENDING",
  "provider": "dracma_trust",
  "method": "facetec_sdk",
  "referenceMatch": "dracma",
  "attemptsRemaining": 3,
  "expiresAt": "2026-09-24T14:30:00Z",
  "facetec": {
    "sessionToken": "…",
    "sessionTokenExpiresAt": "2026-09-24T14:10:00Z",
    "deviceKeyIdentifier": "…"
  }
}
```

Fluxo no app (Browser SDK v10):

1. Guarde o `sessionToken` no backend. Inicialize o SDK só com
   `deviceKeyIdentifier` (`FaceTecSDK.initializeWithSessionRequest`). O init
   já gera um `requestBlob` e conta no limite de 15 chamadas.
2. A cada `requestBlob` (o do init e o de cada captura, 1–3 MB em base64),
   envie **uma** chamada a `POST /v1/identity-verifications/{id}/facetec/process`
   com `Content-Type: application/json`, `sessionId` igual ao `sessionToken`
   e, no modo `image`, a `referenceImage` (JPEG/PNG em base64, até 2 MB; foto
   de rosto, nunca de documento).
3. Devolva `responseBlob` ao SDK em `processResponse`. A resposta também traz
   `processed`, `status`,
   `attemptsRemaining`, `checks` e, em falha definitiva, `failureReason`.
4. Se o token da sessão venceu (10 minutos) ou o `/process` respondeu
   `409 facetec_session_expired`, peça outro em
   `POST /v1/identity-verifications/{id}/facetec/session` e reabra o SDK.

```bash
curl -X POST \
  "https://tenant.api.corpx.com/v1/identity-verifications/$VERIFICATION_ID/facetec/process" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{ "requestBlob": "<base64 do SDK>", "sessionId": "<sessionToken do 201>" }'
```

Limites da jornada:

* **3 capturas reprovadas** encerram a verificação como `FAILED`
  (`liveness_failed` ou `face_mismatch`). Capturas que o provedor não processou
  (`processed: false`, por exemplo imagem fora de foco) não contam.
* Até **15 chamadas** a `/process` por verificação; a 16ª responde `429
  facetec_attempts_exhausted` e a verificação falha.
* Uma captura por vez: enquanto uma chamada está em curso, outra responde `409
  facetec_process_in_progress` com `Retry-After`.
* Corpo de até **5 MB**; acima disso, `413 payload_too_large` (`details.maxBytes`).
* `/facetec/session` pode ser chamado a qualquer momento enquanto `PENDING`,
  com freio de 1 a cada 5 s e 30 por verificação (`429
  facetec_session_renewal_limited`).

### Os modos de match

| `referenceMatch`  | O que prova                                             | Comparado com                                             | Tipo de cota       |
| ----------------- | ------------------------------------------------------- | --------------------------------------------------------- | ------------------ |
| `none`            | Há uma pessoa viva diante da câmera (liveness 3D / PAD) | ninguém                                                   | `liveness`         |
| `dracma` (padrão) | Vida **e** o rosto pertence ao CPF                      | base de referência da DracmaTrust para o CPF (1:1, 3D:2D) | `face_match_cpf`   |
| `image`           | Vida **e** o rosto bate com a foto que você envia       | `referenceImage` enviada no `/process` (1:1, 3D:2D)       | `face_match_image` |

Um `APPROVED` com `referenceMatch: none` só prova que uma pessoa viva concluiu a
captura — **não** prova quem ela é. Leia `checks.faceMatch.result`
(`not_performed`) e trate como step-up de uma sessão já autenticada, nunca como
onboarding. Quando um modo com match ainda não está disponível no provedor, a
criação responde `422 facetec_match_unavailable`; a API nunca rebaixa
silenciosamente para só liveness.

Recomendação: `password_reset` e `second_factor_reset` → `dracma` ou `image`
(provar identidade); `high_value_transaction` e `sensitive_action` dentro de
uma sessão autenticada → `none` é aceitável quando a pessoa já foi identificada
no login; `link` continua sendo a escolha certa quando você não controla o
dispositivo.

## Acompanhar o estado

```bash
curl "https://tenant.api.corpx.com/v1/identity-verifications/$VERIFICATION_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID"
```

| Status     | Significado                                                                                                                 |
| ---------- | --------------------------------------------------------------------------------------------------------------------------- |
| `PENDING`  | A pessoa ainda pode concluir a jornada; `verificationLink` está presente (`link`) ou há `attemptsRemaining` (`facetec_sdk`) |
| `APPROVED` | Identidade aprovada; consuma até `consumableUntil`                                                                          |
| `FAILED`   | Verificação recusada; veja `failureReason`                                                                                  |
| `EXPIRED`  | A jornada venceu sem aprovação                                                                                              |

A resposta também traz `purpose`, `referenceId`, `document`, `provider`,
`method`, `expiresAt` e, quando aplicável, `failureReason`, `completedAt`,
`consumableUntil` e `consumedAt`. `verificationLink` aparece **somente** em
`PENDING` com `method: link`. Com `method: facetec_sdk` vêm também
`referenceMatch`, `attemptsRemaining` e `checks`
(`{"liveness": "pending|passed|failed", "faceMatch": {"result":
"pending|passed|failed|not_performed", "reference": "dracma|image"}}`).
Em `failureReason`, `liveness_failed` e `face_mismatch` são os motivos
específicos do SDK.

## Consumir a aprovação

O consumo liga a prova à ação que você está prestes a executar:

```bash
curl -X POST \
  "https://tenant.api.corpx.com/v1/identity-verifications/$VERIFICATION_ID/consume" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "password_reset",
    "referenceId": "usr_01J8Y6N7M8P9Q0R1S2T3"
  }'
```

`purpose` e `referenceId` precisam ser exatamente os valores da criação. A
primeira chamada válida marca `consumedAt`. Repetir exatamente o mesmo
`verificationId` e corpo é idempotente e devolve o mesmo resultado. Uma
referência ou finalidade diferente, uma tentativa concorrente, estado diferente
de `APPROVED` ou janela vencida responde `409`.

Faça o consumo e a ação sensível na mesma unidade lógica do seu backend. Não
autorize a ação apenas porque o `GET` mostrou `APPROVED`: sem o consumo, duas
requisições concorrentes poderiam reutilizar a mesma prova.

## Callback e webhook

`callbackUri` devolve o navegador ao seu app; ela não substitui notificação de
servidor. O valor precisa coincidir exatamente com o cadastrado para o tenant —
sem wildcard, comparação por prefixo ou normalização de query string.

Nos estados terminais `APPROVED`, `FAILED` e `EXPIRED`, a plataforma envia
`identity.verification.completed`. Valide o `X-Signature` contra os bytes brutos
do corpo e deduplique pelo `id` do envelope. Veja o payload completo em
[Webhooks](/baas/guias/conta/webhooks#identityverificationcompleted).

## Evidências KYC

```bash
curl \
  "https://tenant.api.corpx.com/v1/identity-verifications/$VERIFICATION_ID/artifacts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID"
```

Esta rota exige `kyc.read` no lugar do escopo de gerenciamento e a feature
`kyc_artifacts`. Os arquivos podem conter biometria e material de identidade:
não registre URLs ou conteúdo em logs e aplique a mesma retenção da sua política
de KYC.

## Erros principais

| HTTP | `errorCode`                                                                  | Ação                                                                            |
| ---- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| 400  | `invalid_document`, `invalid_purpose`, `invalid_reference_id`                | Corrija o campo indicado                                                        |
| 400  | `invalid_display_message`, `invalid_verification_ttl`, `invalid_consume_ttl` | Respeite texto simples e os intervalos documentados                             |
| 400  | `invalid_callback_uri`                                                       | Envie exatamente uma URI cadastrada                                             |
| 400  | `invalid_provider`, `invalid_method`, `invalid_reference_match`              | Combine `provider`, `method` e `referenceMatch` como documentado                |
| 400  | `reference_image_required`                                                   | No modo `image`, envie `referenceImage` no `/facetec/process`                   |
| 403  | `feature_disabled`                                                           | Solicite a habilitação da feature                                               |
| 403  | `facetec_sdk_not_enabled`                                                    | Peça à CorpX a feature `identity_verification_facetec_sdk` e as chaves do SDK   |
| 403  | `identity_verification_kind_not_enabled`                                     | O tipo (`details.kind`) tem cota 0; peça a liberação                            |
| 403  | `insufficient_scope`                                                         | Use `identity_verification.manage` nas jornadas e `kyc.read` nos artifacts      |
| 403  | `forbidden`                                                                  | Use a credencial master M2M                                                     |
| 404  | `verification_not_found`                                                     | Confirme o id e o `X-Tenant-Id`                                                 |
| 409  | `verification_not_consumable`                                                | Confira estado, janela, `purpose` e `referenceId`                               |
| 409  | `reference_already_consumed`                                                 | Outra prova já consumiu essa finalidade/referência                              |
| 409  | `verification_method_mismatch`, `verification_not_pending`                   | A rota não vale para o `method` ou o estado atual                               |
| 409  | `facetec_process_in_progress`                                                | Aguarde `Retry-After` e reenvie a mesma captura                                 |
| 409  | `facetec_session_expired`                                                    | Renove em `/facetec/session` e reabra o SDK                                     |
| 413  | `payload_too_large`                                                          | Reduza o `requestBlob` (`details.maxBytes`)                                     |
| 415  | `unsupported_media_type`                                                     | Envie `Content-Type: application/json`                                          |
| 422  | `facetec_match_unavailable`                                                  | O modo de match ainda não está disponível; use outro `referenceMatch` ou `link` |
| 429  | `identity_verification_monthly_limit_exceeded`                               | Cota do tipo (`details.kind`) fechada; aguarde o próximo mês BRT                |
| 429  | `facetec_attempts_exhausted`                                                 | A verificação falhou por excesso de capturas; crie outra                        |
| 429  | `facetec_session_renewal_limited`                                            | Aguarde `Retry-After` antes de renovar a sessão                                 |
| 429  | `rate_limited`                                                               | Reduza a frequência e tente novamente                                           |
| 502  | `provider_error`                                                             | Falha no provedor; veja `partner` e tente de novo                               |
| 503  | `facetec_unavailable`                                                        | SDK indisponível no provedor; tente mais tarde ou use `link`                    |