Catalisa.Building Blocks
Catálogo/Identidade/Biometrics

Biometrics

Alpha

Prova de vida e match facial com motor próprio, no contrato dos provedores certificados

35
Endpoints
7
Entidades
2
Provedores
Tenant
Escopo
3034
Porta
2026-09
Desde

A pessoa diante da câmera está viva e é a mesma do documento? Sessão, página de captura hospedada, decisão explicável com score, limiar e versão de modelo, e evidência assinada — com um nível de garantia declarado, para que a aprovação do motor aberto nunca pareça a de um provedor certificado.

Para quem é
  • Fintechs que abrem conta ou concedem crédito e precisam de KYC com prova de vida antes de fechar contrato com FaceTec ou Unico
  • Produtos que confirmam operação de alto valor pela face de um cliente já cadastrado, como segundo fator
  • Times que precisam provar à auditoria como cada verificação foi decidida, com qual modelo, qual limiar e qual evidência
Substitui
  • O SDK do provedor colado direto no app, com a decisão tomada no front
  • A selfie comparada com o documento sem prova de vida, que uma foto impressa engana
  • O contrato com provedor fechado antes de saber quanto a própria base vai exigir
O que não é
  • Documentoscopia — lê MRZ e QR, mas não diz se o RG é verdadeiro
  • Consulta a bureau, score ou listas restritivas
  • Reconhecimento 1:N em multidão ou vigilância
  • Um cadastro de clientes — guarda o rosto e a decisão, e se liga ao Customers pelo customerId
O que dá para fazer

37 endpoints em 5 recursos.

Explorar a API →

Telas

o que o usuário vê

Toque numa tela para ampliar.

Convite para testar
Convite para testarA página que a pessoa recebe por link. Pede o consentimento e rotula o que vai aparecer na câmera — ela mesma, foto impressa, foto ou vídeo numa tela, máscara — nas espécies da ISO/IEC 30107-3.
Convite para testar
Convite para testarA página que a pessoa recebe por link. Pede o consentimento e rotula o que vai aparecer na câmera — ela mesma, foto impressa, foto ou vídeo numa tela, máscara — nas espécies da ISO/IEC 30107-3.
Antes de abrir a câmera
Antes de abrir a câmeraO roteiro aparece antes de começar, com o número de gestos sorteado para esta sessão. Nada é gravado até a pessoa clicar.
Preparo antes de gravar
Preparo antes de gravarO primeiro gesto aparece com uma contagem de 2,5 s antes de a gravação começar. A pessoa lê com calma e a câmera acerta a luz.
Guia ao vivo
Guia ao vivoO rosto é lido no próprio navegador e o selo confirma quando o gesto foi feito. O vídeo está escondido nesta imagem por privacidade; na captura real a pessoa se vê.
Dica durante o gesto
Dica durante o gestoQuando o gesto está incompleto, a página diz o que falta em vez de esperar a reprovação. O ícone do rosto mostra o movimento.
O próximo gesto
O próximo gestoO próximo passo é anunciado antes de a janela dele começar, para a pessoa ler com calma. Cada janela tem duração sorteada.
Nova tentativa
Nova tentativaUma falha de uso, como gesto fora do tempo, vira nova tentativa com o motivo em linguagem simples. Suspeita de fraude não ganha explicação.
Modo avaliação
Modo avaliaçãoNas organizações de avaliação, como laboratório e pré-teste, a página mostra o código da sessão e a tentativa para o avaliador registrar cada apresentação.
Resultado para o avaliador
Resultado para o avaliadorNo modo avaliação, o fim da captura mostra o resultado. Em qualquer outra organização a página encerra sem revelar a decisão.
Resultado para o avaliador
Resultado para o avaliadorNo modo avaliação, o fim da captura mostra o resultado. Em qualquer outra organização a página encerra sem revelar a decisão.
Concluída
ConcluídaA página encerra sem dizer se aprovou. O resultado vai para o sistema da empresa, por webhook ou consulta, nunca para quem está diante da câmera.
01

Resumo executivo

O Biometrics responde a duas perguntas sobre quem está diante da câmera: está vivo? e é a mesma pessoa? — do documento, na abertura de conta, ou do cadastro facial, na autenticação.

O sistema da empresa abre uma sessão, manda a pessoa para a página de captura hospedada pelo bloco e recebe de volta uma decisão explicada: cada verificação com o score, o limiar usado e a versão do modelo, mais uma evidência assinada que qualquer um confere sem depender da Catalisa.

Por trás, um motor próprio, o face-engine, montado sobre modelos de pesos abertos e rodando na nossa infraestrutura: nenhuma imagem de rosto sai para terceiro. FaceTec, Unico e Serpro Datavalid estão declarados no mesmo contrato e entram como drivers quando houver credencial.

Sessões genuínas medidas59, nenhuma reprovada pelo liveness passivo
Match contra o cadastro facial feito pelo bloco0,95
Avaliação de uma sessão de celular~8 s
Imagens de rosto enviadas a terceirosnenhuma

Segurança em seis camadas, nível de garantia ENHANCED, em conformidade com os requisitos da ISO/IEC 30107-3

CamadaContra o quê
Liveness passivoFoto impressa, foto ou vídeo exibidos numa tela
Desafio ativo sorteadoVídeo gravado e reinjetado — gestos, ordem e duração mudam a cada sessão
Continuidade de identidadeTroca de pessoa durante a captura
Integridade da capturaCâmera virtual e troca de dispositivo entre tentativas, que vão para revisão
Bloqueio por titularTentativas em série contra o mesmo CPF
Evidência assinada em Ed25519Alteração do resultado depois da decisão

O Biometrics segue os requisitos e as recomendações das normas de mercado para biometria facial — ISO/IEC 30107-1 e 30107-3 na detecção de ataque, ISO/IEC 19795-1 nas métricas de desempenho, ICAO 9303 na leitura de documento e LGPD no tratamento do dado. Não é homologado nem certificado por laboratório: a certificação iBeta está no roadmap, e até lá a conformidade é declarada pela Catalisa e demonstrada pelo relatório de avaliação no formato da ISO/IEC 30107-3.

Em teste de injeção por câmera virtual, um vídeo genuíno de uma sessão aprovada, reinjetado numa sessão nova, foi reprovado pelo desafio sorteado. Onde a operação exigir certificação de laboratório, os drivers CERTIFIED entram no mesmo contrato, sem mudar a integração.


02

O problema

negócio

Abrir conta pelo celular exige saber que a pessoa é quem diz ser. O jeito comum de resolver é comparar uma selfie com a foto do documento — e uma selfie é só uma foto. Uma foto impressa do rosto de outra pessoa passa, e uma foto na tela do celular também.

Os provedores que resolvem isso bem, como FaceTec, iProov e Unico, cobram por verificação em contrato anual, e o SDK deles decide dentro do app. Três consequências aparecem depois:

  • A decisão é caixa-preta. Quando a verificação reprova um cliente bom, o time não sabe se foi luz, câmera, limiar ou modelo. Quando aprova um fraudador, também não.
  • A auditoria não tem o que ver. A LGPD trata biometria como dado sensível, e "o fornecedor aprovou" não é evidência de como a decisão foi tomada.
  • Trocar de fornecedor é reescrever. Cada SDK tem fluxo, formato de resposta e vocabulário de erro próprios, e a integração vira dívida no dia em que o contrato muda.

03

Proposta de valor

negócio
  • Prova de vida em camadas. Passiva, por modelo que distingue pele de papel e de tela, e ativa, com gestos sorteados em quantidade, ordem e duração a cada sessão.
  • Continuidade de identidade. O rosto do começo do vídeo tem que ser o do fim: trocar de pessoa no meio reprova.
  • Decisão explicável. Nove status em vez de dois. INCONCLUSIVE vai para revisão humana (LGPD art. 20); RETRY_ALLOWED é experiência de uso, porque foto escura não é fraude.
  • Evidência assinada. Hash do vídeo, do melhor quadro, da referência, dos checks e da política, assinado com chave Ed25519 da organização. A evidência nunca cita arquivo que não exista: ou a mídia foi guardada e confirmada (media.mode: RETAIN), ou a política mandou descartá-la (media.mode: DISCARD, artifacts: [], com o motivo). Upload que não confirma não aprova sessão: ela vai para ERROR com EVIDENCE_MEDIA_NOT_STORED, sem template e sem evidência assinada — e a tentativa não é consumida.
  • Garantia declarada. O driver diz o que entrega — BASIC, ENHANCED ou CERTIFIED — e a política exige um mínimo. O motor aberto é ENHANCED.
  • Página de captura pronta, com a cor, o logo e os textos da empresa, contagem de preparo antes de gravar e guia ao vivo que diz o que falta no gesto.
  • Tudo parametrizável pela empresa: quantos gestos, quais, quanto tempo cada um, limiares, bloqueio por titular, retenção. Sem deploy.

04

Casos de uso reais

negócio

Abertura de conta com documento

[Cenário ilustrativo] Fintech de crédito pessoal abre conta pelo celular e precisa de KYC com prova de vida.

A dor. A comparação da selfie com a foto do documento, sozinha, aprova uma foto impressa, e o fornecedor certificado custa mais por verificação do que a margem da primeira operação.

A solução com o bloco. Sessão ONBOARDING com a foto do documento como referência e enrollOnApprove: true. Na criação, o bloco lê a MRZ do passaporte ou o QR da CNH digital e recusa documento vencido se a política pedir. Depois avalia liveness e match e, ao aprovar, já grava o cadastro facial da pessoa.

O resultado. Validado em staging com passaporte e rosto reais: aprovado na primeira tentativa, match 0,702 contra o documento.

Confirmação de operação de alto valor

[Cenário ilustrativo] O mesmo cliente, meses depois, pede um saque acima do limite habitual.

A dor. SMS e senha provam posse de aparelho e conhecimento, não presença.

A solução com o bloco. Sessão AUTHENTICATION com referência ENROLLED_TEMPLATE. A comparação é contra o rosto que o próprio bloco capturou, não contra a foto do documento.

O resultado. Match 0,951 contra o cadastro feito pelo próprio bloco — o desenho é "documento uma vez, cadastro facial depois". E cinco falhas seguidas do mesmo CPF em uma hora bloqueiam o titular por 30 minutos.

Guia ao vivo durante a captura, com o selo de gesto confirmado
Guia ao vivo durante a captura, com o selo de gesto confirmado

Calibrar antes de contratar

[Cenário ilustrativo] Antes de decidir qual provedor contratar, é preciso saber como a própria base se comporta: quantos genuínos o sistema reprova, e por quê.

A solução com o bloco. Link de convite (POST /invites) compartilhado com voluntários. Cada pessoa rotula o que vai mostrar à câmera — ela mesma, uma foto impressa, uma tela, uma máscara — e o relatório cruza o rótulo com a decisão.

O resultado. Na medição em staging, nenhuma das 59 sessões genuínas foi reprovada pelo liveness; os ajustes ficaram no tempo e na leitura dos gestos, cada um com teste de regressão sobre as sessões reais gravadas.

Convite para voluntários, com o rótulo do que vai aparecer na câmera
Convite para voluntários, com o rótulo do que vai aparecer na câmera


05

Mercado e diferenciais

negócio

O mercado de biometria facial tem três faixas. Os provedores certificados — FaceTec, iProov — vendem prova de vida auditada por laboratório. As redes de identidade — Unico — vendem a base compartilhada de rostos e fraudes. E a fonte primária estatal — Serpro Datavalid — compara com a foto da base oficial, sem prova de vida.

O bloco é a camada que fala com todos, com um motor próprio que atende sem contrato de terceiro.

Integração direta com o SDKCom o Biometrics
Onde a decisão aconteceNo app, dentro do SDKNo servidor, com a política da empresa
Por que reprovouCódigo do fornecedorMotivo, score, limiar e modelo por verificação
Evidência para auditoriaLog da aplicaçãoHashes assinados em Ed25519, verificáveis fora da Catalisa
Revisão humanaA empresa montaStatus INCONCLUSIVE e evento próprio
Trocar de fornecedorReescrever a captura e o parserTrocar a configuração
Custo em volume baixoMínimo contratualMotor próprio, sem custo por consulta a terceiro

Quando escolher o concorrente. Quando a regulação ou um parceiro exigir certificação de laboratório, a FaceTec ou a iProov entram como driver CERTIFIED no próprio bloco, mantendo política, evidência e trilha. Para somar o sinal de fraude compartilhado entre instituições, a Unico entra da mesma forma.


06

Modelo de cobrança e ROI

negócio

Unidade: sessão de verificação avaliada — a que chegou a uma decisão. Erro do motor, link vencido e desistência antes do envio não entram na conta.

Preço público (catalisa.app, plano por organização vendida):

PlanoMensalidadeInclusasExcedente
LivreR$ 030— (bloqueia; 402 QUOTA_EXCEEDED)
StartR$ 199300R$ 0,79
GrowthR$ 9902.000R$ 0,55
ScaleR$ 3.90010.000R$ 0,39
Acima de 50 mil/mêsnegociado—motor certificado e SLA em contrato

Sessão de ambiente test nunca é cobrada nem consome franquia.

Drivers de custo: sessões avaliadas, tentativas por sessão (o limite padrão é 3), o fornecedor quando não for o motor próprio, e a retenção de mídia, que por padrão é de 30 dias.

Com o motor próprio não há custo por consulta a terceiro: o custo é CPU. Uma sessão de celular leva cerca de 8 segundos de avaliação num nó de 4 vCPUs, e o motor escala horizontalmente por réplica.

Com um driver externo, o custo do fornecedor fica registrado por sessão. Em ambos os casos o consumo vai ao Billing no medidor biometrics.verification, com o id da sessão como chave de idempotência.


07

Arquitetura

flowchart TB
  TENANT["Sistema da empresa<br/>backend"]
  PESSOA["Pessoa<br/>navegador ou app"]

  subgraph BIO["Building Block Biometrics"]
    SESSAO["POST /sessions<br/>política e sorteio dos gestos"]
    PAGINA["Página de captura<br/>token de uso único"]
    SUBMIT["Submissão<br/>vídeo e telemetria"]
    DECISAO["Decisão<br/>checks, limiares, status"]
    EVID["Evidência<br/>hashes assinados Ed25519"]
  end

  ENGINE["face-engine<br/>motor próprio"]
  EXT["FaceTec, Unico, Serpro<br/>drivers declarados"]
  FS["File Storage<br/>vídeo e documento"]
  EVT["Webhooks Engine<br/>biometrics.session.completed"]

  TENANT --> SESSAO
  SESSAO -- "captureUrl" --> TENANT
  TENANT -- "link ou iframe" --> PESSOA
  PESSOA --> PAGINA
  PAGINA --> SUBMIT
  SUBMIT --> ENGINE
  SUBMIT -.-> EXT
  SUBMIT --> FS
  ENGINE --> DECISAO
  DECISAO --> EVID
  EVID --> EVT
  EVT --> TENANT

O motor. O face-engine é um serviço separado, em Python, que só o bloco alcança, com bearer próprio. Ele encadeia modelos de pesos abertos, todos publicados por terceiros com licença permissiva:

EtapaModeloLicença
Detecção de rostoYuNetMIT
Liveness passivoMiniFASNetApache-2.0
Pontos do rosto e gestosMediaPipe Face LandmarkerApache-2.0
Comparação de rostosFacenet512MIT
MRZ do passaporte e QR da CNH-eTesseract e zxing-cppApache-2.0

Os pesos são fixados por hash em models.lock.json: trocar um modelo muda a versão do motor, e a versão sai em todo check.

O que o bloco não faz, e quem faz

Não fazQuem faz
Guardar o vídeo e o documentoFile Storage
Entregar o resultado por HTTP ao sistema da empresaWebhooks Engine
Consultar CPF em bureauBureaus
Extrair campos do documento para o cadastroData Extraction
Dizer se o documento é autênticoDocumentoscopia — fora do escopo

08

Conceitos e modelo de dados

Glossário

TermoSignifica
SessãoUma verificação, do pedido à decisão. Aceita até maxAttempts tentativas
FluxoONBOARDING (com documento), AUTHENTICATION (com cadastro facial), ENROLLMENT (só cadastra), LIVENESS_ONLY e DEDUP (reservado)
ReferênciaContra o que o rosto é comparado: DOCUMENT_IMAGE, FILE, ENROLLED_TEMPLATE, PROVIDER_BASE. SUBJECT_TEMPLATE é a forma de pedir "o cadastro ativo mais recente do titular de subjectRef" e é gravada como ENROLLED_TEMPLATE
TemplateO cadastro facial: o vetor do rosto, cifrado com chave própria. Nunca sai do bloco
Âncora (anchorBasis)Por que um cadastro prova de QUEM é o rosto: provider_base (base oficial), document_cpf_match (foto de documento com o CPF impresso lido e igual ao do titular) ou document_face_match_no_cpf_check (MODO DEMONSTRAÇÃO: rosto bate com o documento, CPF não conferido — âncora FRACA). Gravada no cadastro com o fornecedor, a versão do modelo e o leitor do documento (anchorDetail), para reavaliar quando o modelo for retreinado ou o fornecedor trocado
captureTokenToken curto, de uso único por tentativa, que é tudo o que a página de captura recebe
CheckUma verificação: quality.capture, liveness.passive, liveness.active, identity.continuity, match.1_1, capture.integrity
GarantiaBASIC, ENHANCED ou CERTIFIED. Declarada pelo driver, exigida pela política
Vínculo (binding)O SHA-256 da operação que a sessão autoriza. Amarra a selfie àquilo que ela liberou

Modelo de dados

Modelo PrismaPropósitoCampos-chave
BiometricsProviderConfigFornecedor por organizaçãoproviderType, credencial cifrada, appearance, allowedEmbedHosts
BiometricsPolicyPolítica por organizaçãolimiares, challenge, lockout, retention, minAssurance
BiometricsSessionA verificação e a decisãoflow, status, titular em HMAC, operationHash do vínculo, decision, evidência
BiometricsCaptureCada tentativahashes, fileId da mídia, telemetria, checks
BiometricsTemplateCadastro facialvetor cifrado, versão do modelo, titular em HMAC
BiometricsSigningKeyChave Ed25519 da organizaçãokeyId, chave pública, privada cifrada
BiometricsUsageConsumo medidosessão, fornecedor, custo

Status de uma sessão

StatusTerminalO que fazer
SESSION_OPENnãoAguardando a captura
PROCESSINGnãoAvaliando
APPROVEDsimSeguir
REJECTEDsimRecusar. Conta para o bloqueio do titular
INCONCLUSIVEsimRevisão humana (ou recusa, se a política pedir onInconclusive: REJECT)
RETRY_ALLOWEDnãoA página oferece nova tentativa com o motivo
EXPIREDsimAbrir nova sessão
CANCELLEDsimCancelada pela empresa
ERRORnãoFalha do motor ou da guarda da mídia. O único que merece nova tentativa automática. errorCode: EVIDENCE_MEDIA_NOT_STORED quer dizer que o file-storage não confirmou o upload: a sessão não aprovou de propósito, nada foi gravado desta tentativa e o evento biometrics.session.media_not_stored foi para a trilha

Os motivos da decisão formam um vocabulário fechado, com namespace, que a esteira da empresa pode automatizar: quality.too_dark, liveness.passive.failed, liveness.active.gesture_missing, liveness.active.timeout, identity.continuity_broken, match.below_threshold, match.gray_zone, capture.injection_suspected, capture.device_changed, policy.assurance_insufficient, subject.locked, entre outros — 27 no total.

Vínculo com a operação (step-up transacional)

Uma selfie aprovada prova que alguém esteve vivo diante da câmera. Não prova o que aquela pessoa autorizou — e é isso que falta quando a verificação libera dinheiro. Sem vínculo, a evidência de qualquer sessão aprovada da mesma organização serve para qualquer operação: basta apresentar a de ontem.

O vínculo fecha essa porta. Quem vai autorizar calcula o SHA-256 da operação exata (o que for canônico para ele: tipo, valor, destino, referência) e abre a sessão com ele:

json
{ "flow": "AUTHENTICATION", "purpose": "autorizar Pix acima do limite",
  "reference": { "source": "ENROLLED_TEMPLATE", "templateId": "…" },
  "binding": { "operationHash": "3f2a…64 hex minúsculos" } }
{ "flow": "AUTHENTICATION", "purpose": "autorizar Pix acima do limite",
  "reference": { "source": "ENROLLED_TEMPLATE", "templateId": "…" },
  "binding": { "operationHash": "3f2a…64 hex minúsculos" } }

O bloco nunca vê a operação, só o hash. A evidência dessa sessão passa a ser assinada em v2, sobre v2|${sessionId}|${attempt}|${bundleHash}|${signedAt}|${operationHash}, e a assinatura leva version: 2 e operationHash. Sessão sem vínculo continua saindo em v1, com a mesma mensagem de sempre — nada do que já foi assinado muda, e a chave pública é a mesma.

Na verificação, a versão vem da evidência gravada e o hash vem da coluna da sessão, nunca do que o chamador mandar. Três desencontros são valid: false: vínculo gravado com assinatura v1 (rebaixamento), assinatura v2 em sessão sem vínculo, e signature.operationHash diferente da coluna.

SessãoAssinaturaversionMensagem assinada
Sem bindingv1ausente${sessionId}|${attempt}|${bundleHash}|${signedAt}
Com bindingv22v2|${sessionId}|${attempt}|${bundleHash}|${signedAt}|${operationHash}

Subcontas: revenda como SaaS

Uma empresa que revende verificação biométrica para os próprios clientes — o caso do Catalisa Biometrics — cadastra cada cliente como subconta da sua organização (API Keys) e entrega a ele uma chave da subconta. A partir daí o bloco separa tudo por cliente:

O quêComo fica por subconta
Sessões, evidência, cadastros faciais, direitos do titularCada cliente só vê e só opera o que é dele; sessão ou cadastro de outro cliente responde 404. O bloqueio por excesso de falhas conta dentro do cliente
Marca da página de capturaFornecedor configurado na subconta (marca, appearance, allowedEmbedHosts); sem ele, vale o da organização
PolíticaOverride por subconta (PUT /policy no escopo dela); sem override, vale a da organização
Cota mensalmonthlyQuota da subconta: atingida, a criação de sessão responde 402 QUOTA_EXCEEDED
SuspensãoSubconta SUSPENDED não abre sessão: 403 SUBACCOUNT_SUSPENDED
UsoGET /usage?groupBy=day devolve a série do cliente para o dashboard dele e para a fatura
WebhookCada evento leva subaccountId; o cliente cadastra o próprio endpoint no Webhooks Engine e recebe só os eventos dele

A organização vê todos os clientes: sem escopo, lista e soma tudo, e filtra com ?subaccountId=. Para agir como um cliente (abrir sessão, ajustar a política dele), manda X-Subaccount-Id.

Regra da cota. Conta as sessões da subconta criadas no mês civil de America/Sao_Paulo, menos as que terminaram EXPIRED ou CANCELLED — sessão aberta reserva a vaga; expirou ou foi cancelada sem decisão, a vaga volta. É a mesma base do billable do endpoint de uso no fechamento do mês. A conferência final acontece na gravação, sob trava por subconta: aberturas simultâneas na última vaga não passam juntas.

sequenceDiagram
  participant C as Sistema do cliente
  participant B as Biometrics
  participant W as Webhooks Engine
  C->>B: POST /sessions (chave da subconta)
  B->>B: subconta ACTIVE? cota do mês?
  alt suspensa
    B-->>C: 403 SUBACCOUNT_SUSPENDED
  else cota atingida
    B-->>C: 402 QUOTA_EXCEEDED
  else ok
    B-->>C: 201 sessão (subaccountId)
    B->>W: biometrics.session.completed (subaccountId)
    W->>C: webhook no endpoint do cliente
  end

Ambiente de testes (sandbox)

Toda chave de API nasce em um ambiente: test ou live (API Keys). O ambiente da chave decide o mundo em que a sessão nasce, e a sessão guarda esse ambiente para sempre.

O quêtest (sandbox)live (produção)
MotorSimulado (MOCK), determinísticoO fornecedor configurado na organização ou na subconta
Fornecedor configuradoDispensa — só para chave de subconta (veja Quem vê o quê abaixo): dá para integrar antes de conectar motorObrigatório (400 sem fornecedor padrão)
Cota da subcontaNão consomeConsome (402 QUOTA_EXCEEDED ao atingir)
Medição e faturaNenhuma linha de uso, nenhum evento usage.recordedMede e fatura
minAssurance da políticaNão se aplicaRecusa fornecedor abaixo do exigido
LeituraChave test só enxerga sessão testChave live só enxerga sessão live
Suspensão da subcontaBloqueia igualBloqueia

O envelope da sessão traz environment, e o evento biometrics.session.completed também — o mesmo endpoint de webhook consegue separar o que é ensaio do que é real.

Resultado previsível pelo CPF. No sandbox, o final do CPF (subjectRef) decide o desfecho, para o cliente exercitar cada ramo da integração:

Final do CPFDesfecho
…-25 (ou qualquer outro)APPROVED
…-11INCONCLUSIVE (revisão humana)
…-55RETRY_ALLOWED na primeira tentativa, APPROVED na segunda
…-66ERROR do motor, sem consumir tentativa
…-00REJECTED por comparação facial
…-33REJECTED por prova de vida
…-44REJECTED por continuidade
…-22INCONCLUSIVE por câmera virtual

Quem vê o quê. Só a chave de subconta fica selada no próprio ambiente — ela é do cliente do tenant, e a chave de teste dele não pode alcançar produção. O tenant não fica selado: com JWT ou com a chave da organização agindo por X-Subaccount-Id (o caminho do console do cliente), ele enxerga os dois mundos e escolhe com ?environment=live|test|all. Selar o tenant esconderia o sandbox exatamente da tela em que o cliente integra.

⚠️ O sandbox nasce do selo, e só a chave de subconta é selada (admin.router.ts › environmentOf: sem subaccountId, o ambiente do chamador é indefinido). Consequência prática, medida em 23/09/2026: uma chave test**da própria organização** abre sessão emlivee recebe400 "Nenhum fornecedor de biometria padrão configurado". Para integrar sem motor, emita a chave testde uma **subconta**. O?environment=do tenant vale para LEITURA (listagens,/usage`) — ele não abre sessão de sandbox.

GET /usage responde produção por padrão para quem não está selado — é o número de que a cota e a fatura falam — e aceita ?environment=test ou ?environment=all. A listagem de sessões aceita o mesmo parâmetro e, sem ele, mostra os dois.


09

Referência da API

Todas as rotas ficam sob /biometrics. As de /api/v1 exigem JWT com organizationId; as de captura e convite aceitam só o próprio token.

Sessões

MétodoRotaDescriçãoPermissão
POST/biometrics/api/v1/sessionsAbre a sessão e devolve o handoffBIOMETRICS_VERIFY
GET/biometrics/api/v1/sessionsListaBIOMETRICS_READ
GET/biometrics/api/v1/sessions/:idO envelope completoBIOMETRICS_READ
GET/biometrics/api/v1/sessions/:id/evidenceHashes e assinaturaBIOMETRICS_READ
GET/biometrics/api/v1/sessions/:id/evidence/verifyConfere a assinatura no servidorBIOMETRICS_READ
POST/biometrics/api/v1/sessions/:id/evidence/verifyO mesmo, com as expectativas no corpo (use este quando mandar CPF)BIOMETRICS_READ
POST/biometrics/api/v1/sessions/:id/cancelCancelaBIOMETRICS_VERIFY
POST/biometrics/api/v1/sessions/:id/capturesSubmissão por SDK próprio, com o captureTokentoken

POST /biometrics/api/v1/sessions

Request

json
{
  "flow": "ONBOARDING",
  "purpose": "abertura de conta",
  "subjectRef": { "type": "CPF", "value": "529.982.247-25" },
  "reference": { "source": "DOCUMENT_IMAGE", "fileId": "7c1e…" },
  "enrollOnApprove": true
}
{
  "flow": "ONBOARDING",
  "purpose": "abertura de conta",
  "subjectRef": { "type": "CPF", "value": "529.982.247-25" },
  "reference": { "source": "DOCUMENT_IMAGE", "fileId": "7c1e…" },
  "enrollOnApprove": true
}
CampoTipoObrigatórioDescrição
flowenumsimONBOARDING, AUTHENTICATION, ENROLLMENT, LIVENESS_ONLY
purposestringsimFinalidade, de 3 a 120 caracteres. Vai para a trilha
legalBasisstringnãoBase legal declarada
subjectRefobjetonãoCPF do titular. Gravado como HMAC e máscara; ativa o bloqueio por titular
referenceobjetodepende do fluxoDOCUMENT_IMAGE ou FILE com fileId; ENROLLED_TEMPLATE com templateId; SUBJECT_TEMPLATE sem id — exige subjectRef e busca o cadastro âncora ativo mais recente desse titular: só o nascido de sessão ONBOARDING aprovada contra a base oficial (PROVIDER_BASE, com match.1_1 passado) do mesmo titular, no escopo exato (pedido da organização só vê cadastro sem subconta) e, em produção, nunca do motor simulado (MOCK) nem de sessão test. Desde 30/09 também ancora o cadastro de ONBOARDING aprovada contra a foto do documento cujo CPF impresso o fornecedor leu e bateu (document_cpf_match) e, só enquanto a organização mantiver documentAnchorWithoutCpfCheck ligado, o do MODO DEMONSTRAÇÃO (document_face_match_no_cpf_check); entre várias, vale a mais antiga ativa, e ONBOARDING com enrollOnApprove de titular que JÁ TEM âncora é recusado (409 subject.anchor_exists, evento biometrics.subject.anchor_exists, na criação e de novo no cadastro) — reancorar (fornecedor novo, modelo retreinado) é fluxo explícito de administração. A base é a gravada no cadastro e tem de ser a que a sessão de origem sustenta. FILE nunca ancora; documento sem CPF conferido fora do modo demonstração, também não; ENROLLMENT também não. O filtro é feito no banco. Sem âncora, 404. Serve a quem sabe o CPF e não guarda o id do cadastro (o baas, ao abrir a selfie do titular de uma conta, pela fachada openAuthenticationSession)
customerIduuidnãoVínculo com o Customers
providerConfigIduuidnãoForça um fornecedor; senão, vale o padrão da organização
appearanceobjetonãoCores, logo, textos e modo da página, só para esta sessão
metadataobjetonãoAté 10 rótulos livres. Nunca CPF
enrollOnApprovebooleanonãoGrava o cadastro facial ao aprovar. Só ONBOARDING e ENROLLMENT
bindingobjetonão{ "operationHash": "<SHA-256, 64 hex minúsculos>" }. Amarra a sessão à operação: a evidência sai assinada em v2 cobrindo o hash. Volta no envelope como binding

Resposta 201

json
{
  "data": {
    "sessionId": "5b0e…",
    "flow": "ONBOARDING",
    "provider": "OPENSOURCE",
    "assurance": "ENHANCED",
    "status": "SESSION_OPEN",
    "attempt": 0,
    "maxAttempts": 3,
    "subjectRef": { "type": "CPF", "hmac": "…", "masked": "***.***.247-25" },
    "reference": {
      "source": "DOCUMENT_IMAGE",
      "portraitExtracted": true,
      "document": { "authenticity": "mrz-valid", "mrz": { "…": "mascarado" }, "qr": null }
    },
    "handoff": {
      "captureUrl": "https://biometrics.bb.stg.catalisa.app/biometrics/capture/eyJ…",
      "captureToken": "eyJ…",
      "captureMode": "RAW_FRAMES",
      "challenge": { "script": ["SMILE", "TURN_LEFT", "BLINK"], "timeoutMs": 22000, "slotsMs": [5200, 6100, 4800] },
      "expiresAt": "2026-09-18T15:00:00.000Z"
    },
    "expiresAt": "2026-09-18T15:00:00.000Z"
  }
}
{
  "data": {
    "sessionId": "5b0e…",
    "flow": "ONBOARDING",
    "provider": "OPENSOURCE",
    "assurance": "ENHANCED",
    "status": "SESSION_OPEN",
    "attempt": 0,
    "maxAttempts": 3,
    "subjectRef": { "type": "CPF", "hmac": "…", "masked": "***.***.247-25" },
    "reference": {
      "source": "DOCUMENT_IMAGE",
      "portraitExtracted": true,
      "document": { "authenticity": "mrz-valid", "mrz": { "…": "mascarado" }, "qr": null }
    },
    "handoff": {
      "captureUrl": "https://biometrics.bb.stg.catalisa.app/biometrics/capture/eyJ…",
      "captureToken": "eyJ…",
      "captureMode": "RAW_FRAMES",
      "challenge": { "script": ["SMILE", "TURN_LEFT", "BLINK"], "timeoutMs": 22000, "slotsMs": [5200, 6100, 4800] },
      "expiresAt": "2026-09-18T15:00:00.000Z"
    },
    "expiresAt": "2026-09-18T15:00:00.000Z"
  }
}

Outros campos do envelope. modality é sempre face. capture diz por onde a captura entrou (channel) e, num iframe, de qual origem (embedHost) — nulo enquanto ela não aconteceu. cost traz amount, currency e estimated, o custo daquela sessão. elapsedMs é o tempo de avaliação. createdAt, capturedAt e evaluatedAt marcam as três transições; só expiresAt aparece no exemplo acima porque as outras ainda não existiam quando a sessão foi aberta.

Perfil avaliado. Todo envelope do motor próprio traz evaluation: o perfil de avaliação ISO/IEC 30107-3 a que a sessão se refere, se ela rodou dentro dele (conforms) e, se não, o que saiu (violations). A garantia CERTIFIED vale só para sessão conforme a um perfil com laudo emitido. GET /policy e PUT /policy devolvem a mesma conformidade em meta.evaluationProfiles, e GET /catalog lista os perfis.

json
"evaluation": {
  "profileId": "pad-l1-2026-09",
  "label": "Candidato ISO/IEC 30107-3 Nível 1",
  "standard": "ISO/IEC 30107-3",
  "conforms": true,
  "certified": false,
  "violations": []
}
"evaluation": {
  "profileId": "pad-l1-2026-09",
  "label": "Candidato ISO/IEC 30107-3 Nível 1",
  "standard": "ISO/IEC 30107-3",
  "conforms": true,
  "certified": false,
  "violations": []
}

Depois da decisão, GET /sessions/:id traz decision com outcome, reasons e reviewRequired; checks[] com status, score, threshold, reasons e o engine (nome, modelo e versão) de cada verificação; evidence com os hashes e a assinatura; e enrollment.templateId quando enrollOnApprove gravou o cadastro.

Erros

StatusCódigoQuando
400VALIDATIONFluxo sem a referência que exige, CPF inválido, documento vencido com rejectExpiredDocument, referência sem rosto utilizável
400BAD_REQUESTGarantia do driver abaixo de minAssurance, ou capacidade que o driver não tem (provider.not_supported)
403FORBIDDENSem permissão, ou titular bloqueado (subject.locked)
404NOT_FOUNDCadastro facial ou arquivo de referência inexistente ou de outra organização
503SERVICE_UNAVAILABLEMotor indisponível

Revisão humana (POST /sessions/:id/review)

Sessão INCONCLUSIVE com decision.reviewRequired: true (política onInconclusive: REVIEW) é decidida por uma pessoa com BIOMETRICS_ADMIN:

json
{ "decision": "APPROVE" | "REJECT", "reason": "texto de 10 a 500 caracteres" }
{ "decision": "APPROVE" | "REJECT", "reason": "texto de 10 a 500 caracteres" }
  • Chave de API e token client_credentials são recusados (403 review.person_required).
  • Só INCONCLUSIVE revisável: REJECTED nunca vira APPROVED (409 review.not_inconclusive).
  • O titular declarado (customerId) não revisa a própria sessão (403 review.reviewer_is_subject). O IAM não guarda CPF de usuário: quando o titular não tem customerId, a separação é do processo.
  • APPROVE numa ONBOARDING com enrollOnApprove forma o cadastro facial, como a aprovação automática. As condições são conferidas antes (review.no_template, review.too_late — 24 h, review.anchor_exists); se o cadastro falhar mesmo assim, a sessão volta a INCONCLUSIVE.
  • A mesa não resolve dúvida de ROSTO: APPROVE numa ONBOARDING cujo match.1_1 não passou é 409 review.match_not_passed. A âncora só vale com o match passado na origem; aprovar formaria um cadastro anunciado como âncora que o bloco nunca reconhece. A base da âncora (anchorBasis) é a da sessão — demonstração continua demonstração.
  • O motivo fica em decision.review e sai no evento biometrics.session.reviewed (trilha).
  • Quem consome a sessão por leitura (o banking na abertura de conta) segue sozinho: a próxima leitura vê APPROVED com âncora e abre a conta.

Mídia para conferência humana (POST /sessions/:id/review-media)

Quem revisa precisa VER o que a máquina viu. Corpo { "reason": "10 a 500 caracteres" }; resposta:

json
{ "data": { "sessionId": "…", "mode": "RETAIN", "available": true, "unavailableReason": null,
  "purgedAt": null, "retainedUntil": "…", "ttlSeconds": 300,
  "items": [ { "kind": "document_image", "contentType": "image/jpeg", "url": "https://…", "expiresAt": "…", "status": "available" } ] } }
{ "data": { "sessionId": "…", "mode": "RETAIN", "available": true, "unavailableReason": null,
  "purgedAt": null, "retainedUntil": "…", "ttlSeconds": 300,
  "items": [ { "kind": "document_image", "contentType": "image/jpeg", "url": "https://…", "expiresAt": "…", "status": "available" } ] } }
  • Peças, nesta ordem: document_image (foto do documento pela página), reference_portrait (retrato extraído do documento), best_frame (melhor frame da selfie), challenge_video (vídeo do desafio) e reference (arquivo de referência do tenant, quando houver).
  • URL pré-assinada de 5 minutos, só leitura (expiresIn=300 no file-storage, que só encurta).
  • Mesma régua da revisão: pessoa com BIOMETRICS_ADMIN; chave de API, client_credentials e token interno: 403 review.person_required. Sessão de outra organização: 404.
  • Todo acesso vai para a trilha ANTES de as URLs saírem: biometrics.review.media.viewed com quem (viewerId), por quê (reason) e quais peças (kinds), nunca a URL. Trilha fora do ar: 503 review.audit_unavailable e nenhuma URL sai. Toda recusa: biometrics.review.media.refused.
  • Sem mídia é 200 com o motivo: DISCARDED (retention.media: DISCARD, nunca guardada), PURGED (a retenção apagou; purgedAt), NO_EVIDENCE (sem captura avaliada). Peça cujo arquivo sumiu sai com status: missing.
  • GET /sessions/:id/evidence (com BIOMETRICS_READ) também devolve URLs, de 1 hora e sem rastro: é a rota de integração, não a de conferência humana. A mesa usa esta.

Captura e convite (públicas, por token)

MétodoRotaDescriçãoPermissão
GET/biometrics/capture/:tokenA página de capturatoken
GET/biometrics/capture/:token/stateEstado da sessão, para a páginatoken
GET/biometrics/capture/:token/logoO logo da empresatoken
GET/biometrics/capture/:token/guide/:nameArquivos do guia ao vivo, com hash fixotoken
POST/biometrics/capture/:token/documentA foto do documento (multipart image, JPEG/PNG/WebP, até 8 MB), ANTES da selfie, quando a sessão ONBOARDING pediu DOCUMENT_IMAGE sem fileId. Não consome o token. Resposta: { accepted: true } ou o motivo de UX (reference.low_quality, reference.document_subject_unread, reference.document_subject_mismatch, reference.document_expired…) com attemptsLeft; até 5 fotos por sessão. Cada recusa publica biometrics.document.refused, cada aceite biometrics.document.accepted (com o veredito do CPF, nunca o número)token
POST/biometrics/capture/:token/submitO vídeo e a telemetriatoken
POST/biometrics/api/v1/invitesCria um link de conviteBIOMETRICS_ADMIN
GET/biometrics/invite/:tokenA página do convitetoken
POST/biometrics/invite/:token/startAbre uma sessão a partir do convitetoken

Tela inicial da captura, antes de abrir a câmera
Tela inicial da captura, antes de abrir a câmera

Cadastro facial

MétodoRotaDescriçãoPermissão
POST/biometrics/api/v1/enrollmentsCria o cadastro a partir de uma sessão aprovadaBIOMETRICS_ENROLL
GET/biometrics/api/v1/enrollments/:idMetadados do cadastro, nunca o vetorBIOMETRICS_READ
DELETE/biometrics/api/v1/enrollments/:idRevoga. Zera o vetor do cadastro e a cópia dele na sessão de origem (state.templateCipher), como a purga de retenção: a mesma sessão não regrava o rosto nas 24 h da janela de cadastro. biometrics.enrollment.revoked leva vectorScrubbed; falha ao limpar a cópia não desfaz a revogação (fica no log, e a purga de mídia apaga depois)BIOMETRICS_ENROLL
POST/biometrics/api/v1/enrollments/rekeyRecifra os cadastros com a chave novaBIOMETRICS_ADMIN

Evidência e direitos do titular

MétodoRotaDescriçãoPermissão
GET/biometrics/api/v1/evidence-keysChaves públicas Ed25519 da organizaçãoBIOMETRICS_READ
POST/biometrics/api/v1/evidence-keys/rotateGira a chave de assinaturaBIOMETRICS_ADMIN
POST/biometrics/api/v1/subjects/reportO que existe sobre um CPF (LGPD art. 18)BIOMETRICS_ADMIN
POST/biometrics/api/v1/subjects/eraseApaga os dados biométricos de um CPFBIOMETRICS_ADMIN

O CPF vai no corpo, nunca na URL, para não aparecer em log de acesso.

GET|POST /sessions/:id/evidence/verify

Confere a assinatura gravada e responde o que quem autoriza precisa saber. As expectativas são opcionais e vão na query (GET) ou no corpo (POST):

ParâmetroTipoDescrição
expectedOperationHashstringSHA-256 (64 hex minúsculos) da operação que o chamador está autorizando
expectedSubjectstringCPF esperado do titular, só dígitos. Comparado pelo HMAC do bloco, nunca em claro
json
{
  "data": {
    "valid": true,
    "version": 2,
    "operationHash": "3f2a…",
    "operationHashMatches": true,
    "subjectMatches": true,
    "flow": "AUTHENTICATION",
    "outcome": "APPROVED",
    "identityProven": true,
    "environment": "live",
    "keyId": "ev-7c1e…",
    "signedAt": "2026-09-22T12:00:00.000Z",
    "retiredAt": null
  }
}
{
  "data": {
    "valid": true,
    "version": 2,
    "operationHash": "3f2a…",
    "operationHashMatches": true,
    "subjectMatches": true,
    "flow": "AUTHENTICATION",
    "outcome": "APPROVED",
    "identityProven": true,
    "environment": "live",
    "keyId": "ev-7c1e…",
    "signedAt": "2026-09-22T12:00:00.000Z",
    "retiredAt": null
  }
}

operationHashMatches e subjectMatches só aparecem quando a expectativa correspondente foi passada; as duas comparações são em tempo constante. valid fala só da assinatura; quem prova identidade é identityProven (ver §14). Quem autoriza exige valid && outcome === 'APPROVED' && identityProven && operationHashMatches && subjectMatches e, em produção, environment === 'live' — o bloco informa, a decisão de aceitar é de quem chama. Sessão sem evidência assinada é 400; sessão de outra organização é 404; expectedOperationHash ou expectedSubject malformado é 400 VALIDATION.

CampoProva o quê
validA evidência foi assinada por esta organização e não foi mexida, e o vínculo gravado confere
outcomeO que a sessão decidiu (APPROVED, REJECTED, INCONCLUSIVE…)
identityProvenIdentidade: sessão aprovada com comparação facial 1:1 contra um cadastro facial do mesmo titular, ainda utilizável (não revogado e não vencido: expiresAt > agora). false em LIVENESS_ONLY, ENROLLMENT e ONBOARDING. Conferido a CADA verify: a mesma sessão que provava deixa de provar quando o cadastro é revogado ou vence
identityUnprovenReasonPor que identityProven é false quando a culpa é do cadastro: TEMPLATE_REVOKED ou TEMPLATE_EXPIRED (o limite expiresAt == agora já é vencido). null em todo o resto. Sai com o log biometrics.identity.template_unusable (organização, cadastro e motivo — sem CPF nem HMAC do titular)
subjectMatchesQue o CPF declarado na sessão é o que o chamador esperava. Não prova quem é a pessoa
operationHashMatchesQue a evidência autoriza esta operação
environmentlive ou test. Operação real não aceita test

Prefira o POST quando mandar expectedSubject: CPF em query string cai em log de acesso e em proxy.

Fornecedores, política e consumo

MétodoRotaDescriçãoPermissão
POST/biometrics/api/v1/providersCadastra o fornecedorBIOMETRICS_ADMIN
GET/biometrics/api/v1/providersListaBIOMETRICS_READ
GET/biometrics/api/v1/providers/:idDetalheBIOMETRICS_READ
PATCH/biometrics/api/v1/providers/:idAtualiza, inclusive a aparênciaBIOMETRICS_ADMIN
DELETE/biometrics/api/v1/providers/:idRemoveBIOMETRICS_ADMIN
POST/biometrics/api/v1/providers/:id/test-connectionTesta o motor ou a credencialBIOMETRICS_ADMIN
GET/biometrics/api/v1/policyA política efetiva (da subconta, se houver override; senão da organização)BIOMETRICS_READ
PUT/biometrics/api/v1/policyTroca a política (no escopo de subconta, grava o override dela)BIOMETRICS_ADMIN
DELETE/biometrics/api/v1/policyRemove o override da subconta do escopoBIOMETRICS_ADMIN
POST/biometrics/api/v1/policy/reapply-retentionReaplica a retenção da política vigente ao que a organização já guarda: estende evidence.retainedUntil (ou o mediaDays do snapshot, sem evidência) e o expiresAt dos cadastros; nunca encurta; organização do token (subconta: 403); biometrics.retention.reapplied com as contagensBIOMETRICS_ADMIN
GET/biometrics/api/v1/catalogDrivers, capacidades e garantia de cada umBIOMETRICS_READ
GET/biometrics/api/v1/usageConsumo por período. Com groupBy=day|month, série com total, approved, rejected, inconclusive, expired, cancelled, inProgress e billable por bucket (America/Sao_Paulo) e totals; from, to, subaccountId e environment (live por padrão, test ou all) opcionaisBIOMETRICS_READ

Escopo de subconta. Todas as rotas de /api/v1 aceitam chave de subconta e X-Subaccount-Id (ver Subcontas). GET /sessions e GET /usage aceitam ?subaccountId= para a organização filtrar. O envelope da sessão traz subaccountId e environment (live ou test; veja Ambiente de testes). Convites, POST /evidence-keys/rotate e POST /enrollments/rekey são da organização: no escopo de subconta respondem 403 SUBACCOUNT_SCOPE_FORBIDDEN.

Códigodetails.codeQuando
402QUOTA_EXCEEDEDCota mensal da subconta atingida (monthlyQuota, used, periodStart, periodEnd)
403SUBACCOUNT_SUSPENDEDSubconta suspensa (reason)

10

Início rápido

1. Autenticar

bash
TOKEN=$(curl -s -X POST https://iam.bb.stg.catalisa.app/iam/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{"email":"SEU-EMAIL","password":"SUA-SENHA","organizationId":"SUA-ORG"}' \
  | jq -r .accessToken)
BIO=https://biometrics.bb.stg.catalisa.app/biometrics/api/v1
TOKEN=$(curl -s -X POST https://iam.bb.stg.catalisa.app/iam/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{"email":"SEU-EMAIL","password":"SUA-SENHA","organizationId":"SUA-ORG"}' \
  | jq -r .accessToken)
BIO=https://biometrics.bb.stg.catalisa.app/biometrics/api/v1

Usuário recém-criado pela API não loga. POST /iam/api/v1/users devolve status: "pendente" e o login responde 401 Invalid credentials — a mesma mensagem de senha errada. Ative antes: PATCH /iam/api/v1/users/:id com {"status":"ativo"}.

2. Cadastrar o motor próprio como padrão

bash
curl -X POST $BIO/providers \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "name": "motor-proprio", "providerType": "OPENSOURCE", "isDefault": true }'
curl -X POST $BIO/providers \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "name": "motor-proprio", "providerType": "OPENSOURCE", "isDefault": true }'

Dá para pular este passo no ambiente de testes, com uma chave test de subconta: a sessão sai no motor simulado mesmo sem fornecedor configurado, sem consumir cota e sem gerar fatura (Ambiente de testes). Com o JWT deste passo 1 — ou com uma chave test da organização — o passo não pode ser pulado: o chamador não está selado em test, a sessão nasce em live e vem 400 "Nenhum fornecedor de biometria padrão configurado".

3. Abrir uma sessão de prova de vida

bash
curl -s -X POST $BIO/sessions \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "flow": "LIVENESS_ONLY", "purpose": "teste do inicio rapido" }' \
  | jq '.data | {sessionId, captureUrl: .handoff.captureUrl}'
curl -s -X POST $BIO/sessions \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "flow": "LIVENESS_ONLY", "purpose": "teste do inicio rapido" }' \
  | jq '.data | {sessionId, captureUrl: .handoff.captureUrl}'

4. Abrir o captureUrl no celular e seguir a página. Ela pede a câmera, mostra o primeiro gesto com uma contagem de 2,5 s antes de gravar, guia os gestos sorteados e envia sozinha.

Contagem de preparo, com o primeiro gesto na tela antes de gravar
Contagem de preparo, com o primeiro gesto na tela antes de gravar

5. Ler a decisão

bash
curl -s $BIO/sessions/$SESSION_ID -H "Authorization: Bearer $TOKEN" \
  | jq '.data | {status, decision, checks: [.checks[] | {kind, status, score, threshold}]}'
curl -s $BIO/sessions/$SESSION_ID -H "Authorization: Bearer $TOKEN" \
  | jq '.data | {status, decision, checks: [.checks[] | {kind, status, score, threshold}]}'
json
{
  "status": "APPROVED",
  "decision": { "outcome": "APPROVED", "reasons": [], "reviewRequired": false },
  "checks": [
    { "kind": "quality.capture", "status": "PASSED", "score": 0.91, "threshold": 0.6 },
    { "kind": "liveness.passive", "status": "PASSED", "score": 0.97, "threshold": 0.8 },
    { "kind": "liveness.active", "status": "PASSED", "score": 1, "threshold": 1 },
    { "kind": "identity.continuity", "status": "PASSED", "score": 0.95, "threshold": 0.7 }
  ]
}
{
  "status": "APPROVED",
  "decision": { "outcome": "APPROVED", "reasons": [], "reviewRequired": false },
  "checks": [
    { "kind": "quality.capture", "status": "PASSED", "score": 0.91, "threshold": 0.6 },
    { "kind": "liveness.passive", "status": "PASSED", "score": 0.97, "threshold": 0.8 },
    { "kind": "liveness.active", "status": "PASSED", "score": 1, "threshold": 1 },
    { "kind": "identity.continuity", "status": "PASSED", "score": 0.95, "threshold": 0.7 }
  ]
}

Tela de conclusão, que não revela o resultado
Tela de conclusão, que não revela o resultado

SDKs oficiais

A API é REST com JSON e funciona com qualquer cliente HTTP — os SDKs existem para poupar o que é chato de acertar: verificação da assinatura do webhook, conferência do recibo sem depender da Catalisa, repetição segura e os tipos do envelope.

LinguagemInstalaçãoSituação
Python 3.9+pip install catalisa-biometricsNo ar
PHP 8.1+composer require catalisa/biometricsNo ar
Go 1.21+go get github.com/catalisaio/catalisa-biometrics-sdk/packages/goNo ar
.NET 8 e .NET Standard 2.0dotnet add package Catalisa.BiometricsNo ar
Ruby 3.0+gem install catalisa-biometricsNo ar
Node 18+ e TypeScriptnpm install @catalisa/biometricsEm publicação no npm
Navegadornpm install @catalisa/biometrics-webEm publicação no npm
Java 17+ e Kotlinio.github.catalisaio:catalisa-biometrics:0.1.0No ar (Maven Central; Kotlin usa o mesmo artefato)

Código-fonte, testes e os vetores de assinatura compartilhados entre as linguagens: catalisaio/catalisa-biometrics-sdk.

Nenhum SDK é obrigatório, e nenhum deles guarda segredo: a chave fica no seu servidor, e o envio da captura pelo app nativo usa o token de uso único da sessão, não a chave da conta. Para as linguagens sem SDK, o guia do desenvolvedor traz exemplos completos das mesmas quatro chamadas em oito linguagens, e a especificação OpenAPI gera cliente em qualquer uma.


11

Receitas

Mais tempo para cada gesto. Público mais velho ou celular mais lento pedem janela maior. A política aceita o intervalo sorteado por gesto e o teto do vídeo:

bash
curl -X PUT $BIO/policy -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "challenge": { "gestures": 2, "gesturesMax": 3, "slotMinMs": 5500, "slotMaxMs": 7500, "timeoutMs": 24000 } }'
curl -X PUT $BIO/policy -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "challenge": { "gestures": 2, "gesturesMax": 3, "slotMinMs": 5500, "slotMaxMs": 7500, "timeoutMs": 24000 } }'

O vídeo inteiro não passa de 24 segundos — é o limite do motor. Menos gestos com mais tempo costumam reprovar menos gente do que mais gestos com pouco tempo.

O próximo gesto é anunciado antes de a janela começar
O próximo gesto é anunciado antes de a janela começar

Escolher os gestos. challenge.pool restringe o catálogo; o padrão tem sete (virar à esquerda e à direita, piscar, sorrir, abrir a boca, acenar com a cabeça, erguer as sobrancelhas). approachEnabled: true inclui aproximar o rosto da câmera, que funciona bem no celular e mal no notebook.

TILT_LEFT e TILT_RIGHT existem no motor e entram por challenge.pool, mas estão fora do catálogo padrão por decisão: em três sessões reais, com texto e depois com pictograma, "inclinar, orelha no ombro" foi executado como "virar". O motor recusou certo as três vezes — o gesto é que não funciona como instrução.

Página com a cara da empresa. appearance no fornecedor vale para todas as sessões; na sessão, só para ela. Cores, raio dos cantos, fonte de uma lista fechada, logo por fileId, modo claro, escuro ou automático, textos por idioma e redirectUrl. Nada vira CSS ou JavaScript livre.

A tela de captura no modo escuro, com a dica do gesto
A tela de captura no modo escuro, com a dica do gesto

Embutir em iframe. Liste a origem em allowedEmbedHosts do fornecedor e use allow="camera". A página avisa o andamento por postMessage — nunca o resultado:

eventQuando
readyPágina carregada, sessão capturável
capturingCâmera liberada, gravação começou
step:<GESTO>Cada passo do roteiro, com index, total e durationMs
submittedVídeo enviado
retryNova tentativa; a página recarrega sozinha
doneSessão encerrada — leia o envelope pelo servidor
expiredSessão expirada
guideO guia visual do gesto carregou ({loaded:true}) ou não ({loaded:false, reason}). A captura segue nos dois casos
errorCâmera negada ou motor instável, com reason

Num WebView do React Native (o app de banco abre a página hospedada assim), o mesmo emit() chama também window.ReactNativeWebView.postMessage quando a ponte existe, com só o nome do evento — {"type":"<nome>"}, sem reason, sem índice, sem token. O app não precisa injetar ponte nenhuma; a decisão ele lê pelo servidor, como todo mundo.

html
<iframe id="bio" src="CAPTURE_URL" allow="camera"></iframe>
<script>
  // A origem sai da própria captureUrl que o seu backend recebeu: ela muda de
  // ambiente, e um host fixo aqui faz a página ignorar todos os eventos calada.
  const origem = new URL(CAPTURE_URL).origin
  window.addEventListener('message', (e) => {
    if (e.origin !== origem || e.data?.source !== 'catalisa-biometrics') return
    if (e.data.event === 'done') consultarSessaoNoBackend()
  })
</script>
<iframe id="bio" src="CAPTURE_URL" allow="camera"></iframe>
<script>
  // A origem sai da própria captureUrl que o seu backend recebeu: ela muda de
  // ambiente, e um host fixo aqui faz a página ignorar todos os eventos calada.
  const origem = new URL(CAPTURE_URL).origin
  window.addEventListener('message', (e) => {
    if (e.origin !== origem || e.data?.source !== 'catalisa-biometrics') return
    if (e.data.event === 'done') consultarSessaoNoBackend()
  })
</script>

Verificar a evidência sem a Catalisa. Baixe a chave pública em GET /evidence-keys e confira a assinatura de GET /sessions/:id/evidence. A mensagem assinada é sessionId|attempt|bundleHash|signedAt, e o bundleHash já resume checks, artefatos, política e roteiro — basta openssl pkeyutl -verify com a chave pública.

Modo avaliação para laboratório e pré-teste. Numa organização listada em BIOMETRICS_EVALUATION_ORG_IDS, a página mostra um selo com a sessão e a tentativa e, ao fim, o resultado com os motivos, para o avaliador registrar cada apresentação. Fora dessas organizações a página nunca mostra o resultado.

Cartão de resultado do modo avaliação
Cartão de resultado do modo avaliação

Medir antes de ligar em produção. POST /invites gera um link válido por até 90 dias para voluntários. A página rotula o que a pessoa mostra à câmera — ela mesma, foto impressa, foto numa tela, vídeo numa tela ou máscara, as espécies da ISO/IEC 30107-3 — e o relatório devolve APCER por espécie, BPCER e as taxas de não resposta, no vocabulário do laudo.

Nova tentativa, com o motivo em linguagem simples
Nova tentativa, com o motivo em linguagem simples


12

Integração com outros building blocks

BlocoComo se encaixa
File StorageGuarda o vídeo do desafio, o melhor quadro e o documento de referência, pela fachada IFileStorageFacade. Falha de armazenamento não perde a verificação: o hash fica
BillingSessão avaliada vira UsageEvent no medidor biometrics.verification, pela fachada IBillingFacade — quando a organização tem conta de faturamento e esse medidor. Sem um dos dois, o bloco registra um aviso e o consumo fica só no GET /usage, que é de onde o excedente é apurado no SaaS da Catalisa
Webhooks EngineEntrega os eventos abaixo a quem assinou. Evento de subconta vai para os endpoints dela e para os da organização
API KeysSubcontas, chaves de subconta, suspensão e cota (monthlyQuota)
CustomerscustomerId na sessão e no cadastro facial liga a verificação ao cliente
IAMEscopo por organização e as permissões BIOMETRICS_*
BaaS e qualquer bloco que autorizeConfere a evidência pela fachada IBiometricsFacade, sem HTTP do cliente no caminho: verifyEvidence({ organizationId, sessionId, expectedOperationHash?, expectedSubject? }) devolve { valid, version, operationHash, operationHashMatches?, subjectMatches?, flow, outcome, identityProven, identityUnprovenReason, environment, keyId, signedAt }. No monólito chama o serviço direto; em standalone, o bloco por JWT interno

Eventos publicados — todos levam subaccountId (null quando a sessão é da organização)

EventoQuando
biometrics.session.createdSessão aberta
biometrics.session.completedDecisão tomada, com o status
biometrics.session.review_requiredINCONCLUSIVE: alguém precisa olhar
biometrics.session.expiredSessão venceu sem decisão
biometrics.session.media_not_storedO file-storage não confirmou a mídia da captura: a sessão não aprovou (ERROR, EVIDENCE_MEDIA_NOT_STORED) e a tentativa não foi consumida
biometrics.subject.lockedCriação recusada por excesso de falhas do titular
biometrics.subject.erasedDados de um titular apagados a pedido
biometrics.enrollment.created e .revokedCadastro facial gravado ou revogado
biometrics.provider_config.created, .updated e .deletedFornecedor configurado, alterado ou removido na organização
biometrics.usage.recordedVerificação contabilizada. Consumido pelo próprio bloco para faturar; publicado no barramento como qualquer outro

13

Configuração e operação

Onde roda

AmbienteBase da APIMotor
Produçãohttps://biometrics.bb.catalisa.app/biometricsface-engine no mesmo stack, só rede interna, 4 vCPUs / 4 GB
Staginghttps://biometrics.bb.stg.catalisa.app/biometricsidem

O token vem do IAM do mesmo ambiente (https://iam.bb.catalisa.app/iam/api/v1/users/login em produção), sempre com organizationId no login. O captureUrl devolvido pela sessão já aponta para a base pública do ambiente.

Variáveis de ambiente

VariávelObrigatóriaPadrãoDescrição
BIOMETRICS_CREDENTIAL_MASTER_KEYsim—64 hex. Cifra a credencial do fornecedor e a chave de assinatura
BIOMETRICS_TEMPLATE_MASTER_KEYsim—64 hex, diferente da anterior. Cifra o cadastro facial
BIOMETRICS_TEMPLATE_MASTER_KEY_PREVIOUSnão—A chave antiga durante a rotação, até o rekey terminar
BIOMETRICS_ENGINE_URLnãohttp://face-engine:8000Endereço interno do motor
BIOMETRICS_ENGINE_TOKENsim com o motor—Bearer compartilhado com o motor
BIOMETRICS_PUBLIC_URLsim—Base pública do bloco, usada para montar o captureUrl
BIOMETRICS_EXPIRE_SCHEDULER_ENABLEDnãotrueSessão vencida vira EXPIRED a cada minuto
BIOMETRICS_RETENTION_PURGE_ENABLEDnãofalsePurga de retenção (mídia, vetor e cadastro facial vencido — ver abaixo). Desligada por padrão: apagar é irreversível. false, 0, no e off desligam (até 01/10/2026 era z.coerce.boolean e a string "false" ligava)
BIOMETRICS_RETENTION_PURGE_INTERVAL_HOURSnão24Cadência da purga
BIOMETRICS_RAW_IMAGE_RETENTION_ENABLEDnãofalseTeto de idade da imagem bruta (ver abaixo). Desligado por padrão: sem ele nada é apagado. false, 0, no e off desligam
BIOMETRICS_RAW_IMAGE_RETENTION_DAYSnão30Idade (desde createdAt) a partir da qual a imagem bruta sai. Piso de 7: valor menor vira 7 (com aviso no log)
BIOMETRICS_RAW_IMAGE_RETENTION_DRY_RUNnãofalseModo plano: só CONTA o que apagaria (trilha com mode: DRY_RUN). Vale mesmo com o teto desligado — é o ensaio antes de ligar
BIOMETRICS_RAW_IMAGE_RETENTION_INTERVAL_HOURSnão24Cadência do teto
BIOMETRICS_DEBUG_ERRORSnãofalsetrue escreve o erro cru no stderr. Só para investigar: o traço pode conter dado da sessão
BIOMETRICS_USAGE_CONSUMER_ENABLEDnãofalseLiga o faturamento. false, 0, no e off desligam
BIOMETRICS_EVALUATION_ORG_IDSnãovazioOrganizações de avaliação (laboratório, pré-teste), separadas por vírgula. Só nelas a página de captura mostra o resultado

Purga de retenção (BiometricsRetentionPurgeService, a cada BIOMETRICS_RETENTION_PURGE_INTERVAL_HOURS, uma réplica por vez pela trava biometrics:retention-purge:lock):

O quêQuandoO que saiO que ficaTrilha
Mídia da sessãoevidence.retainedUntil, ou (evaluatedAt ?? createdAt) + retention.mediaDays do snapshot da sessãoo ARQUIVO no file-storage (objeto no S3 e a linha) de: melhor frame e vídeo de todas as tentativas, retrato extraído e a foto do documento tirada pela página; a cópia do vetor (state.templateCipher)a linha, checks, decisão, hashes e a assinatura da evidência; a referência mandada pelo tenant (reference)biometrics.media.purged (ids, hashes, resultado por arquivo) ou biometrics.media.purge_failed
Cadastro facialexpiresAt (createdAt + retention.templateDays)revogado, embeddingCipher zerado, e a cópia do vetor na sessão de origema linha (id, titular em HMAC, âncora)biometrics.enrollment.expired
Cadastro sem validadea política vigente do escopo tem templateDaysrecebe expiresAt = createdAt + templateDays (reduzir retenção vale para o que já existe)—biometrics.enrollment.expiry_set

Idempotente e segura com 2 réplicas: cada sessão e cada cadastro fecham por updateMany condicionado ao estado anterior (só quem fecha publica), e arquivo já apagado conta como missing. Arquivo que o file-storage não apagou deixa a sessão aberta para a próxima passada. Cadastro vencido faz a selfie de autenticação responder 404 BIOMETRIC_TEMPLATE_MISSING; quem decide o que a pessoa vê é o integrador.

Vencer pela retenção encerra o que o cadastro amarrava — de propósito (LGPD). O vencimento vale no instante de expiresAt, não na passada da purga: entre os dois, o cadastro ainda tem vetor, e mesmo assim não abre sessão ENROLLED_TEMPLATE (404), não roda match na captura e não prova identidade no verify (identityProven: false, identityUnprovenReason: 'TEMPLATE_EXPIRED'). Toda evidência que se apoiava nele para de provar — inclusive a que cadastrou uma chave de aparelho no BaaS, que é reverificada a cada uso: a chave morre junto e o BaaS recusa com BIOMETRIC_TEMPLATE_UNUSABLE. O app precisa fazer um novo cadastro facial do titular e cadastrar o aparelho de novo; estender a retenção (reapply-retention) antes do vencimento é o único jeito de evitar isso.

Armadilhas da purga (01/10/2026):

  • Até esta versão a purga só zerava o fileId na evidência: o arquivo ficava no storage, a foto do documento (DOCUMENT_IMAGE pela página) e as tentativas antigas nem eram olhadas, sessões que venceram sem avaliação (documento tirado, selfie nunca feita) ficavam fora, e o take: 200 sem cursor relia as mesmas 200 sessões no prazo a cada passada. Sessões purgadas antes disso têm mediaPurgedAt, mas os ponteiros das colunas (reference_file_id, reference_portrait_file_id) e das capturas ficaram: a passada seguinte apaga esses arquivos e publica biometrics.media.purged com leftover: true.
  • O file-storage apagava a linha antes do objeto: S3 falhando deixava os bytes no bucket e a nova tentativa respondia 404 ("já não existe"). Agora objeto primeiro, linha depois.
  • Primeira passada ao ligar apaga tudo o que já está fora do prazo, até 5.000 sessões (mais 5.000 sobras e 5.000 cadastros) por passada; o resto sai nas seguintes. Não há modo ensaio: antes de ligar em produção, conte as vencidas no banco. O teto conta sessão TRATADA, não lida — contado na leitura, a varredura (que recomeça do início e ordena por UUID) parava sempre nas mesmas linhas no prazo e as vencidas de id alto nunca saíam.
  • templateDays: null (o padrão) = cadastro sem validade. Gravar templateDays numa política dá validade também aos cadastros antigos na próxima passada — e os que já passaram do prazo são revogados nela.

Teto de idade da imagem bruta (BiometricsRawImageRetentionService, plano de privacidade; trava biometrics:raw-image-retention:lock, lotes de 50, até 1.000 sessões ou 10 min por passada). Independe da política: sessão criada há mais de BIOMETRICS_RAW_IMAGE_RETENTION_DAYS perde, do FILE-STORAGE, o mesmo conjunto de arquivos da purga da política (filesOf): melhor frame e vídeo de todas as tentativas, retrato extraído e a foto do documento tirada pela página. Fica: decisão, checks, status, a evidência assinada (o bundleHash cobre kind + hash, não o fileId), os hashes, o cadastro facial e a cópia do vetor na sessão — esses seguem com a purga da política, que continua dona de mediaPurgedAt. A referência mandada pelo tenant não é nossa e não sai.

ModoQuandoO que faz
DISABLEDsem …_ENABLED e sem …_DRY_RUNnem agenda; só loga que está desligado
DRY_RUN…_DRY_RUN=true (ou run({ dryRun: true }))lê e conta; nada apagado, nada marcado
APPLY…_ENABLED=true sem …_DRY_RUNapaga, zera os ponteiros (fileId na evidência, colunas, capturas) e marca raw_images_purged_at

Idempotente: a sessão marcada sai da varredura, e arquivo já apagado conta como missing. Arquivo que o storage não apagou (ou que lançou) NÃO marca a sessão — vai biometrics.raw_images.purge_failed e a próxima passada tenta de novo —, e o lote segue. A marca é condicionada ao updatedAt lido: uma escrita concorrente na evidência não é perdida. Trilha: biometrics.raw_images.purged por sessão (ids, hashes, resultado por arquivo) e, por organização tocada, biometrics.raw_images.retention_run com runId, modo, retentionDays, cutoff, a sessão mais antiga e a mais nova tocadas e os números. A revisão passa a responder PURGED (a evidência ganha mediaPurgedAt), e o envelope de uma ONBOARDING com documento já aceito continua com documentPending: false depois da limpeza.

Migration antes do deploy: 20261027100000_biometrics_raw_images_purged_at (coluna + índice). O Prisma lê todas as colunas do modelo: código novo sem a coluna quebra toda leitura de sessão.

As duas master keys são separadas de propósito: a da credencial gira com o contrato do fornecedor; a do cadastro facial exige recifrar a base inteira.

Política por organização, sem deploy (PUT /policy)

ChavePadrãoPara quê
minAssuranceENHANCEDGarantia mínima do driver. O MOCK é BASIC e é recusado
thresholds.matchrecusa < 0,55, aprova ≥ 0,70Entre os dois é zona cinzenta, INCONCLUSIVE
thresholds.livenessPassiverecusa < 0,40, aprova ≥ 0,80Liveness passivo
maxAttempts3Tentativas por sessão
sessionTtlMinutes15Validade do link, até 60
challenge3 gestos, 4,5 a 6,5 s cada, até 22 sQuantidade, janelas e catálogo
documenttudo desligadoRecusar documento vencido; exigir MRZ ou QR válido
lockout5 falhas em 60 min → 30 minBloqueio por titular
retentionmídia por 30 dias, media: RETAINE validade do cadastro facial, se houver. retention.media: DISCARD é o modo de privacidade: a mídia é hasheada e descartada, nunca sobe ao storage
onInconclusiveREVIEWOu REJECT
allowedCaptureChannelsHOSTED, IFRAME, SDKPor onde a câmera pode abrir

Observabilidade. O bloco publica métricas OpenTelemetry de baixa cardinalidade. Nenhum rótulo carrega CPF, sessão ou organização.

InstrumentoTipoO que mede
biometrics.sessions.completed.totalcontadorSessões avaliadas, por fluxo, resultado, fornecedor e versão do motor
biometrics.checks.totalcontadorChecks por tipo e status
biometrics.check.scorehistogramaScore de cada check (0–1), por tipo e versão do motor
biometrics.decision.reasons.totalcontadorMotivos da decisão
biometrics.evaluation.durationhistograma (ms)Avaliação de ponta a ponta no bloco
biometrics.engine.stage.durationhistograma (ms)Cada etapa do motor
biometrics.session.refused.totalcontadorCriações recusadas: titular bloqueado, referência ruim, documento vencido

GET /biometrics/health responde vivo e GET /biometrics/health/ready responde pronto. Nenhuma das duas pede token, e nenhuma toca o banco.

O motor em operação. O face-engine sobe com os pesos embutidos na imagem e aquece os modelos antes de se declarar saudável. Uma sessão de celular leva ~8 s em 4 vCPUs; a análise dos pontos do rosto roda em paralelo por quadro.


14

Segurança e compliance

Biometria é dado pessoal sensível (LGPD art. 5º, II). O desenho parte disso:

TemaComo
Finalidadepurpose obrigatório em toda sessão, com legalBasis opcional, gravados na trilha
TitularCPF em HMAC e máscara, nunca em claro
Cadastro facialCifrado com chave própria, nunca devolvido pela API, com rotação por rekey
MídiaRetenção configurável; a purga apaga do storage selfie, vídeo, retrato e foto do documento (todas as tentativas), preserva os hashes e registra na trilha o que saiu
Direitos do titularsubjects/report diz o que existe; subjects/erase apaga sessões, mídia e cadastros de um CPF
Decisão automatizadaINCONCLUSIVE vai para revisão humana (art. 20)

Quem está diante da câmera não carrega credencial. A página recebe um captureToken de escopo único e uso único por tentativa, e só as rotas de captura o aceitam. A página roda com CSP por nonce; os arquivos do guia ao vivo são servidos pelo próprio bloco com hash fixo, sem CDN.

A página não diz o resultado. Nem aprovado, nem reprovado: quem decide o que dizer à pessoa é a empresa, depois de ler o envelope pelo servidor. Isso impede que um fraudador use a página como oráculo para ajustar o ataque.

Contra injeção de vídeo. Os gestos são sorteados em quantidade, ordem e duração por sessão, e a janela de cada um é conferida no vídeo. Na medição, um vídeo genuíno aprovado, reinjetado por câmera virtual, passou no liveness passivo e na continuidade — é rosto real — e foi reprovado pela janela sorteada. Troca de dispositivo entre tentativas vira INCONCLUSIVE.

Contra força bruta. O mesmo CPF com 5 sessões reprovadas ou inconclusivas em 60 minutos fica bloqueado por 30. Os três números são da política.

Evidência assinada. Cada organização tem uma chave Ed25519 própria, criada no primeiro uso, com a privada cifrada. A pública é publicada para que a auditoria verifique sem depender da Catalisa.

subjectRef é DECLARADO, não provado. Quem abre a sessão informa o CPF do titular; o bloco guarda o HMAC daquilo que foi informado. Logo subjectMatches compara declaração com expectativa — é controle de consistência, não prova de identidade. Quem prova identidade é identityProven, derivado dentro do bloco: true só quando a sessão foi aprovada com comparação facial 1:1 (match.1_1 PASSED) contra um cadastro facial amarrado ao mesmo titular. Fluxo sem comparação — LIVENESS_ONLY e ENROLLMENT, onde a política nem exige o check de match — prova presença de uma pessoa viva, e só. ONBOARDING compara contra o documento que o próprio integrador enviou: a âncora ali é o documento, não o bloco, e identityProven também sai false.

O cadastro facial tem que ser do titular declarado. Uma sessão AUTHENTICATION que aponte um ENROLLED_TEMPLATE de outro titular é recusada na criação (reference.template_subject_mismatch), e a mensagem não diz de quem é o cadastro. Sem essa amarra, quem tem credencial da organização abriria uma sessão no CPF da vítima, compararia o próprio rosto com o cadastro dela e receberia APPROVED no nome dela.

Chave de assinatura, escopo e rotação. A chave é buscada dentro da organização: o mesmo keyId em outra organização não verifica. Chave aposentada continua verificando o que assinou antes de ser aposentada — é o contrato da rotação, e auditoria antiga não pode virar inválida porque giramos a chave —, mas assinatura com carimbo posterior ao retiredAt é valid: false.

Evidência amarrada à operação. Sessão aberta com binding.operationHash sai assinada em v2, e a assinatura cobre o hash da operação: a selfie aprovada para liberar um Pix não serve para liberar outro, nem para outra coisa. A versão sai da evidência gravada e o hash sai da coluna da sessão — o chamador não escolhe nenhum dos dois, e rebaixar v2 para v1 é valid: false. O bloco recebe o hash e só o hash: valor, destino e payload da operação nunca entram aqui.

Conformidade com normas

O bloco é desenvolvido em conformidade com os requisitos e as recomendações das normas abaixo. Conformidade declarada pela Catalisa — sem homologação nem certificação de terceiro.

NormaOnde o bloco aplica
ISO/IEC 30107-1 e 30107-3Detecção de ataque de apresentação (PAD): famílias de ataque, métricas APCER e BPCER e protocolo de avaliação
ISO/IEC 19795-1Métricas de desempenho do match, FMR e FNMR
ICAO Doc 9303Leitura da MRZ do passaporte, com validação dos dígitos verificadores
LGPD — arts. 5º II, 11, 18 e 20Dado sensível, base legal, direitos do titular e revisão de decisão automatizada
Circular BCB nº 3.978/2020Apoia a identificação e a qualificação de clientes da política de PLD/FT
RFC 8032 — Ed25519Assinatura da evidência
NIST SP 800-38D — AES-256-GCMCifra do cadastro facial e das credenciais
RFC 7519 — JWTToken de captura de uso único
W3C CSP Level 3 e Permissions PolicyIsolamento da página de captura e acesso à câmera
OpenTelemetryMétricas de operação

Certificações no roadmap (nenhuma emitida até aqui)

CertificaçãoEscopo
iBeta ISO/IEC 30107-3 Nível 1Ataques com foto impressa, tela, vídeo e máscara de papel
iBeta ISO/IEC 30107-3 Nível 2Máscaras 3D de látex, silicone e resina
FIDO Alliance Face VerificationDesempenho do match, PAD e injeção, com laboratório credenciado
CEN/TS 18099Detecção de injeção de dados biométricos, como câmera virtual e vídeo sintético

15

Limitações conhecidas

EscopoComo o bloco trata
Autenticidade física do documentoFora do escopo. O bloco lê MRZ e QR para validade e consistência; documentoscopia é de provedor especializado
Reconhecimento 1:NFora do escopo. O fluxo DEDUP está reservado no contrato
FaceTec, Unico e Serpro DatavalidDeclarados no catálogo; ativados com a credencial do contrato de cada um
Certificação de laboratórioEntregue pelos drivers CERTIFIED
Duração do vídeoAté 24 segundos por tentativa
Dispositivo recomendadoCelular, pela câmera e pela luz. O gesto de aproximar o rosto (APPROACH) é indicado só para celular
Captura do documentoCom reference: { source: "DOCUMENT_IMAGE" } sem fileId, a página hospedada fotografa o documento (câmera traseira ou arquivo, com dicas) antes da selfie. Um lado só: o da foto e do CPF
Leitura do CPF do documentoO motor próprio lê o CPF impresso por OCR (tesseract) e devolve só o veredito (match/mismatch/unread), nunca o número. match só quando nenhum OUTRO CPF formatado aparece na imagem (papel com o CPF da vítima ao lado de outro documento é mismatch). Funciona em CNH, RG novo e CIN, que imprimem o CPF formatado; a MRZ do passaporte não traz CPF e o QR da CNH-e é assinado e comprimido (só o Serpro lê). Medido em imagem sintética (com ruído, blur e giro de 4°); a taxa de leitura em foto real de celular ainda não foi medida. Não é documentoscopia: documento forjado com o CPF certo passa — por isso a âncora diz de onde veio (document_cpf_match) e não se passa por base oficial
Modo demonstraçãodocumentAnchorWithoutCpfCheck: true (só a organização principal grava; cada mudança vai para a trilha) deixa o cadastro ancorar sem o CPF conferido, marcado document_face_match_no_cpf_check no cadastro, na evidência e no evento biometrics.enrollment.created. A âncora fraca deixa de valer quando o modo é desligado e nunca vira forte: só um cadastro novo, com CPF conferido ou base oficial
APPROACH fora do celularNo notebook o rosto não chega perto o bastante da câmera para bater o limiar. O gesto falha por medição, não por má vontade: ligue approachEnabled só onde a captura é de celular
APPROACH nunca é o 1º gestoA página mostra o 1º gesto na contagem antes de gravar; quem aproximava ali chegava perto antes do vídeo e o motor media 1,02–1,09× (pede 1,3×). O sorteio põe APPROACH do 2º gesto em diante (02/10/2026)
capture.device_changed compara o rótulo da câmeraO deviceId gira entre tentativas no WebView do Android (cada tentativa é uma página nova). Com selectedLabelHash dos dois lados, manda o rótulo; sem ele, o deviceId, como antes. O rótulo é escolhido por quem instala a câmera (v4l2loopback card_label= copia o da física): rótulo igual com deviceId diferente E inventário de câmeras (labelsHash) diferente continua sendo troca
Prova de identidadeidentityProven só existe onde há comparação 1:1 contra cadastro facial do mesmo titular. Em ONBOARDING a identidade vem do documento que o integrador enviou, e o bloco não a atesta
subjectRef declaradoO CPF é informado por quem abre a sessão; o bloco guarda o HMAC do que foi informado. subjectMatches é consistência, não identidade
Cadastro facial sem titularCadastro gravado sem subjectRef não amarra titular: a sessão é aceita, mas identityProven sai false
Vínculo com a operaçãoO bloco confere o hash que recebeu; construir e reconstruir o hash da operação é de quem autoriza. Nenhuma política exige vínculo hoje: sessão sem binding continua válida e assinada em v1
Atestação de dispositivoRoadmap: SDK nativo com atestação na origem da captura. Medimos em 14/09/2026 que jitter, ruído e blocagem de quadro não separam vídeo injetado de celular real — quem segura o ataque hoje é a janela sorteada, não a métrica de imagem

16

Perguntas frequentes

Usa inteligência artificial de terceiros?

Usa modelos de pesos abertos publicados por terceiros — YuNet, MiniFASNet, MediaPipe, Facenet512 —, rodando na nossa infraestrutura. Nenhuma imagem sai para serviço externo. Os pesos são fixados por hash e a versão aparece em cada check.

Substitui a FaceTec?

O motor próprio atende sem contrato de terceiro nos fluxos em que o nível ENHANCED basta. Onde a certificação for exigida, a FaceTec entra como driver e a integração não muda.

Por que a página não mostra se aprovou?

Porque a página está nas mãos de quem está diante da câmera, que pode ser um fraudador. Mostrar o resultado transforma a página num oráculo para ajustar o ataque. A empresa lê o envelope pelo servidor e decide o que dizer.

A empresa pode configurar quanto tempo cada gesto dura?

Pode, pela política da organização, sem deploy: quantidade de gestos, janela mínima e máxima de cada um, o tempo total até 24 segundos e quais gestos entram no sorteio.

Qual a diferença entre REJECTED e INCONCLUSIVE?

REJECTED é o sistema seguro de que não deve aprovar. INCONCLUSIVE é zona cinzenta — match entre os limiares, sinal heurístico de câmera virtual, troca de dispositivo — e vai para revisão humana, como pede a LGPD para decisão automatizada com efeito relevante.

Precisa pedir o documento em toda verificação?

Não. O documento entra uma vez, no ONBOARDING com enrollOnApprove. Depois, a autenticação compara com o cadastro facial, que chega a 0,95 de match.

subjectMatches: true prova que a pessoa é o titular do CPF?

Não. O CPF é declarado por quem abre a sessão, então subjectMatches diz que a declaração bate com a expectativa de quem verifica. A prova de identidade é identityProven: sessão aprovada com comparação facial 1:1 contra um cadastro facial do mesmo titular. Quem autoriza operação sensível exige identityProven, não o fluxo nem o subjectMatches sozinho.

A selfie aprovada de uma operação serve para outra?

Não, se a sessão for aberta com binding.operationHash: a assinatura da evidência cobre o hash da operação, e a verificação diz operationHashMatches: false para qualquer outra. Sem vínculo, a evidência prova presença e identidade, não o que foi autorizado — é por isso que o step-up transacional deve sempre abrir a sessão vinculada.

Funciona no navegador ou precisa de app?

No navegador, sem instalar nada. Antes de gravar, a página mostra o primeiro gesto com uma contagem de 2,5 s. O guia ao vivo roda no próprio navegador e se desliga sozinho em conexão lenta ou com economia de dados; a captura funciona sem ele. Para app nativo, a rota POST /sessions/:id/captures aceita a submissão de um SDK próprio com o mesmo captureToken.