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, entrega o link à pessoa e consome a aprovação uma única vez no seu backend.

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

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
  }'

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:

{
  "verificationId": "idv_01J8Y7C8D9E0F1G2H3J4",
  "status": "PENDING",
  "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.

Acompanhar o estado

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

A resposta também traz purpose, referenceId, document, provider, expiresAt e, quando aplicável, failureReason, completedAt, consumableUntil e consumedAt. verificationLink aparece somente em PENDING.

Consumir a aprovação

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

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.

Evidências KYC

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