Skip to navigation

Captura facial (link e SDK FaceTec)

A captura facial aparece em dois produtos. Nos dois, a pessoa mostra o rosto ao vivo; a diferença é quem abre a câmera.

ProdutoQuando usarCaptura por linkCaptura pelo SDK no seu app
Abertura de conta com biometria centralizadaOnboarding PF/PJ, desligada por padrãopersons[].biometryLink abre a página hospedadaPOST /v1/accreditations/{id}/capture e o app relê os blobs
Verificação de identidade (API paga à parte)Provar o CPF antes de uma ação sensívelmethod: link devolve verificationLinkmethod: facetec_sdk e o app chama /facetec/process

Este guia cobre as duas formas na abertura. A verificação de identidade usa o mesmo SDK FaceTec v10, com rotas e cotas próprias — o pedido do pacote (bundle id, domínio) é o mesmo.

O app não fala com a FaceTec nem com a Dracma. Quem fala é a API CorpX. Embutir o SDK sem o pacote emitido para o seu aplicativo falha no initialize (RejectedByServer): o identificador do binário não está na allowlist.

Não baixe o SDK por conta

O FaceTec é licenciado pelo provedor de biometria do tenant. Um zip baixado na conta de desenvolvedor da FaceTec não autentica as sessões da CorpX. Peça o pacote ao suporte, com os identificadores abaixo; a CorpX devolve o zip e cadastra a chave.

Pedir o SDK

Escreva para suporte@corpx.com antes de embutir a câmera. Um pacote vale para um aplicativo. Trocar o bundle id, o application id ou o domínio depois de emitido exige outro pedido.

Informe, para cada app (produção e, se houver, homologação):

CampoObrigatório emExemplo
Tenanttodostenant-suaempresa
Produtotodosabertura (accreditation_central_kyc) e/ou verificação de identidade (identity_verification_facetec_sdk)
Application Nametodosnome que a FaceTec usa no pacote, ex. Banco X iOS
Plataformatodosbrowser, ios, android, react_native, flutter ou cordova
Bundle IdentifieriOS e quem empacota iOS (React Native, Flutter, Cordova)br.com.banco.app (CFBundleIdentifier)
Application IDAndroid e quem empacota Androidbr.com.banco.app (applicationId do Gradle)
DomíniosBrowser SDK e WebViewapp.banco.com, onboarding.banco.com — hosts de produção, sem path
Ambientetodosprodução e/ou desenvolvimento

Um app React Native, Flutter ou Cordova envia os dois identificadores nativos (iOS e Android), porque o binário que a loja instala é o nativo. Um PWA ou página própria envia só os domínios.

A CorpX:

  1. pede o pacote FaceTec v10 amarrado a esses identificadores;
  2. entrega o zip (não redistribua; a licença é do aplicativo);
  3. na verificação de identidade, cadastra o deviceKeyIdentifier no tenant;
  4. na abertura, a chave da sessão vem de POST .../capture/{token}/start (sdk.key) — o zip ainda precisa ser o da mesma versão.

O deviceKeyIdentifier não é segredo: vai embutido no app e sai no 201 da verificação de identidade. O que não pode vazar é o zip, nem um bundle id diferente do pedido.

Sem esse cadastro, method: facetec_sdk responde 403 facetec_sdk_not_enabled. A página hospedada da abertura não precisa do zip no seu repositório: ela carrega o Browser SDK nos assets da CorpX.

Plataformas e idiomas

O que a FaceTec publica e o que este fluxo aceita:

PacoteLinguagem do appOnde a CorpX usa
Browser SDK v10JavaScriptPágina hospedada da abertura; PWA / site próprio
iOS SDK v10Swift ou Objective-CApp nativo iOS 12+
Android SDK v10Kotlin ou JavaApp nativo Android 5+
React Native, Flutter, Cordovaa linguagem do wrappero wrapper chama o SDK iOS/Android; peça o zip desses sample apps

Não há pacote C#, Python ou Go para a câmera. O backend só relê requestBlob / responseBlob.

A interface do SDK aceita mais de 30 idiomas (localização da FaceTec). A página hospedada da CorpX carrega FaceTecStrings.pt-br.js e fala português brasileiro com o titular. No app próprio, use o FaceTecStrings.{locale}.js que veio no zip e FaceTecSDK.configureLocalization. Pedido novo de pacote não troca o idioma: isso é arquivo de strings, não chave.

A versão tem de ser v10. O protocolo antigo (v9: faceScan / scanResultBlob, PEM, productionKeyText) não funciona nestas rotas. Na abertura, sdk.version do /start é a versão dos assets (hoje a linha 10.1.x); use exatamente esse zip.

HTTPS e câmera

No Browser SDK a câmera só abre em https (ou localhost no zip de desenvolvimento). HTTP remoto falha com GetUserMediaRemoteHTTPNotSupported. WebView precisa da permissão de câmera da plataforma nativa, não só da página.

Use quando você não controla o dispositivo — WhatsApp, e-mail, webview simples, onboarding no desktop.

Não envie o objeto biometry. O 201 de POST /v1/accreditations/pf ou /pj traz o link na pessoa que captura (na PJ, só o administrador):

{
"accreditationId": "acr_01J8Y7C8D9E0F1G2H3J4",
"status": "PENDING_BIOMETRY",
"persons": [
{
"personId": "prs_3b1c9a7f2e4d",
"biometryLink": "https://tenant.api.corpx.com/v1/accreditations/capture/{token}"
}
]
}

Entregue biometryLink só a essa pessoa. O token no path é a credencial: não manda JWT, vale 24 h, e um POST /v1/accreditations/{id}/capture (ou o retry da pessoa) invalida o anterior.

loop [cada blob do SDK] POST /v1/accreditations/pf ou /pj 201 com persons[].biometryLink abre o link GET /v1/accreditations/capture/{token} POST .../start sessionToken, sdk.version, sdk.key POST .../session (requestBlob) responseBlob, status GET .../done redirect ao callbackUri com outcome Seu sistema Titular Página hospedada API CorpX

O titular toca Iniciar verificação facial. A página carrega o Browser SDK em /v1/accreditations/capture/assets/{versão}/core-sdk/…, pede a câmera, relê os blobs e, no fim, chama GET .../done. Essa rota relê a verificação e manda o navegador de volta ao seu callbackUri com outcome:

outcomeSignificado
biometry_approvedIdentidade aprovada no provedor
biometry_pendingA captura saiu e o provedor ainda consolida — o caso mais comum; espere o webhook
biometry_failedReprovada; cabe retry da pessoa
biometry_expiredLink ou verificação vencidos; peça outro
errorFalha de leitura no /done; consulte o GET do credenciamento

O outcome escolhe a tela. O estado autoritativo continua no webhook de onboarding e no GET /v1/accreditations/{id}.

Quem reabre o mesmo link depois de concluir vê o desfecho, não a câmera. Sem callbackUri cadastrada, a página mostra o resultado e para.

Abertura: captura pelo SDK no seu app

Use quando o titular já está no seu iOS, Android ou web app e você quer a câmera ali, sem sair para o browser da CorpX.

1. Token de captura

Enquanto o credenciamento está PENDING_BIOMETRY:

curl -X POST "https://tenant.api.corpx.com/v1/accreditations/$ACR_ID/capture" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-Id: $TENANT_ID"
{
"accreditationId": "acr_01J8Y7C8D9E0F1G2H3J4",
"captureToken": "…",
"expiresAt": "2026-10-17T12:00:00Z",
"captureUrl": "https://tenant.api.corpx.com/v1/accreditations/capture/…"
}

captureUrl é a página hospedada, se você quiser cair nela. No app, o que importa é captureToken: ele entra no path das rotas públicas abaixo. Não mande JWT nelas. Cada emissão apaga o token anterior. Fora de PENDING_BIOMETRY, a resposta é 409 capture_not_available.

2. Inicializar o SDK

No momento de abrir a câmera — não no boot do app:

curl -X POST "https://tenant.api.corpx.com/v1/accreditations/capture/$CAPTURE_TOKEN/start"
{
"sessionToken": "…",
"expiresAt": "2026-10-16T12:10:00Z",
"sdk": {
"version": "10.1.21",
"key": "…"
}
}

Carregue o zip dessa sdk.version. No Browser SDK v10:

  1. FaceTecSDK.setResourceDirectory / setImagesDirectory para as pastas do zip (core-sdk/FaceTecSDK.js/resources, core-sdk/FaceTec_images);
  2. configureLocalization com o FaceTecStrings do idioma;
  3. initializeWithSessionRequest(sdk.key, processor).

O processor implementa onSessionRequest(requestBlob, cb) e onFaceTecExit. O init já gera um requestBlob e conta no teto de 15 chamadas. Guarde sessionToken no seu backend e ecoe em cada /session; o SDK v10 não expõe o id da sessão ao app.

No iOS/Android o sample app do zip mostra o equivalente (initialize + session request). O fio com a CorpX é o mesmo: cada blob vai ao /session.

3. Relé de cada blob

curl -X POST "https://tenant.api.corpx.com/v1/accreditations/capture/$CAPTURE_TOKEN/session" \
-H "Content-Type: application/json" \
-H "X-FaceTec-User-Agent: $UA" \
-d '{
"requestBlob": "<base64 do SDK>",
"sessionToken": "<sessionToken do /start>"
}'

requestBlob e sessionToken são obrigatórios. Corpo de até 5 MB (413 payload_too_large).

Headers opcionais, só se o seu SDK gerar:

  • X-FaceTec-User-Agent — FaceTecSDK.createFaceTecAPIUserAgentString("");
  • X-Testing-API-Header — FaceTecSDK.getTestingAPIHeader(), nos zips de desenvolvimento.

A API só repassa. Não invente valor.

Resposta 200:

{
"responseBlob": "…",
"status": "pending",
"retryAllowed": true
}

Devolva responseBlob ao SDK (processResponse no Browser SDK). status:

  • pending — handshake ou captura sem veredito; não conta tentativa reprovada; o SDK pede outro round;
  • outro valor (approved, rejected, …) — houve veredito; rejected conta nas 3 falhas.

Não interprete o blob. Não chame o provedor.

Quando a sessão do SDK encerrar com veredito, mande o titular ao GET /v1/accreditations/capture/{token}/done (webview) ou consulte o credenciamento / webhook. O /done é o mesmo da página hospedada: relê a verificação e devolve o outcome no callbackUri.

TetoErro
Token com 24 h410 capture_expired — emita outro
3 capturas processadas e reprovadas422 capture_failed_limit
15 chamadas a /start+/session (inclui handshake)429 capture_call_limit
Uma chamada por vez409 capture_in_progress
Verificação ainda não gravada409 capture_not_available (tente de novo em segundos)
Credenciamento fora de PENDING_BIOMETRY409 capture_not_available

Retry da pessoa (PF) ou do administrador (PJ) emite token novo. Sócio que não é administrador recebe 422 administrator_required.

Verificação de identidade

API paga, independente de conta bancária. POST /v1/identity-verifications com method: link devolve verificationLink (página do provedor). Com method: facetec_sdk (exige provider: dracma_trust e o pacote cadastrado) o 201 traz facetec.deviceKeyIdentifier e facetec.sessionToken; cada captura vai a POST /v1/identity-verifications/{id}/facetec/process.

O pedido do zip (bundle id, application id, domínios) é este da seção Pedir o SDK. O protocolo no app — initializeWithSessionRequest, requestBlob / responseBlob, 3 tentativas, 15 chamadas, token de 10 min — está no guia de verificação de identidade. Não misture as rotas: captura de abertura não chama /facetec/process; verificação de identidade não usa /accreditations/capture.

O que não fazer

  • Chamar a FaceTec ou a Dracma com o sessionToken / sdk.key. A sessão só vale nas rotas da CorpX.
  • Reusar um zip de outro aplicativo, outro tenant ou da conta gratuita da FaceTec.
  • Mudar o bundle id no store e continuar com o mesmo zip.
  • Tratar callbackUri / outcome como prova: o webhook e o GET é que fecham o estado.
  • Traduzir errorCode da API para um genérico. A tela precisa do código original (capture_expired, facetec_sdk_not_enabled, …).
  • Logar requestBlob, responseBlob, sessionToken ou selfie.