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 umverificationLinkque 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 paraPOST /v1/identity-verifications/{id}/facetec/process. Exigeprovider: dracma_trust, a featureidentity_verification_facetec_sdke 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.
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_credentialsda master; - host
https://client.api.corpx.come os três headers de assinatura; X-Tenant-Id;- escopo
identity_verification.manage; - feature
identity_verificationhabilitada para criar jornadas; callbackUricadastrada em Verificações de identidade no painel, com comparação exata.
O download de evidências usa o escopo dedicado kyc.read.
Criar
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:
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:
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).
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
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
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.