Skip to navigation

Verificação de identidade

Esta API é paga à parte.

A API cria uma prova independente de conta para proteger redefinição de senha, reset de segundo fator, transação de alto valor ou outra ação sensível. O backend do banco cria a jornada para um CPF, o correntista faz a captura facial e o backend consome a aprovação uma única vez antes de concluir a ação.

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).
  • facetec_sdk: o app do banco 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.
Use a master, não a credencial da conta

Esta superfície é para a credencial master M2M do internet banking. A credencial filha, delegada para uma única conta, não pode criar, consultar nem consumir verificações. Nunca envie a master ao navegador ou ao app.

Pré-requisitos

  • token client_credentials da master;
  • host https://client.api.corpx.com e os três headers de assinatura;
  • 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.

O download de evidências usa o escopo dedicado kyc.read.

Criar

curl -X POST "https://client.api.corpx.com/v1/identity-verifications" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-Id: $TENANT_ID" \
-H "X-Request-Timestamp: $TS" \
-H "X-Content-SHA256: $BODY_SHA256" \
-H "X-Request-Signature: $SIGNATURE" \
-H "Content-Type: application/json" \
-d '{
"document": "12345678909",
"purpose": "second_factor_reset",
"referenceId": "reset_01J8Y6N7M8P9Q0R1S2T3",
"displayMessage": "Confirme sua identidade para cadastrar o novo dispositivo.",
"callbackUri": "https://ib.example.com/identity-verification/return",
"ttlMinutes": 30,
"consumeTtlMinutes": 10
}'

document é um CPF de 11 dígitos. referenceId é obrigatório e identifica a ação no seu sistema. As finalidades aceitas são password_reset, second_factor_reset, high_value_transaction e sensitive_action. displayMessage é texto simples opcional de até 240 caracteres. ttlMinutes tem padrão 30 e consumeTtlMinutes, 10; ambos têm máximo 60. provider (unico ou dracma_trust) e method (link ou facetec_sdk) são opcionais; referenceMatch (none, dracma padrão ou image) só vale com facetec_sdk.

Não envie Idempotency-Key: cada POST abre intencionalmente uma prova nova e consome uma unidade da cota quando responde 201.

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"
}
Cota por tenant e por tipo, não por conta

A cota é contada por tipo, por tenant e por mês-calendário BRT, somando todas as contas do internet banking: 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. Cada 201 conta e nunca é estornado, mesmo se a jornada falhar, expirar ou não for consumida. Cota fechada responde HTTP 429 com identity_verification_monthly_limit_exceeded e details.kind; o erro rate_limited também usa HTTP 429, mas é um limite de tráfego separado.

Captura pelo SDK FaceTec

Com method: facetec_sdk o 201 não traz verificationLink; traz o bloco facetec (sessionToken, sessionTokenExpiresAt, deviceKeyIdentifier) e attemptsRemaining: 3. O Browser SDK v10 inicializa só com deviceKeyIdentifier (initializeWithSessionRequest); o sessionToken fica no backend e volta como sessionId em cada /facetec/process. O próprio init gera um requestBlob e conta no limite de 15 chamadas. Cada captura seguinte gera outro blob (1–3 MB em base64).

O app devolve o blob ao backend, e só o backend (com a master e a assinatura de requisição) chama, uma vez por captura:

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

No modo image, inclua referenceImage (JPEG/PNG em base64, até 2 MB; foto de rosto, nunca de documento). A resposta traz responseBlob (devolva ao SDK), processed, status, attemptsRemaining, checks e, em falha definitiva, failureReason. Quando o token da sessão vence (10 minutos) ou o /process responde 409 facetec_session_expired, peça outro em POST /v1/identity-verifications/{id}/facetec/session e reabra o SDK.

Limites: 3 capturas reprovadas encerram a verificação como FAILED (liveness_failed ou face_mismatch); capturas não processadas (processed: false) não contam. Até 15 chamadas a /process por verificação (a 16ª responde 429 facetec_attempts_exhausted). Uma captura por vez (409 facetec_process_in_progress com Retry-After). Corpo de até 5 MB (413 payload_too_large). /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).

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 é (checks.faceMatch.result = not_performed). Use-o apenas como step-up de uma sessão já autenticada. 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. Para password_reset e second_factor_reset, prefira dracma ou image.

Consultar

curl "https://client.api.corpx.com/v1/identity-verifications/$VERIFICATION_ID" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-Id: $TENANT_ID" \
-H "X-Request-Timestamp: $TS" \
-H "X-Content-SHA256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \
-H "X-Request-Signature: $SIGNATURE"
StatusPróximo passo
PENDINGAguarde; verificationLink continua presente (link) ou há attemptsRemaining (facetec_sdk)
APPROVEDConsuma antes de consumableUntil
FAILEDNão execute a ação; leia failureReason
EXPIREDCrie outra jornada se ainda for necessário

A resposta inclui purpose, referenceId, document, provider, method, expiresAt, failureReason, completedAt, consumableUntil e consumedAt quando aplicáveis. verificationLink só existe em PENDING com method: link. Com method: facetec_sdk vêm também referenceMatch, attemptsRemaining e checks (liveness e faceMatch.result/faceMatch.reference); liveness_failed e face_mismatch são os failureReason específicos do SDK.

Consumir

curl -X POST \
"https://client.api.corpx.com/v1/identity-verifications/$VERIFICATION_ID/consume" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-Id: $TENANT_ID" \
-H "X-Request-Timestamp: $TS" \
-H "X-Content-SHA256: $BODY_SHA256" \
-H "X-Request-Signature: $SIGNATURE" \
-H "Content-Type: application/json" \
-d '{
"purpose": "second_factor_reset",
"referenceId": "reset_01J8Y6N7M8P9Q0R1S2T3"
}'

A finalidade e a referência precisam coincidir exatamente com a criação. A primeira chamada válida grava consumedAt. Repetir o mesmo id e o mesmo corpo é idempotente; finalidade/referência diferentes, consumo concorrente, estado não aprovado ou janela vencida respondem 409.

Consuma no backend imediatamente antes da ação protegida. Ver APPROVED no GET não reserva a prova e, sozinho, não impede reutilização concorrente.

Callback e webhook

A callbackUri só devolve o navegador. Ela precisa ser idêntica à URI cadastrada — sem wildcard, prefixo ou normalização — e não prova o resultado.

identity.verification.completed é enviado para APPROVED, FAILED e EXPIRED, com X-Signature. Valide os bytes brutos e deduplique pelo id do envelope. Exemplo completo em Webhooks da conta.

Evidências

GET /v1/identity-verifications/{verificationId}/artifacts exige kyc.read no lugar do escopo de gerenciamento e a feature kyc_artifacts. Assine a chamada como qualquer outra no host client. O retorno pode conter biometria e evidências do provedor; não registre URLs nem conteúdo em logs.

Erros principais

HTTPerrorCodeSignificado
400invalid_document, invalid_purpose, invalid_reference_idCampo de criação inválido
400invalid_display_message, invalid_verification_ttl, invalid_consume_ttlTexto ou intervalo inválido
400invalid_callback_uriA URI não coincide exatamente com o cadastro
400invalid_provider, invalid_method, invalid_reference_matchCombinação inválida de provider, method e referenceMatch
400reference_image_requiredModo image sem referenceImage no /facetec/process
403feature_disabledFeature desligada
403facetec_sdk_not_enabledFeature identity_verification_facetec_sdk ou chaves do SDK ausentes
403identity_verification_kind_not_enabledO tipo (details.kind) tem cota 0
403insufficient_scopeFalta identity_verification.manage ou kyc.read
403forbiddenA chamada não veio da master M2M
404verification_not_foundId inexistente neste tenant
409verification_not_consumableEstado, janela ou vínculo de consumo incompatível
409reference_already_consumedOutra prova já autorizou esta finalidade/referência
409verification_method_mismatch, verification_not_pendingRota incompatível com o method ou o estado
409facetec_process_in_progressOutra captura em curso; aguarde Retry-After
409facetec_session_expiredRenove em /facetec/session
413payload_too_largerequestBlob acima de details.maxBytes
415unsupported_media_typeFalta Content-Type: application/json
422facetec_match_unavailableModo de match indisponível no provedor
429identity_verification_monthly_limit_exceededCota do tipo (details.kind) fechada no mês BRT
429facetec_attempts_exhaustedExcesso de capturas; a verificação falhou
429facetec_session_renewal_limitedRenovação de sessão muito frequente
429rate_limitedLimite de tráfego, separado da cota
502provider_errorFalha no provedor (veja partner)
503facetec_unavailableSDK indisponível no provedor