Biometrics
AlphaProva de vida e match facial com motor próprio, no contrato dos provedores certificados
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.
- 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
- 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
- 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
37 endpoints em 5 recursos.
/biometrics/api/v1/sessions/biometrics/biometrics/api/v1/enrollments/biometrics/api/v1/biometrics/api/v1Telas
o que o usuário vêToque numa tela para ampliar.












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 medidas | 59, nenhuma reprovada pelo liveness passivo |
| Match contra o cadastro facial feito pelo bloco | 0,95 |
| Avaliação de uma sessão de celular | ~8 s |
| Imagens de rosto enviadas a terceiros | nenhuma |
Segurança em seis camadas, nível de garantia ENHANCED, em conformidade com os requisitos da ISO/IEC 30107-3
| Camada | Contra o quê |
|---|---|
| Liveness passivo | Foto impressa, foto ou vídeo exibidos numa tela |
| Desafio ativo sorteado | Vídeo gravado e reinjetado — gestos, ordem e duração mudam a cada sessão |
| Continuidade de identidade | Troca de pessoa durante a captura |
| Integridade da captura | Câmera virtual e troca de dispositivo entre tentativas, que vão para revisão |
| Bloqueio por titular | Tentativas em série contra o mesmo CPF |
| Evidência assinada em Ed25519 | Alteraçã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.
O problema
negócioAbrir 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.
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.
INCONCLUSIVEvai 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 paraERRORcomEVIDENCE_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,ENHANCEDouCERTIFIED— 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.
Casos de uso reais
negócioAbertura 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.

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.

Mercado e diferenciais
negócioO 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 SDK | Com o Biometrics | |
|---|---|---|
| Onde a decisão acontece | No app, dentro do SDK | No servidor, com a política da empresa |
| Por que reprovou | Código do fornecedor | Motivo, score, limiar e modelo por verificação |
| Evidência para auditoria | Log da aplicação | Hashes assinados em Ed25519, verificáveis fora da Catalisa |
| Revisão humana | A empresa monta | Status INCONCLUSIVE e evento próprio |
| Trocar de fornecedor | Reescrever a captura e o parser | Trocar a configuração |
| Custo em volume baixo | Mínimo contratual | Motor 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.
Modelo de cobrança e ROI
negócioUnidade: 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):
| Plano | Mensalidade | Inclusas | Excedente |
|---|---|---|---|
| Livre | R$ 0 | 30 | — (bloqueia; 402 QUOTA_EXCEEDED) |
| Start | R$ 199 | 300 | R$ 0,79 |
| Growth | R$ 990 | 2.000 | R$ 0,55 |
| Scale | R$ 3.900 | 10.000 | R$ 0,39 |
| Acima de 50 mil/mês | negociado | — | 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.
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 --> TENANTO 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:
| Etapa | Modelo | Licença |
|---|---|---|
| Detecção de rosto | YuNet | MIT |
| Liveness passivo | MiniFASNet | Apache-2.0 |
| Pontos do rosto e gestos | MediaPipe Face Landmarker | Apache-2.0 |
| Comparação de rostos | Facenet512 | MIT |
| MRZ do passaporte e QR da CNH-e | Tesseract e zxing-cpp | Apache-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 faz | Quem faz |
|---|---|
| Guardar o vídeo e o documento | File Storage |
| Entregar o resultado por HTTP ao sistema da empresa | Webhooks Engine |
| Consultar CPF em bureau | Bureaus |
| Extrair campos do documento para o cadastro | Data Extraction |
| Dizer se o documento é autêntico | Documentoscopia — fora do escopo |
Conceitos e modelo de dados
Glossário
| Termo | Significa |
|---|---|
| Sessão | Uma verificação, do pedido à decisão. Aceita até maxAttempts tentativas |
| Fluxo | ONBOARDING (com documento), AUTHENTICATION (com cadastro facial), ENROLLMENT (só cadastra), LIVENESS_ONLY e DEDUP (reservado) |
| Referência | Contra 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 |
| Template | O 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 |
captureToken | Token curto, de uso único por tentativa, que é tudo o que a página de captura recebe |
| Check | Uma verificação: quality.capture, liveness.passive, liveness.active, identity.continuity, match.1_1, capture.integrity |
| Garantia | BASIC, 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 Prisma | Propósito | Campos-chave |
|---|---|---|
BiometricsProviderConfig | Fornecedor por organização | providerType, credencial cifrada, appearance, allowedEmbedHosts |
BiometricsPolicy | Política por organização | limiares, challenge, lockout, retention, minAssurance |
BiometricsSession | A verificação e a decisão | flow, status, titular em HMAC, operationHash do vínculo, decision, evidência |
BiometricsCapture | Cada tentativa | hashes, fileId da mídia, telemetria, checks |
BiometricsTemplate | Cadastro facial | vetor cifrado, versão do modelo, titular em HMAC |
BiometricsSigningKey | Chave Ed25519 da organização | keyId, chave pública, privada cifrada |
BiometricsUsage | Consumo medido | sessão, fornecedor, custo |
Status de uma sessão
| Status | Terminal | O que fazer |
|---|---|---|
SESSION_OPEN | não | Aguardando a captura |
PROCESSING | não | Avaliando |
APPROVED | sim | Seguir |
REJECTED | sim | Recusar. Conta para o bloqueio do titular |
INCONCLUSIVE | sim | Revisão humana (ou recusa, se a política pedir onInconclusive: REJECT) |
RETRY_ALLOWED | não | A página oferece nova tentativa com o motivo |
EXPIRED | sim | Abrir nova sessão |
CANCELLED | sim | Cancelada pela empresa |
ERROR | não | Falha 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:
{ "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ão | Assinatura | version | Mensagem assinada |
|---|---|---|---|
Sem binding | v1 | ausente | ${sessionId}|${attempt}|${bundleHash}|${signedAt} |
Com binding | v2 | 2 | v2|${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 titular | Cada 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 captura | Fornecedor configurado na subconta (marca, appearance, allowedEmbedHosts); sem ele, vale o da organização |
| Política | Override por subconta (PUT /policy no escopo dela); sem override, vale a da organização |
| Cota mensal | monthlyQuota da subconta: atingida, a criação de sessão responde 402 QUOTA_EXCEEDED |
| Suspensão | Subconta SUSPENDED não abre sessão: 403 SUBACCOUNT_SUSPENDED |
| Uso | GET /usage?groupBy=day devolve a série do cliente para o dashboard dele e para a fatura |
| Webhook | Cada 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
endAmbiente 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) |
|---|---|---|
| Motor | Simulado (MOCK), determinístico | O fornecedor configurado na organização ou na subconta |
| Fornecedor configurado | Dispensa — só para chave de subconta (veja Quem vê o quê abaixo): dá para integrar antes de conectar motor | Obrigatório (400 sem fornecedor padrão) |
| Cota da subconta | Não consome | Consome (402 QUOTA_EXCEEDED ao atingir) |
| Medição e fatura | Nenhuma linha de uso, nenhum evento usage.recorded | Mede e fatura |
minAssurance da política | Não se aplica | Recusa fornecedor abaixo do exigido |
| Leitura | Chave test só enxerga sessão test | Chave live só enxerga sessão live |
| Suspensão da subconta | Bloqueia igual | Bloqueia |
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 CPF | Desfecho |
|---|---|
…-25 (ou qualquer outro) | APPROVED |
…-11 | INCONCLUSIVE (revisão humana) |
…-55 | RETRY_ALLOWED na primeira tentativa, APPROVED na segunda |
…-66 | ERROR do motor, sem consumir tentativa |
…-00 | REJECTED por comparação facial |
…-33 | REJECTED por prova de vida |
…-44 | REJECTED por continuidade |
…-22 | INCONCLUSIVE 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: semsubaccountId, o ambiente do chamador é indefinido). Consequência prática, medida em 23/09/2026: uma chavetest**da própria organização** abre sessão emlivee recebe400 "Nenhum fornecedor de biometria padrão configurado". Para integrar sem motor, emita a chavetestde 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.
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étodo | Rota | Descrição | Permissão |
|---|---|---|---|
POST | /biometrics/api/v1/sessions | Abre a sessão e devolve o handoff | BIOMETRICS_VERIFY |
GET | /biometrics/api/v1/sessions | Lista | BIOMETRICS_READ |
GET | /biometrics/api/v1/sessions/:id | O envelope completo | BIOMETRICS_READ |
GET | /biometrics/api/v1/sessions/:id/evidence | Hashes e assinatura | BIOMETRICS_READ |
GET | /biometrics/api/v1/sessions/:id/evidence/verify | Confere a assinatura no servidor | BIOMETRICS_READ |
POST | /biometrics/api/v1/sessions/:id/evidence/verify | O mesmo, com as expectativas no corpo (use este quando mandar CPF) | BIOMETRICS_READ |
POST | /biometrics/api/v1/sessions/:id/cancel | Cancela | BIOMETRICS_VERIFY |
POST | /biometrics/api/v1/sessions/:id/captures | Submissão por SDK próprio, com o captureToken | token |
POST /biometrics/api/v1/sessions
Request
{
"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
}| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
flow | enum | sim | ONBOARDING, AUTHENTICATION, ENROLLMENT, LIVENESS_ONLY |
purpose | string | sim | Finalidade, de 3 a 120 caracteres. Vai para a trilha |
legalBasis | string | não | Base legal declarada |
subjectRef | objeto | não | CPF do titular. Gravado como HMAC e máscara; ativa o bloqueio por titular |
reference | objeto | depende do fluxo | DOCUMENT_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) |
customerId | uuid | não | Vínculo com o Customers |
providerConfigId | uuid | não | Força um fornecedor; senão, vale o padrão da organização |
appearance | objeto | não | Cores, logo, textos e modo da página, só para esta sessão |
metadata | objeto | não | Até 10 rótulos livres. Nunca CPF |
enrollOnApprove | booleano | não | Grava o cadastro facial ao aprovar. Só ONBOARDING e ENROLLMENT |
binding | objeto | nã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
{
"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.
"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
| Status | Código | Quando |
|---|---|---|
400 | VALIDATION | Fluxo sem a referência que exige, CPF inválido, documento vencido com rejectExpiredDocument, referência sem rosto utilizável |
400 | BAD_REQUEST | Garantia do driver abaixo de minAssurance, ou capacidade que o driver não tem (provider.not_supported) |
403 | FORBIDDEN | Sem permissão, ou titular bloqueado (subject.locked) |
404 | NOT_FOUND | Cadastro facial ou arquivo de referência inexistente ou de outra organização |
503 | SERVICE_UNAVAILABLE | Motor 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:
{ "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_credentialssão recusados (403 review.person_required). - Só
INCONCLUSIVErevisável:REJECTEDnunca viraAPPROVED(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 temcustomerId, a separação é do processo. APPROVEnumaONBOARDINGcomenrollOnApproveforma 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 aINCONCLUSIVE.- A mesa não resolve dúvida de ROSTO:
APPROVEnumaONBOARDINGcujomatch.1_1nã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.reviewe sai no eventobiometrics.session.reviewed(trilha). - Quem consome a sessão por leitura (o
bankingna abertura de conta) segue sozinho: a próxima leitura vêAPPROVEDcom â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:
{ "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) ereference(arquivo de referência do tenant, quando houver). - URL pré-assinada de 5 minutos, só leitura (
expiresIn=300nofile-storage, que só encurta). - Mesma régua da revisão: pessoa com
BIOMETRICS_ADMIN; chave de API,client_credentialse 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.viewedcom quem (viewerId), por quê (reason) e quais peças (kinds), nunca a URL. Trilha fora do ar:503 review.audit_unavailablee nenhuma URL sai. Toda recusa:biometrics.review.media.refused. - Sem mídia é
200com 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 comstatus: missing. GET /sessions/:id/evidence(comBIOMETRICS_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étodo | Rota | Descrição | Permissão |
|---|---|---|---|
GET | /biometrics/capture/:token | A página de captura | token |
GET | /biometrics/capture/:token/state | Estado da sessão, para a página | token |
GET | /biometrics/capture/:token/logo | O logo da empresa | token |
GET | /biometrics/capture/:token/guide/:name | Arquivos do guia ao vivo, com hash fixo | token |
POST | /biometrics/capture/:token/document | A 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/submit | O vídeo e a telemetria | token |
POST | /biometrics/api/v1/invites | Cria um link de convite | BIOMETRICS_ADMIN |
GET | /biometrics/invite/:token | A página do convite | token |
POST | /biometrics/invite/:token/start | Abre uma sessão a partir do convite | token |

Cadastro facial
| Método | Rota | Descrição | Permissão |
|---|---|---|---|
POST | /biometrics/api/v1/enrollments | Cria o cadastro a partir de uma sessão aprovada | BIOMETRICS_ENROLL |
GET | /biometrics/api/v1/enrollments/:id | Metadados do cadastro, nunca o vetor | BIOMETRICS_READ |
DELETE | /biometrics/api/v1/enrollments/:id | Revoga. 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/rekey | Recifra os cadastros com a chave nova | BIOMETRICS_ADMIN |
Evidência e direitos do titular
| Método | Rota | Descrição | Permissão |
|---|---|---|---|
GET | /biometrics/api/v1/evidence-keys | Chaves públicas Ed25519 da organização | BIOMETRICS_READ |
POST | /biometrics/api/v1/evidence-keys/rotate | Gira a chave de assinatura | BIOMETRICS_ADMIN |
POST | /biometrics/api/v1/subjects/report | O que existe sobre um CPF (LGPD art. 18) | BIOMETRICS_ADMIN |
POST | /biometrics/api/v1/subjects/erase | Apaga os dados biométricos de um CPF | BIOMETRICS_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âmetro | Tipo | Descrição |
|---|---|---|
expectedOperationHash | string | SHA-256 (64 hex minúsculos) da operação que o chamador está autorizando |
expectedSubject | string | CPF esperado do titular, só dígitos. Comparado pelo HMAC do bloco, nunca em claro |
{
"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.
| Campo | Prova o quê |
|---|---|
valid | A evidência foi assinada por esta organização e não foi mexida, e o vínculo gravado confere |
outcome | O que a sessão decidiu (APPROVED, REJECTED, INCONCLUSIVE…) |
identityProven | Identidade: 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 |
identityUnprovenReason | Por 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) |
subjectMatches | Que o CPF declarado na sessão é o que o chamador esperava. Não prova quem é a pessoa |
operationHashMatches | Que a evidência autoriza esta operação |
environment | live 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étodo | Rota | Descrição | Permissão |
|---|---|---|---|
POST | /biometrics/api/v1/providers | Cadastra o fornecedor | BIOMETRICS_ADMIN |
GET | /biometrics/api/v1/providers | Lista | BIOMETRICS_READ |
GET | /biometrics/api/v1/providers/:id | Detalhe | BIOMETRICS_READ |
PATCH | /biometrics/api/v1/providers/:id | Atualiza, inclusive a aparência | BIOMETRICS_ADMIN |
DELETE | /biometrics/api/v1/providers/:id | Remove | BIOMETRICS_ADMIN |
POST | /biometrics/api/v1/providers/:id/test-connection | Testa o motor ou a credencial | BIOMETRICS_ADMIN |
GET | /biometrics/api/v1/policy | A política efetiva (da subconta, se houver override; senão da organização) | BIOMETRICS_READ |
PUT | /biometrics/api/v1/policy | Troca a política (no escopo de subconta, grava o override dela) | BIOMETRICS_ADMIN |
DELETE | /biometrics/api/v1/policy | Remove o override da subconta do escopo | BIOMETRICS_ADMIN |
POST | /biometrics/api/v1/policy/reapply-retention | Reaplica 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 contagens | BIOMETRICS_ADMIN |
GET | /biometrics/api/v1/catalog | Drivers, capacidades e garantia de cada um | BIOMETRICS_READ |
GET | /biometrics/api/v1/usage | Consumo 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) opcionais | BIOMETRICS_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ódigo | details.code | Quando |
|---|---|---|
402 | QUOTA_EXCEEDED | Cota mensal da subconta atingida (monthlyQuota, used, periodStart, periodEnd) |
403 | SUBACCOUNT_SUSPENDED | Subconta suspensa (reason) |
Início rápido
1. Autenticar
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/v1TOKEN=$(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/v1Usuário recém-criado pela API não loga.
POST /iam/api/v1/usersdevolvestatus: "pendente"e o login responde401 Invalid credentials— a mesma mensagem de senha errada. Ative antes:PATCH /iam/api/v1/users/:idcom{"status":"ativo"}.
2. Cadastrar o motor próprio como padrão
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
testde 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 chavetestda organização — o passo não pode ser pulado: o chamador não está selado emtest, a sessão nasce emlivee vem400 "Nenhum fornecedor de biometria padrão configurado".
3. Abrir uma sessão de prova de vida
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.

5. Ler a decisão
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}]}'{
"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 }
]
}
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.
| Linguagem | Instalação | Situação |
|---|---|---|
| Python 3.9+ | pip install catalisa-biometrics | No ar |
| PHP 8.1+ | composer require catalisa/biometrics | No ar |
| Go 1.21+ | go get github.com/catalisaio/catalisa-biometrics-sdk/packages/go | No ar |
| .NET 8 e .NET Standard 2.0 | dotnet add package Catalisa.Biometrics | No ar |
| Ruby 3.0+ | gem install catalisa-biometrics | No ar |
| Node 18+ e TypeScript | npm install @catalisa/biometrics | Em publicação no npm |
| Navegador | npm install @catalisa/biometrics-web | Em publicação no npm |
| Java 17+ e Kotlin | io.github.catalisaio:catalisa-biometrics:0.1.0 | No 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.
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:
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.

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.

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:
event | Quando |
|---|---|
ready | Página carregada, sessão capturável |
capturing | Câmera liberada, gravação começou |
step:<GESTO> | Cada passo do roteiro, com index, total e durationMs |
submitted | Vídeo enviado |
retry | Nova tentativa; a página recarrega sozinha |
done | Sessão encerrada — leia o envelope pelo servidor |
expired | Sessão expirada |
guide | O guia visual do gesto carregou ({loaded:true}) ou não ({loaded:false, reason}). A captura segue nos dois casos |
error | Câ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.
<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.

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.

Integração com outros building blocks
| Bloco | Como se encaixa |
|---|---|
| File Storage | Guarda 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 |
| Billing | Sessã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 Engine | Entrega os eventos abaixo a quem assinou. Evento de subconta vai para os endpoints dela e para os da organização |
| API Keys | Subcontas, chaves de subconta, suspensão e cota (monthlyQuota) |
| Customers | customerId na sessão e no cadastro facial liga a verificação ao cliente |
| IAM | Escopo por organização e as permissões BIOMETRICS_* |
| BaaS e qualquer bloco que autorize | Confere 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)
| Evento | Quando |
|---|---|
biometrics.session.created | Sessão aberta |
biometrics.session.completed | Decisão tomada, com o status |
biometrics.session.review_required | INCONCLUSIVE: alguém precisa olhar |
biometrics.session.expired | Sessão venceu sem decisão |
biometrics.session.media_not_stored | O 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.locked | Criação recusada por excesso de falhas do titular |
biometrics.subject.erased | Dados de um titular apagados a pedido |
biometrics.enrollment.created e .revoked | Cadastro facial gravado ou revogado |
biometrics.provider_config.created, .updated e .deleted | Fornecedor configurado, alterado ou removido na organização |
biometrics.usage.recorded | Verificação contabilizada. Consumido pelo próprio bloco para faturar; publicado no barramento como qualquer outro |
Configuração e operação
Onde roda
| Ambiente | Base da API | Motor |
|---|---|---|
| Produção | https://biometrics.bb.catalisa.app/biometrics | face-engine no mesmo stack, só rede interna, 4 vCPUs / 4 GB |
| Staging | https://biometrics.bb.stg.catalisa.app/biometrics | idem |
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ável | Obrigatória | Padrão | Descrição |
|---|---|---|---|
BIOMETRICS_CREDENTIAL_MASTER_KEY | sim | — | 64 hex. Cifra a credencial do fornecedor e a chave de assinatura |
BIOMETRICS_TEMPLATE_MASTER_KEY | sim | — | 64 hex, diferente da anterior. Cifra o cadastro facial |
BIOMETRICS_TEMPLATE_MASTER_KEY_PREVIOUS | não | — | A chave antiga durante a rotação, até o rekey terminar |
BIOMETRICS_ENGINE_URL | não | http://face-engine:8000 | Endereço interno do motor |
BIOMETRICS_ENGINE_TOKEN | sim com o motor | — | Bearer compartilhado com o motor |
BIOMETRICS_PUBLIC_URL | sim | — | Base pública do bloco, usada para montar o captureUrl |
BIOMETRICS_EXPIRE_SCHEDULER_ENABLED | não | true | Sessão vencida vira EXPIRED a cada minuto |
BIOMETRICS_RETENTION_PURGE_ENABLED | não | false | Purga 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_HOURS | não | 24 | Cadência da purga |
BIOMETRICS_RAW_IMAGE_RETENTION_ENABLED | não | false | Teto 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_DAYS | não | 30 | Idade (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_RUN | não | false | Modo 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_HOURS | não | 24 | Cadência do teto |
BIOMETRICS_DEBUG_ERRORS | não | false | true escreve o erro cru no stderr. Só para investigar: o traço pode conter dado da sessão |
BIOMETRICS_USAGE_CONSUMER_ENABLED | não | false | Liga o faturamento. false, 0, no e off desligam |
BIOMETRICS_EVALUATION_ORG_IDS | não | vazio | Organizaçõ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ê | Quando | O que sai | O que fica | Trilha |
|---|---|---|---|---|
| Mídia da sessão | evidence.retainedUntil, ou (evaluatedAt ?? createdAt) + retention.mediaDays do snapshot da sessão | o 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 facial | expiresAt (createdAt + retention.templateDays) | revogado, embeddingCipher zerado, e a cópia do vetor na sessão de origem | a linha (id, titular em HMAC, âncora) | biometrics.enrollment.expired |
| Cadastro sem validade | a política vigente do escopo tem templateDays | recebe 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
fileIdna evidência: o arquivo ficava no storage, a foto do documento (DOCUMENT_IMAGEpela página) e as tentativas antigas nem eram olhadas, sessões que venceram sem avaliação (documento tirado, selfie nunca feita) ficavam fora, e otake: 200sem cursor relia as mesmas 200 sessões no prazo a cada passada. Sessões purgadas antes disso têmmediaPurgedAt, mas os ponteiros das colunas (reference_file_id,reference_portrait_file_id) e das capturas ficaram: a passada seguinte apaga esses arquivos e publicabiometrics.media.purgedcomleftover: true. - O
file-storageapagava 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. GravartemplateDaysnuma 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.
| Modo | Quando | O que faz |
|---|---|---|
DISABLED | sem …_ENABLED e sem …_DRY_RUN | nem 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_RUN | apaga, 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)
| Chave | Padrão | Para quê |
|---|---|---|
minAssurance | ENHANCED | Garantia mínima do driver. O MOCK é BASIC e é recusado |
thresholds.match | recusa < 0,55, aprova ≥ 0,70 | Entre os dois é zona cinzenta, INCONCLUSIVE |
thresholds.livenessPassive | recusa < 0,40, aprova ≥ 0,80 | Liveness passivo |
maxAttempts | 3 | Tentativas por sessão |
sessionTtlMinutes | 15 | Validade do link, até 60 |
challenge | 3 gestos, 4,5 a 6,5 s cada, até 22 s | Quantidade, janelas e catálogo |
document | tudo desligado | Recusar documento vencido; exigir MRZ ou QR válido |
lockout | 5 falhas em 60 min → 30 min | Bloqueio por titular |
retention | mídia por 30 dias, media: RETAIN | E validade do cadastro facial, se houver. retention.media: DISCARD é o modo de privacidade: a mídia é hasheada e descartada, nunca sobe ao storage |
onInconclusive | REVIEW | Ou REJECT |
allowedCaptureChannels | HOSTED, IFRAME, SDK | Por 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.
| Instrumento | Tipo | O que mede |
|---|---|---|
biometrics.sessions.completed.total | contador | Sessões avaliadas, por fluxo, resultado, fornecedor e versão do motor |
biometrics.checks.total | contador | Checks por tipo e status |
biometrics.check.score | histograma | Score de cada check (0–1), por tipo e versão do motor |
biometrics.decision.reasons.total | contador | Motivos da decisão |
biometrics.evaluation.duration | histograma (ms) | Avaliação de ponta a ponta no bloco |
biometrics.engine.stage.duration | histograma (ms) | Cada etapa do motor |
biometrics.session.refused.total | contador | Criaçõ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.
Segurança e compliance
Biometria é dado pessoal sensível (LGPD art. 5º, II). O desenho parte disso:
| Tema | Como |
|---|---|
| Finalidade | purpose obrigatório em toda sessão, com legalBasis opcional, gravados na trilha |
| Titular | CPF em HMAC e máscara, nunca em claro |
| Cadastro facial | Cifrado com chave própria, nunca devolvido pela API, com rotação por rekey |
| Mídia | Retençã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 titular | subjects/report diz o que existe; subjects/erase apaga sessões, mídia e cadastros de um CPF |
| Decisão automatizada | INCONCLUSIVE 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.
| Norma | Onde o bloco aplica |
|---|---|
| ISO/IEC 30107-1 e 30107-3 | Detecção de ataque de apresentação (PAD): famílias de ataque, métricas APCER e BPCER e protocolo de avaliação |
| ISO/IEC 19795-1 | Métricas de desempenho do match, FMR e FNMR |
| ICAO Doc 9303 | Leitura da MRZ do passaporte, com validação dos dígitos verificadores |
| LGPD — arts. 5º II, 11, 18 e 20 | Dado sensível, base legal, direitos do titular e revisão de decisão automatizada |
| Circular BCB nº 3.978/2020 | Apoia a identificação e a qualificação de clientes da política de PLD/FT |
| RFC 8032 — Ed25519 | Assinatura da evidência |
| NIST SP 800-38D — AES-256-GCM | Cifra do cadastro facial e das credenciais |
| RFC 7519 — JWT | Token de captura de uso único |
| W3C CSP Level 3 e Permissions Policy | Isolamento da página de captura e acesso à câmera |
| OpenTelemetry | Métricas de operação |
Certificações no roadmap (nenhuma emitida até aqui)
| Certificação | Escopo |
|---|---|
| iBeta ISO/IEC 30107-3 Nível 1 | Ataques com foto impressa, tela, vídeo e máscara de papel |
| iBeta ISO/IEC 30107-3 Nível 2 | Máscaras 3D de látex, silicone e resina |
| FIDO Alliance Face Verification | Desempenho do match, PAD e injeção, com laboratório credenciado |
| CEN/TS 18099 | Detecção de injeção de dados biométricos, como câmera virtual e vídeo sintético |
Limitações conhecidas
| Escopo | Como o bloco trata |
|---|---|
| Autenticidade física do documento | Fora do escopo. O bloco lê MRZ e QR para validade e consistência; documentoscopia é de provedor especializado |
| Reconhecimento 1:N | Fora do escopo. O fluxo DEDUP está reservado no contrato |
| FaceTec, Unico e Serpro Datavalid | Declarados no catálogo; ativados com a credencial do contrato de cada um |
| Certificação de laboratório | Entregue pelos drivers CERTIFIED |
| Duração do vídeo | Até 24 segundos por tentativa |
| Dispositivo recomendado | Celular, pela câmera e pela luz. O gesto de aproximar o rosto (APPROACH) é indicado só para celular |
| Captura do documento | Com 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 documento | O 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ção | documentAnchorWithoutCpfCheck: 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 celular | No 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º gesto | A 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âmera | O 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 identidade | identityProven 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 declarado | O 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 titular | Cadastro gravado sem subjectRef não amarra titular: a sessão é aceita, mas identityProven sai false |
| Vínculo com a operação | O 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 dispositivo | Roadmap: 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 |
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.