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 umverificationLinkque 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 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.
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_verificationhabilitada para criar jornadas; callbackUricadastrada 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
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:
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.
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:
Fluxo no app (Browser SDK v10):
- Guarde o
sessionTokenno backend. Inicialize o SDK só comdeviceKeyIdentifier(FaceTecSDK.initializeWithSessionRequest). O init já gera umrequestBlobe conta no limite de 15 chamadas. - A cada
requestBlob(o do init e o de cada captura, 1–3 MB em base64), envie uma chamada aPOST /v1/identity-verifications/{id}/facetec/processcomContent-Type: application/json,sessionIdigual aosessionTokene, no modoimage, areferenceImage(JPEG/PNG em base64, até 2 MB; foto de rosto, nunca de documento). - Devolva
responseBlobao SDK emprocessResponse. A resposta também trazprocessed,status,attemptsRemaining,checkse, em falha definitiva,failureReason. - Se o token da sessão venceu (10 minutos) ou o
/processrespondeu409 facetec_session_expired, peça outro emPOST /v1/identity-verifications/{id}/facetec/sessione reabra o SDK.
Limites da jornada:
- 3 capturas reprovadas encerram a verificação como
FAILED(liveness_failedouface_mismatch). Capturas que o provedor não processou (processed: false, por exemplo imagem fora de foco) não contam. - Até 15 chamadas a
/processpor verificação; a 16ª responde429 facetec_attempts_exhaustede a verificação falha. - Uma captura por vez: enquanto uma chamada está em curso, outra responde
409 facetec_process_in_progresscomRetry-After. - Corpo de até 5 MB; acima disso,
413 payload_too_large(details.maxBytes). /facetec/sessionpode ser chamado a qualquer momento enquantoPENDING, com freio de 1 a cada 5 s e 30 por verificação (429 facetec_session_renewal_limited).
Os modos de match
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
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:
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
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.