API de prova de vida: como funciona o fluxo de liveness na prática

Uma API de prova de vida abre uma sessão, captura imagem ou vídeo no dispositivo do usuário, envia o material para análise e devolve um resultado que diz se havia uma pessoa real diante da câmera. O resto é desenho de integração.

O nome comercial varia (prova de vida, liveness, detecção de vivacidade), mas o problema é o mesmo: separar uma pessoa presente de uma reprodução. Foto impressa, tela apontada para a câmera, máscara, vídeo pré-gravado e, cada vez mais, imagem sintética injetada direto no fluxo, sem passar pela lente.

Quem integra pela primeira vez subestima duas coisas: a quantidade de estados que o fluxo pode assumir e o peso do ambiente físico no resultado.

O que a API faz e o que continua sendo responsabilidade sua

A API resolve a captura, a análise e a devolução do veredito. Ela não decide o que sua aplicação faz com esse resultado, não controla a iluminação do ambiente e não substitui a comparação facial contra o documento, que é outra chamada.

Vale fixar a distinção desde o início. Prova de vida responde "havia uma pessoa real ali?". Comparação facial responde "essa pessoa é a mesma do documento?". Liveness aprovado com comparação reprovada acontece, e o oposto também. Tratar os dois como um sinal só origina boa parte dos bugs de fluxo.

Existe ainda a escolha entre modelo ativo, que pede uma ação ao usuário, e passivo, que analisa o sinal sem instrução explícita. A diferença está em liveness ativo ou passivo.

O fluxo de ponta a ponta, passo a passo

1. Início da sessão. O seu backend chama o endpoint de criação de sessão e recebe um identificador e um token de curta duração. O token vai para o cliente, nunca a credencial da conta. Validade curta é desenho, não detalhe: limita a janela de reuso por um atacante.
2. Entrega do token ao cliente. O app ou a página web inicializa o componente de captura com esse identificador. É aqui que você declara parâmetros como tentativas permitidas e URL de retorno.
3. Captura no dispositivo. O componente pede permissão de câmera, avalia enquadramento, distância e iluminação e só então captura. Boa parte da qualidade final se decide antes de qualquer análise.
4. Envio do material. O pacote capturado vai para o serviço de análise, idealmente direto do cliente para o fornecedor. Isso reduz a superfície de dado sensível sob sua custódia.
5. Análise. O serviço avalia sinais de vivacidade e de manipulação. A referência pública de teste é a norma ISO/IEC 30107-3 (2023), que define metodologia e formato de relatório para detecção de ataque de apresentação.
6. Resultado. Seu backend recebe o veredito, por consulta de status ou por webhook. Nunca confie no resultado que chega só pelo cliente.
7. Decisão e registro. Sua aplicação aplica a regra de negócio e grava a evidência: sessão, horário, resultado, motivo da falha e versão da política aplicada.
8. Reapresentação. Falha recuperável devolve o usuário ao passo 3 com sessão nova e contador. Falha não recuperável vai para fila de análise humana ou bloqueio.

O passo 7 separa integração madura de integração apressada. Sem registro de evidência você tem um fluxo que funciona, mas não tem como demonstrar depois como a validação foi feita.

App e web: o que muda na captura

Rodar a prova de vida em aplicativo nativo e rodar em navegador são cenários diferentes o bastante para exigir decisões separadas.

• Acesso à câmera. App nativo (SDK): API nativa, com controle de foco, exposição e resolução. Web (navegador): getUserMedia, com limitações por navegador e exigência de HTTPS.
• Sinais de dispositivo disponíveis. App nativo (SDK): Mais ricos: sensores, integridade do app, atestação de plataforma. Web (navegador): Mais restritos, dependentes do que o navegador expõe.
• Risco de injeção de vídeo. App nativo (SDK): Menor, mas existente em dispositivo comprometido. Web (navegador): Maior, porque câmera virtual é mais simples de instalar.
• Atrito de adoção. App nativo (SDK): Exige instalação prévia do app. Web (navegador): Funciona por link, útil em fluxo de reverificação.
• Atualização do componente. App nativo (SDK): Depende do ciclo da loja de aplicativos. Web (navegador): Imediata, servida pelo fornecedor.
• Uso típico. App nativo (SDK): Onboarding e autenticação recorrente. Web (navegador): Cadastro em desktop, reverificação pontual, atendimento assistido.

A leitura prática: se o seu produto é um marketplace com vendedores que se cadastram do computador, você vai precisar do caminho web mesmo tendo app. E aí a análise de sinal de dispositivo pesa mais, porque câmera virtual é um vetor barato.

Quando a captura falha: iluminação, rede e enquadramento

Falha de captura quase nunca é falha do usuário. É contraluz, câmera suja, conexão que cai no meio do upload, celular perto demais do rosto. Trate esses casos em categorias distintas, porque a resposta é diferente:

• Falha de qualidade (iluminação, enquadramento, nitidez): o componente detecta antes de enviar e pede nova captura com instrução específica. "Tente de novo" não ajuda; "afaste o rosto e vire para a luz" ajuda.
• Falha de rede (upload interrompido, timeout): a sessão precisa sobreviver a uma retomada curta. Se expirou, seu backend abre outra de forma transparente, sem devolver o usuário ao começo do cadastro.
• Falha de permissão (câmera negada): não é erro de liveness, é erro de fluxo. A tela precisa explicar como reabilitar a permissão.
• Falha de análise (sinal de reprodução ou manipulação): a única que deve contar para o limite de tentativas com peso de risco.

Misturar as quatro em um contador só é o erro mais comum. Quem mistura ou trava usuário legítimo por problema de rede, ou dá tentativas infinitas a quem está testando uma máscara.

Como desenhar a reapresentação sem criar loop infinito

Um limite fixo de tentativas resolve metade do problema e cria outro: o usuário que estourou o limite por contraluz fica sem saída. O desenho que se sustenta tem três camadas. Primeiro, um limite por sessão para falhas de qualidade, com orientação diferente a cada tentativa. Segundo, um limite menor e independente para falhas de análise, porque repetição aqui é sinal de risco, não de ambiente ruim. Terceiro, uma saída definida quando qualquer limite estoura: fila de análise humana, canal assistido ou reagendamento, nunca uma tela sem caminho.

Registre o motivo de cada falha. É esse histórico que distingue o usuário que tentou várias vezes num corredor escuro do dispositivo que tentou várias vezes com rostos diferentes. O mesmo raciocínio vale quando a prova de vida é chamada de novo em um momento sensível da conta, tema de deepfake e ataque por injeção.

O que fazer agora

1. Desenhe a máquina de estados da sessão antes de escrever código: criada, capturando, enviada, aprovada, reprovada, expirada, erro técnico.
2. Separe os contadores de falha por categoria e defina limite e saída para cada um.
3. Confirme o resultado sempre no backend, por webhook ou consulta de status.
4. Grave evidência mínima por tentativa: sessão, horário, resultado, motivo e versão da política aplicada.
5. Teste o fluxo em condição ruim de propósito: contraluz, rede instável, permissão negada e navegador desatualizado.

Perguntas frequentes

Prova de vida e reconhecimento facial são a mesma coisa? Não. Prova de vida verifica se há uma pessoa real diante da câmera. Reconhecimento ou comparação facial verifica se aquele rosto corresponde a uma referência, como a foto do documento. São chamadas diferentes e podem retornar resultados diferentes.

Preciso de aplicativo para usar uma API de prova de vida? Não. O fluxo roda em navegador com acesso à câmera via getUserMedia, exigindo HTTPS. O app nativo dá acesso a mais sinais de dispositivo, então a escolha depende do vetor de ataque que você precisa cobrir.

Quantas tentativas devo permitir? Depende da categoria da falha. Qualidade e rede admitem mais tentativas, com orientação específica a cada uma. Falha de análise pede limite curto, porque repetição indica tentativa de burlar a checagem. Defina sempre uma saída quando o limite estourar.

O resultado pode chegar só pelo cliente? Não é recomendado. O retorno do cliente serve para atualizar a interface. A decisão de negócio deve usar o resultado confirmado no seu backend, por webhook ou consulta de status, porque o que trafega no dispositivo pode ser adulterado.

Para avaliar como isso se aplica à sua operação, fale com o time comercial da Shiel ID.