Integração do zero, em uma tarde
Vamos montar uma abertura de conta com prova de vida: a pessoa se cadastra no seu produto, faz a verificação no celular e o seu servidor recebe a decisão assinada. Tudo no ambiente de testes, sem gastar franquia, e no fim a virada para produção.
# 1 · seu servidor abre a sessão POST /v1/sessions → sessionId + captureUrl # 2 · a pessoa faz a verificação no celular captureUrl → câmera, gestos, envio # 3 · a decisão chega no seu servidor webhook session.completed → APPROVED · score · limiar · recibo
Antes de começar
Você precisa de três coisas, e as três levam minutos.
- Uma conta
O plano Livre já traz chave de teste ilimitada e 30 verificações reais por mês. Criar conta.
- A chave de teste
No console, em Chaves de API, crie uma com ambiente teste. Ela roda no motor simulado: não gasta franquia, não é cobrada e não enxerga produção.
- Um endereço público para o webhook
Em desenvolvimento, um túnel resolve. Sem ele, dá para consultar a sessão por id — o passo 5 mostra os dois caminhos.
Passo 1 · Instale o SDK
Opcional, mas poupa o que é chato de acertar: assinatura do webhook, verificação do recibo, repetição segura e os tipos do envelope. Escolha a sua linguagem — o resto do tutorial mostra o código em todas.
pip install catalisa-biometrics
composer require catalisa/biometrics
gem install catalisa-biometrics
dotnet add package Catalisa.Biometrics
go get github.com/catalisaio/catalisa-biometrics-sdk/packages/go
io.github.catalisaio:catalisa-biometrics:0.1.0
Guarde a chave numa variável de ambiente. Ela vive no servidor e nunca no aplicativo nem no navegador: quem tem a chave abre sessões na sua conta.
Passo 2 · Abra a sessão no seu servidor
Quando a pessoa chega na etapa de verificação do seu cadastro, o seu backend abre uma sessão. A resposta traz o captureUrl: ele vale para uma pessoa, uma sessão e expira.
Carregando o exemplo…
O purpose é o que você mostraria a um auditor perguntando por que o rosto dessa pessoa foi processado. O metadata aceita até dez rótulos livres — e nunca um CPF.
Passo 3 · Leve a pessoa até a captura
O caminho mais simples é o link: por WhatsApp, e-mail, QR ou um botão no seu app. A página é nossa, já com a sua marca, e funciona em celular e computador.
Carregando o exemplo…
Quer a câmera dentro do seu produto? Tem iframe com eventos de andamento e envio pelo seu próprio app. A decisão nunca passa pelo navegador — nem no iframe.
Passo 4 · Receba a decisão no seu servidor
Quando a verificação termina, mandamos um evento assinado para o seu endpoint. Confira a assinatura antes de confiar no conteúdo: é isso que garante que veio da Catalisa e não de alguém que descobriu o seu endereço.
Carregando o exemplo…
- Verifique o corpo cruDecodificar e recodificar o JSON muda os bytes e a assinatura não bate.
- Use o id do eventoUma entrega pode chegar mais de uma vez; o
idé estável e serve de chave de idempotência. - Responda rápidoDevolva 200 e faça o trabalho depois. Demora vira reentrega.
- Sem endpoint ainda?Consulte a sessão pelo id — é o passo 5.
Passo 5 · Leia o envelope e decida
A decisão vem com o número que a produziu: score, limiar e o modelo que decidiu, verificação por verificação. É o que você mostra quando alguém contesta.
Carregando o exemplo…
Os estados finais são APPROVED, REJECTED, INCONCLUSIVE, EXPIRED e CANCELLED. RETRY_ALLOWED não é final: a pessoa ainda pode tentar de novo, e a página já reemite o link sozinha.
Passo 6 · Ensaie cada desfecho
No ambiente de testes, o final do CPF decide o resultado. Isso deixa você cobrir aprovação, recusa, revisão e erro sem depender de sorte — e sem gastar franquia.
CPF terminado em …-25AprovadoCPF terminado em …-11Inconclusivo · revisãoCPF terminado em …-55Nova tentativa, depois aprovadoCPF terminado em …-66Erro do motor (repita)CPF terminado em …-00Reprovado na comparação facialCPF terminado em …-33Reprovado na prova de vidaCubra também o que dá errado fora do rosto: cota esgotada e conta suspensa chegam como erro tipado.
Carregando o exemplo…
Passo 7 · Guarde o recibo
Cada decisão vem com um pacote de evidência assinado. Você confere a assinatura sem nos consultar, hoje ou daqui a três anos — é o que sustenta a sua versão numa contestação ou numa auditoria.
# Ed25519 sobre exatamente esta string sessionId | attempt | bundleHash | signedAt # a chave pública vem de GET /v1/evidence-keys # chaves aposentadas continuam publicadas — recibo antigo continua conferindo
Todos os SDKs fazem essa conferência offline, sem chamar a Catalisa. Detalhes em Recibo da decisão.
Passo 8 · Vá para produção
O código não muda. O que muda é a chave — e quatro conferências antes de ligar para valer.
- Troque a chave
Crie uma chave de produção no console e use-a no servidor. A partir daí o motor é o real, cada verificação conta na franquia e as sessões de teste somem da sua listagem.
- Cadastre o webhook de produção
No console, em Webhooks, aponte para o seu endereço e guarde as chaves públicas. Confira a assinatura com elas.
- Revise a política
Limiares, número de tentativas, validade do link e o que fazer na zona cinzenta: mandar para revisão humana ou recusar. Tudo em Parâmetros.
- Combine o plano com o seu volume
O console mostra quanto do ciclo já foi usado. Acima da franquia há excedente por verificação; o bloqueio só acontece no plano Livre.
Quer a captura com a sua marca? Em Personalização dá para definir cor, logo e textos da página, e liberar os domínios que podem embutir o iframe.