Skip to navigation

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. O protocolo no app está em 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

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
}'
CampoRegra
documentCPF, 11 dígitos sem pontuação
purposepassword_reset, second_factor_reset, high_value_transaction ou sensitive_action
referenceIdObrigatório; id da ação no seu sistema e vínculo usado no consumo
displayMessageOpcional, texto simples, até 240 caracteres
callbackUriURI cadastrada exatamente como enviada
ttlMinutesValidade da jornada; padrão 30, máximo 60
consumeTtlMinutesJanela para consumir depois da aprovação; padrão 10, máximo 60
providerOpcional: unico ou dracma_trust; padrão é o provedor configurado para o tenant
methodOpcional: link (padrão) ou facetec_sdk (exige provider: dracma_trust)
referenceMatchSó com facetec_sdk: none, dracma (padrão) ou image — veja 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:

{
"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:

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

referenceMatchO que provaComparado comTipo de cota
noneHá uma pessoa viva diante da câmera (liveness 3D / PAD)ninguémliveness
dracma (padrão)Vida e o rosto pertence ao CPFbase de referência da DracmaTrust para o CPF (1:1, 3D:2D)face_match_cpf
imageVida e o rosto bate com a foto que você enviareferenceImage 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

curl "https://tenant.api.corpx.com/v1/identity-verifications/$VERIFICATION_ID" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-Id: $TENANT_ID"
StatusSignificado
PENDINGA pessoa ainda pode concluir a jornada; verificationLink está presente (link) ou há attemptsRemaining (facetec_sdk)
APPROVEDIdentidade aprovada; consuma até consumableUntil
FAILEDVerificação recusada; veja failureReason
EXPIREDA 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:

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

HTTPerrorCodeAção
400invalid_document, invalid_purpose, invalid_reference_idCorrija o campo indicado
400invalid_display_message, invalid_verification_ttl, invalid_consume_ttlRespeite texto simples e os intervalos documentados
400invalid_callback_uriEnvie exatamente uma URI cadastrada
400invalid_provider, invalid_method, invalid_reference_matchCombine provider, method e referenceMatch como documentado
400reference_image_requiredNo modo image, envie referenceImage no /facetec/process
403feature_disabledSolicite a habilitação da feature
403facetec_sdk_not_enabledPeça à CorpX a feature identity_verification_facetec_sdk e as chaves do SDK
403identity_verification_kind_not_enabledO tipo (details.kind) tem cota 0; peça a liberação
403insufficient_scopeUse identity_verification.manage nas jornadas e kyc.read nos artifacts
403forbiddenUse a credencial master M2M
404verification_not_foundConfirme o id e o X-Tenant-Id
409verification_not_consumableConfira estado, janela, purpose e referenceId
409reference_already_consumedOutra prova já consumiu essa finalidade/referência
409verification_method_mismatch, verification_not_pendingA rota não vale para o method ou o estado atual
409facetec_process_in_progressAguarde Retry-After e reenvie a mesma captura
409facetec_session_expiredRenove em /facetec/session e reabra o SDK
413payload_too_largeReduza o requestBlob (details.maxBytes)
415unsupported_media_typeEnvie Content-Type: application/json
422facetec_match_unavailableO modo de match ainda não está disponível; use outro referenceMatch ou link
429identity_verification_monthly_limit_exceededCota do tipo (details.kind) fechada; aguarde o próximo mês BRT
429facetec_attempts_exhaustedA verificação falhou por excesso de capturas; crie outra
429facetec_session_renewal_limitedAguarde Retry-After antes de renovar a sessão
429rate_limitedReduza a frequência e tente novamente
502provider_errorFalha no provedor; veja partner e tente de novo
503facetec_unavailableSDK indisponível no provedor; tente mais tarde ou use link