Documentação

Resultado e erros (SDK)

Conteúdo exclusivo do SDK React: callbacks onResult e onError. Para respostas HTTP da API REST, veja Erros da API.

VerificationResult

Objeto retornado em onResult após cada verificação concluída com sucesso (inclusive quando approved é false — reprovação não dispara onError).

Prova de vida

type: liveness

{
  "verificationId": "7b5ced4c-678b-4574-8898-62aad1ece852",
  "type": "liveness",
  "approved": true,
  "liveness": {
    "isLive": true,
    "confidence": 98.4
  },
  "selfieBase64": "/9j/4AAQSkZJRg...",
  "timestamp": "2026-07-15T15:00:00.000Z"
}

Prova de vida + comparação facial

type: liveness_facematch

{
  "verificationId": "7b5ced4c-678b-4574-8898-62aad1ece852",
  "type": "liveness_facematch",
  "approved": true,
  "liveness": {
    "isLive": true,
    "confidence": 98.4
  },
  "faceMatch": {
    "matched": true,
    "similarity": 99.1
  },
  "selfieBase64": "/9j/4AAQSkZJRg...",
  "timestamp": "2026-07-15T15:00:00.000Z"
}

Comparação facial simples (sem liveness)

type: facematch

{
  "verificationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "facematch",
  "approved": true,
  "faceMatch": {
    "matched": true,
    "similarity": 97.2
  },
  "selfieBase64": "/9j/4AAQSkZJRg...",
  "timestamp": "2026-07-15T15:00:00.000Z"
}

Campos do VerificationResult

Campo	Descrição
`verificationId`	Identificador único da verificação na API techfaceID.
`type`	`liveness`, `facematch` ou `liveness_facematch`.
`approved`	`true` quando todos os critérios do fluxo foram atendidos.
`liveness`	Presente em fluxos com prova de vida: `isLive` e `confidence` (%).
`faceMatch`	Presente em fluxos com comparação: `matched` e `similarity` (%).
`selfieBase64`	JPEG em base64 (sem prefixo `data:`). Capturado no frontend e anexado ao JSON no cliente antes de chamar `onResult`. Presente nos três fluxos quando a captura local é bem-sucedida. A API não devolve esse campo — veja a tabela abaixo sobre tráfego.
`timestamp`	Data/hora ISO 8601 da conclusão.

Selfie por fluxo

O campo selfieBase64 sempre aparece no onResult quando há captura local. O que muda é se a imagem também trafega na API:

Fluxo	No `onResult`	Enviada à API
`liveness`	Sim — frame da câmera de liveness	Não
`liveness_facematch`	Sim — frame da câmera de liveness	Não — a comparação usa a imagem de referência do provedor de liveness
`facematch`	Sim — selfie capturada pelo componente	Sim — necessária para a comparação facial no servidor

Em fluxos com liveness, o SDK captura a selfie do vídeo no navegador e concatena com a resposta da API. Isso evita tráfego extra de imagem na resposta HTTP, mantendo a foto disponível para o seu backend ou armazenamento local via onResult.

Tratamento de erros

Falhas de rede, autenticação, câmera ou verificação chegam em onError como TechfaceError:

onError={(error) => {
  console.error(error.code);    // ex.: API_KEY_INVALIDA
  console.error(error.message); // mensagem em pt-BR
}}

Em caso de erro, onResult não é chamado e selfieBase64 não é incluído no callback de erro — mesmo que a câmera já tenha capturado frames durante a tentativa.

Erros comuns recebidos em onError:

Código	Significado
`API_KEY_AUSENTE`	apiKey não configurada ou cabeçalho Authorization ausente.
`API_KEY_INVALIDA`	Chave inválida ou não encontrada.
`APIKEY_REVOGADA`	Chave revogada no dashboard.
`ORIGEM_NAO_AUTORIZADA`	Domínio da requisição não está na lista de domínios autorizados da chave.
`SEM_CONEXAO`	Falha de rede ao contactar a API.
`ROSTO_NAO_DETECTADO`	Nenhum rosto detectado na captura ou referência.
`MULTIPLOS_ROSTOS_DETECTADOS`	Mais de um rosto na imagem.

Lista completa de códigos HTTP e detalhes por endpoint em Erros da API.

Toda verificação concluída fica registrada no dashboard com resultado, confiança, similaridade, IP e user-agent para auditoria. A selfie em base64 fica apenas no JSON entregue ao seu app via onResult, salvo se você persistir localmente.

Ocultar a tela de resultado do SDK

Se preferir exibir seu próprio UI, desative a tela interna e use apenas o callback:

<LivenessCheck
  showResultScreen={false}
  onResult={(result) => {
    // result.selfieBase64, result.approved, etc.
  }}
/>