Liveness Advanced

A TechTrue® oferece duas soluções de detecção de vivacidade para atender diferentes necessidades de segurança:

Comparação das Soluções de Liveness

Liveness Essencial

O Liveness Essencial é nossa solução integrada ao serviço de reconhecimento facial, disponível sem custo adicional. Ele fornece detecção de ataques de apresentação (PAD) através de algoritmos avançados de análise facial, sendo indispensável para aplicações que utilizam nosso serviço de reconhecimento facial.

Este serviço é ativado através do parâmetro doLivenessCheck nas requisições de cadastro e verificação facial. Quando habilitado, o sistema avalia automaticamente se a imagem enviada corresponde a uma pessoa real ou a uma tentativa de fraude por apresentação (foto de foto, vídeo, máscara, etc.).

Exemplo de Uso - Cadastrar uma Face com Liveness

shell

curl "https://api.techtrue.com.br/api/v1/services/face/enroll/{ext_id}" \
  -X POST --data "@images.json" \
  -H "Authorization: Bearer {{token}}"

node.js

const axios = require('axios');

let data = JSON.stringify({
  "doLivenessCheck": true,
  "ReturnTemplate": false,
  "Images": [
    {
      "imageType": "frontal",
      "imageData": "{{base64_string}}"
    }
  ]
});

let config = {
  method: 'post',
  url: 'https://api.techtrue.com.br/api/v1/services/face/enroll/{ext_id}',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{token}}'
  },
  data: data
};

axios(config)
  .then((response) => {
    console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
    console.log(error);
  });

O comando acima retorna o seguinte JSON em caso de sucesso:

{
  "result": {
    "code": 1000,
    "message": "ENROLLED_SUCCESSFULLY"
  }
}

Retorno em caso de falha no Liveness Check:

{
  "result": {
    "code": 1013,
    "message": "LIVENESS_CHECK_FAILED",
    "detail": "liveness check failed"
  }
}

Parâmetro doLivenessCheck:

O parâmetro doLivenessCheck, quando definido como true, informa o serviço que deve executar o processo de avaliação de vivacidade sobre as imagens enviadas. Caso a avaliação indique uma tentativa de ataque de apresentação, a requisição retorna erro no JSON.

Dica

Para mais detalhes sobre o serviço de reconhecimento facial e outras funcionalidades, consulte a documentação de Cadastrar uma Face.

Liveness Advanced

O Liveness Advanced é nossa solução especializada de detecção de vivacidade, desenvolvida para ambientes controlados que exigem proteção contra ataques sofisticados. Este serviço opera de forma integrada e complementar ao reconhecimento facial, oferecendo uma camada avançada de segurança.

A principal característica desta solução está na sua capacidade de detectar e prevenir ataques de injeção digital, que representam a nova geração de tentativas de fraude e são particularmente relevantes em aplicações web, desktop e ambientes de alto risco:

• Câmeras virtuais: Detecção de software que simula dispositivos de captura
• Injeção de dispositivos externos: Identificação de conteúdo injetado através de dispositivos físicos
• Ataques baseados em navegador: Proteção contra manipulações no ambiente do navegador
• Ataques em nível de rede: Detecção de interceptação e modificação de dados em trânsito
• Manipulação avançada de conteúdo: Identificação de deepfakes, face swap, morphing facial e renderização 3D

Ambientes Ideais para Liveness Advanced

O Liveness Advanced é recomendado para:

• Ambientes controlados de alto risco: Transações financeiras, contratos digitais e autenticações críticas
• Aplicações web e desktop: Plataformas onde ataques de injeção são mais prevalentes
• Conformidade regulatória rigorosa: Setores que exigem proteção contra fraudes sofisticadas
• Prevenção de fraudes emergentes: Proteção contra deepfakes e tecnologias avançadas de manipulação digital

Visão Geral da Arquitetura

Para utilizar o serviço de Liveness Advanced, é necessário integrar a Web Capture Library em sua aplicação web. Esta biblioteca JavaScript é fornecida pela TechTrue® e desempenha um papel essencial no processo de segurança, sendo obrigatória para o funcionamento do serviço.

A biblioteca controla todo o processo de captura no lado do cliente, coleta metadados críticos de segurança do ambiente de execução e criptografa o payload de forma segura antes de enviá-lo para validação através da API da TechTrue®. Sem esta biblioteca, o endpoint de liveness não pode validar a autenticidade da captura.

Web Capture Library

A Web Capture Library é fornecida pela TechTrue® junto com sua documentação técnica completa. A biblioteca é essencial para garantir a integridade do processo de detecção de ataques de injeção e seu uso é obrigatório para acessar o endpoint do Liveness Advanced.

Nota

A documentação técnica detalhada da Web Capture Library, incluindo guias de integração, exemplos de código e referência completa de API, é fornecida junto com o pacote da biblioteca. Entre em contato com o suporte da TechTrue® para obter acesso.

Requisitos do Sistema

Requisitos da Câmera

• Resolução mínima: 640x480 pixels
• Resoluções abaixo desse limite irão disparar o erro “Resolução da câmera muito baixa”

Requisitos do Servidor Web

• Protocolo HTTPS (obrigatório para permissões de câmera)
• Suporte para contextos seguros (localhost é aceitável para desenvolvimento)

Requisitos do Navegador

• Suporte à API MediaStream
• Suporte a WebAssembly
• Suporte a WebGL (necessário para o recurso de captura automática)

Navegadores Suportados

Navegador	Versão Mínima
Chrome Desktop	v103
Chrome (Android)	v112
Firefox Desktop	v103
Firefox (Android)	v110
Microsoft Edge	v103
Safari Desktop	v15.1
Safari (iOS)	v15.0
Opera Desktop	v86
Opera Mobile	v73
Samsung Internet	v11.1

Endpoint da API

Verificar Liveness

Para verificar a vivacidade, use o código abaixo:

shell

curl -X POST "https://api.techtrue.com.br/api/v1/services/liveness/check" \
  -H "Authorization: Bearer {{token}}" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @payload_criptografado.bin

node.js

const axios = require('axios');
const fs = require('fs');

// Leia o arquivo criptografado da Web Capture Library
const encryptedFile = fs.readFileSync('payload_criptografado.bin');

const config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.techtrue.com.br/api/v1/services/liveness/check',
  headers: {
    'Content-Type': 'application/octet-stream',
    'Authorization': 'Bearer {{token}}'
  },
  data: encryptedFile
};

axios(config)
  .then((response) => {
    console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
    console.log(error);
  });

fetch

// Usando o arquivo criptografado da Web Capture Library
const encryptedFile = event.detail[0].encryptedFile;

fetch('https://api.techtrue.com.br/api/v1/services/liveness/check', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/octet-stream',
    'Authorization': `Bearer ${token}`
  },
  body: encryptedFile
})
  .then(response => response.json())
  .then(result => {
    console.log('Resultado do liveness:', result);
  })
  .catch(error => {
    console.error('Erro:', error);
  });

Endpoint que verifica a vivacidade de uma selfie capturada usando a Web Capture Library. O payload criptografado contém tanto a imagem quanto os metadados necessários para detecção abrangente de fraudes.

Requisição HTTP

POST /api/v1/services/liveness/check

Headers

Nome	Descrição	Obrigatório	Tipo
Authorization	Token Bearer obtido através da autenticação	Sim	string
Content-Type	Deve ser application/octet-stream	Sim	string

Corpo da Requisição

O corpo da requisição deve ser o payload binário criptografado bruto gerado pela Web Capture Library. Isso não é JSON - é um blob binário que deve ser enviado como application/octet-stream.

Importante

Não tente analisar ou modificar o payload criptografado. Envie-o exatamente como recebido do evento capture da Web Capture Library.

Resposta - Sucesso

Estrutura da resposta quando a verificação de liveness é aprovada:

{
  "success": true,
  "data": {
    "face_liveness": {
      "probability": 0.9969119
    },
    "capture_liveness": {
      "probability": 1.0,
      "score": 1.0,
      "rejection": []
    }
  }
}

Campos da Resposta

Campo	Tipo	Descrição
success	boolean	Indica se a requisição foi processada com sucesso
data.face_liveness.probability	number	Probabilidade de que a face seja de uma pessoa viva (0.0 a 1.0)
data.capture_liveness.probability	number	Probabilidade de que a captura seja legítima (0.0 a 1.0)
data.capture_liveness.score	number	Pontuação geral de vivacidade (0.0 a 1.0)
data.capture_liveness.rejection	string[]	Array de motivos de rejeição (vazio se nenhum problema detectado)

Interpretando os Resultados

• probability >= 0.5: A imagem é considerada legítima (VIVA)
• probability < 0.5: A imagem é rejeitada como potencialmente fraudulenta (FALSA)

Recomendação

Para segurança ideal, recomendamos tratar qualquer imagem com probability < 0.5 ou com quaisquer motivos de rejeição como potencialmente fraudulenta, mesmo se marcada com UNTRUSTED_CONTENT_LOW_CONFIDENCE.

Resposta - Rejeitada (Fraude Detectada)

Resposta quando ataque de injeção ou ataque de apresentação é detectado:

{
  "success": true,
  "data": {
    "face_liveness": {
      "probability": 0.1234
    },
    "capture_liveness": {
      "probability": 0.0,
      "score": 0.0,
      "rejection": [
        "UNTRUSTED_CONTENT",
        "SUSPICIOUS_ACTIVITY"
      ]
    }
  }
}

Motivos de Rejeição

Quando probability < 0.5, o array rejection pode conter um ou mais dos seguintes valores:

Código de Rejeição	Descrição
UNTRUSTED_ENVIRONMENT	O ambiente da aplicação não é confiável para ser seguro
SUSPICIOUS_ACTIVITY	Atividade suspeita detectada no dispositivo, potencialmente associada a um ataque
UNTRUSTED_DEVICE	O dispositivo não é confiável ou está se representando incorretamente
SDK_INTEGRITY_VIOLATION	A biblioteca de captura foi adulterada ou modificada
UNTRUSTED_CORRUPTED_PAYLOAD	O payload está corrompido ou foi modificado em trânsito
UNTRUSTED_CONTENT	Ataque de injeção detectado na imagem
UNTRUSTED_CONTENT_LOW_CONFIDENCE	Indicadores de injeção detectados mas com menor confiança

Uso Interno

Os motivos de rejeição são apenas para análise interna e métricas. Não encaminhe códigos de rejeição específicos para a aplicação cliente, pois essa informação pode ajudar atacantes a refinar suas técnicas.

Detecções de Baixa Confiança

Mesmo quando sinalizado como UNTRUSTED_CONTENT_LOW_CONFIDENCE, o sistema detectou indicadores consistentes com tentativas de injeção. Para fins de segurança, recomendamos tratar estes como rejeições válidas. Trabalhamos continuamente para melhorar a precisão da detecção e minimizar falsas rejeições.

Resposta - Erro

Estrutura de resposta de erro:

{
  "timestamp": "2025-11-10T14:30:00.000+00:00",
  "status": 400,
  "error": "Bad Request",
  "message": "Face not found",
  "path": "/api/v1/services/liveness/check",
  "error_code": "FACE_NOT_FOUND"
}

Códigos de Erro

Código HTTP	Mensagem	Código de Erro	Descrição
400	Face not found	FACE_NOT_FOUND	Nenhuma face detectada na imagem
400	Face is cropped	FACE_CROPPED	Face está apenas parcialmente visível na imagem
400	Face is occluded	FACE_IS_OCCLUDED	Face está parcialmente escondida atrás de um objeto
400	Too many faces detected	TOO_MANY_FACES	Mais de uma face está visível na imagem
400	Facial out-of-plane rotation angle is extremely large	FACE_ANGLE_TOO_LARGE	Ângulo da face relativo à câmera é muito extremo
400	Absolute face size is too small	FACE_TOO_SMALL	Resolução da face é insuficiente (deve estar mais próxima da câmera ou usar maior resolução)
400	Relative face size is too small	FACE_TOO_SMALL	Face ocupa muito pouco da imagem (deve estar mais próxima ou mais centralizada)
400	Face is too close to one or more borders	FACE_CLOSE_TO_BORDER	Face está muito próxima das bordas da imagem (deve estar centralizada)
400	Image too small to be processed	IMAGE_TOO_SMALL	Resolução da imagem está abaixo do mínimo de 480p
400	Failed to parse file	UNKNOWN	Arquivo não é um payload criptografado válido ou está corrompido
400	Failed to read metadata	UNKNOWN	Formato do payload criptografado é inválido
400	Failed to decrypt message	UNKNOWN	Incompatibilidade de chave de criptografia entre cliente e servidor
401	Unauthorized	-	Token de autenticação inválido ou ausente
500	Internal Server Error	UNKNOWN	Erro inesperado do servidor

Códigos de Resposta HTTP

Código	Descrição
200	OK - Requisição processada com sucesso (verifique os campos probability e rejection para determinar se o liveness passou)
400	Bad Request - Payload inválido ou problemas de qualidade da imagem
401	Unauthorized - Token de autenticação inválido ou ausente
500	Internal Server Error - Erro inesperado do servidor

Melhores Práticas

Dicas de Integração

1. Forneça instruções claras ao usuário: Oriente os usuários a posicionar o rosto corretamente dentro do quadro de captura.

2. Trate erros graciosamente: Forneça mensagens de erro úteis quando a captura falhar (ex: “Por favor, certifique-se de que seu rosto está totalmente visível e bem iluminado”).

3. Considere condições de iluminação: Incentive os usuários a usar o serviço em ambientes bem iluminados para melhores resultados.

4. Otimização mobile: Embora a biblioteca funcione em navegadores mobile, considere SDKs nativos para aplicativos móveis quando disponíveis.

5. Teste exaustivamente: Teste em diferentes dispositivos, navegadores e condições de iluminação antes da implantação em produção.

Otimização de Performance

1. Tamanho do payload: A Web Capture Library oferece configurações de tamanho de payload. Consulte a documentação técnica da biblioteca para opções de otimização.

2. Considerações de rede: O payload criptografado pode ter vários megabytes. Certifique-se de que sua configuração de rede pode lidar com isso.

3. Tratamento de timeout: Implemente valores de timeout apropriados para requisições à API (recomendado: mínimo de 30 segundos).

Suporte

Para dúvidas, problemas ou para obter o pacote da Web Capture Library e sua documentação técnica completa, entre em contato com o suporte da TechTrue®.

Nota

A Web Capture Library é distribuída separadamente e requer autorização explícita da TechTrue®.