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.
`ERRO_DE_REDE`	Falha de rede ao contactar a API.
`ERRO_LIVENESS`	Falha no detector de prova de vida.
`CANCELADO_PELO_USUARIO`	Usuário cancelou a verificação.
`SESSAO_INCOMPLETA`	API não retornou dados necessários para liveness.

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. No backend, valide o verificationId com GET /v1/sessions/:verificationId em vez de confiar só no JSON do navegador.

Reiniciar o fluxo (UI customizada)

Com showResultScreen={false}, use useTechfaceReset(id) com o mesmo id do componente. Mantenha o SDK montado (ocultar com CSS é ok):

const reset = useTechfaceReset("verificacao");
const [result, setResult] = useState<VerificationResult | null>(null);

<div style={{ display: result ? "none" : "block" }}>
  <LivenessCheck
    id="verificacao"
    showResultScreen={false}
    onResult={setResult}
  />
</div>

{result && (
  <button
    type="button"
    onClick={() => {
      setResult(null);
      reset();
    }}
  >
    Tentar novamente
  </button>
)}

Com a tela de resultado padrão do SDK, o botão "Tentar novamente" já reinicia o fluxo — o hook não é necessário.

Personalizar a tela de resultado (`resultFields`)

Com a tela do SDK ativa (showResultScreen padrão true), a prop resultFields define quais linhas de detalhe a ResultScreen exibe. O JSON completo continua em onResult — a prop só altera a UI.

Sempre aparecem: título aprovado/reprovado e o botão "Tentar novamente" (quando o fluxo oferece retry). Campos sem dado no resultado (ex.: faceMatch em um fluxo só de liveness) são ignorados mesmo se listados.

Valor	O que mostra na UI	Só aparece se…
`type`	Subtítulo do tipo de verificação	—
`liveness`	Pessoa viva: sim / não	`result.liveness` existir
`livenessConfidence`	Confiança da prova de vida (%)	`result.liveness` existir
`faceMatch`	Match facial: sim / não	`result.faceMatch` existir
`similarity`	Similaridade (%)	`result.faceMatch` existir
`verificationId`	ID da verificação	—
`timestamp`	Data/hora da conclusão	—

Padrão: todos os campos (DEFAULT_RESULT_FIELDS). Array vazio [] = só o título (e retry).

Exemplos

Liveness — só métricas

<LivenessCheck
  resultFields={["liveness", "livenessConfidence"]}
  onResult={(result) => console.log(result)}
/>

Face match — tipo + similaridade

<FaceMatchCheck
  liveness
  referenceImage={{ url: "https://exemplo.com/documento.jpg" }}
  resultFields={["type", "faceMatch", "similarity"]}
  onResult={(result) => console.log(result)}
/>

Só título aprovado/reprovado

<LivenessCheck
  resultFields={[]}
  onResult={(result) => console.log(result)}
/>

ResultScreen avulsa (UI híbrida)

import { ResultScreen, useTechfaceReset } from "techface-sdk";

const reset = useTechfaceReset("verificacao");

{result && (
  <ResultScreen
    result={result}
    onRetry={() => {
      setResult(null);
      reset();
    }}
    resultFields={["faceMatch", "similarity"]}
  />
)}

Detalhes das props em Componentes.

Ocultar a tela de resultado do SDK

Se preferir montar sua própria UI completa (não só filtrar campos), desative a tela interna. Combine com id + useTechfaceReset para o botão de retry (veja a seção acima).

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

Para apenas esconder linhas da tela pronta do SDK, use resultFields — não precisa de showResultScreen={false}.