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.
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.
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):
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:
- pede o pacote FaceTec v10 amarrado a esses identificadores;
- entrega o zip (não redistribua; a licença é do aplicativo);
- na verificação de identidade, cadastra o
deviceKeyIdentifierno tenant; - 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:
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.
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.
Abertura: captura pelo link
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):
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.
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:
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:
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:
Carregue o zip dessa sdk.version. No Browser SDK v10:
FaceTecSDK.setResourceDirectory/setImagesDirectorypara as pastas do zip (core-sdk/FaceTecSDK.js/resources,core-sdk/FaceTec_images);configureLocalizationcom oFaceTecStringsdo idioma;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
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:
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;rejectedconta 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.
Limites do link
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/outcomecomo prova: o webhook e oGETé que fecham o estado. - Traduzir
errorCodeda API para um genérico. A tela precisa do código original (capture_expired,facetec_sdk_not_enabled, …). - Logar
requestBlob,responseBlob,sessionTokenou selfie.