Relatório Face Match: JSON da pontuação de similaridade

Visão geral

O relatório de correspondência facial registra uma comparação biométrica 1:1 entre a selfie capturada ao vivo durante a prova de vida e uma imagem de referência, que geralmente é o retrato extraído do documento de identidade. Ele retorna uma única pontuação de similaridade de 0 a 100, URLs assinadas das duas imagens comparadas, a sessão de origem da imagem de referência e os avisos gerados pela correspondência. O relatório é gerado depois que o usuário conclui a etapa de prova de vida e a etapa de documento em um fluxo de verificação (workflow). Em fluxos baseados em retrato, como a autenticação biométrica, ele é gerado apenas após a prova de vida. Também é possível obtê-lo diretamente pela API de Correspondência facial independente, quando você mesmo envia duas imagens de rosto quaisquer. Cada relatório tem seu próprio status, independente do status geral da sessão, que indica como a etapa de correspondência facial foi resolvida por si só:

Approved: score está acima do limiar de revisão e nenhum aviso de recusa automática foi disparado.
In Review: score está entre os limiares de recusa e de revisão, ou nenhuma pontuação pôde ser calculada e face_match_not_computed_action é REVIEW.
Declined: score está no limiar de recusa ou abaixo dele, NO_REFERENCE_IMAGE foi disparado, ou nenhuma pontuação pôde ser calculada e face_match_not_computed_action é DECLINE.
Resub Requested: um revisor solicitou pelo console que o usuário reenvie esta etapa.
Not Finished: a etapa de correspondência facial ainda não produziu resultado, inclusive enquanto o usuário tenta novamente uma captura que falhou.

Onde aparece nas respostas da API

O relatório de correspondência facial vem dentro do array face_matches[], que é sempre um array JSON e nunca um objeto face_match isolado. Ele é null até que pelo menos uma etapa de correspondência facial tenha produzido dados, e aparecem várias entradas quando um fluxo executa a correspondência facial mais de uma vez. Um fluxo de Adaptive Age Verification também o preenche quando o fallback de verificação de identidade é executado. Nesse caso, a entrada informa o nó de estimativa de idade como seu node_id, já que o fluxo não tem um nó de Correspondência facial próprio.

API de decisão da sessão: GET /v3/session/{sessionId}/decision/ retorna face_matches[] no nível superior. Consulte Obter a decisão da sessão.
Webhooks: os payloads de session.status.updated incluem o mesmo array face_matches[] assim que a etapa produz dados. Consulte Webhooks.
API de Correspondência facial independente: para comparações 1:1 diretas, consulte API independente de Correspondência facial.

Leia response.face_matches[0] e percorra o array. O formato singular face_match, citado em alguns tutoriais antigos, não existe no endpoint de decisão v3.

Esquema

O esquema canônico, campo a campo, está na página Modelos de dados. Os campos abaixo reproduzem esse esquema canônico.

Campo	Tipo	Descrição
`status`	`"Approved" \| "Declined" \| "In Review" \| "Resub Requested" \| "Not Finished"`	Status da etapa de correspondência facial (`FeatureStatusChoices`).
`node_id`	string \| null	Nó do grafo do fluxo que gerou este relatório.
`score`	number 0–100 \| null	Pontuação de similaridade biométrica, arredondada para 2 casas decimais. `null` quando nenhuma comparação foi possível.
`source_image_session_id`	string \| null	UUID da sessão cujo retrato armazenado forneceu a imagem de referência (de origem). É definido em fluxos baseados em retrato (autenticação biométrica ou um retrato enviado na criação da sessão). `null` quando a imagem de referência é o retrato do documento capturado na mesma sessão.
`source_image`	string (URL assinada)	A imagem de referência (geralmente o retrato do documento). URL assinada de curta duração: faça o download logo e nunca armazene a URL.
`target_image`	string (URL assinada)	A imagem-alvo (geralmente a selfie da prova de vida). URL assinada de curta duração: faça o download logo e nunca armazene a URL.
`warnings[]`	array	Avisos do módulo. Cada entrada contém `feature` (sempre `"FACEMATCH"`), `risk`, `additional_data`, `log_type`, `short_description`, `long_description` e `node_id`. Consulte Avisos de correspondência facial.

Valores de status

Status	Significado	Efeito posterior
`Approved`	Pontuação acima do limiar de revisão e nenhum aviso de recusa automática disparado.	Conta como uma correspondência facial bem-sucedida.
`In Review`	Pontuação acima do limiar de recusa, mas no limiar de revisão ou abaixo dele, ou nenhuma pontuação pôde ser calculada (`FACE_MATCH_NOT_COMPUTED`, por exemplo após uma consulta sem documento que não deixou referência) com `face_match_not_computed_action` definido como `REVIEW`.	A sessão também passa para `In Review` até que um revisor aja.
`Declined`	Pontuação no limiar de recusa ou abaixo dele, `NO_REFERENCE_IMAGE` disparado, ou nenhuma pontuação pôde ser calculada com `face_match_not_computed_action` definido como `DECLINE`.	A sessão é recusada, a menos que outra ramificação aprovada satisfaça o fluxo.
`Resub Requested`	Um revisor solicitou pelo console o reenvio desta etapa.	O usuário precisa fazer a captura novamente.
`Not Finished`	A etapa de correspondência facial não produziu resultado (uma entrada estava ausente, o fluxo nunca chegou à etapa de comparação ou o usuário ainda está no ciclo de novas tentativas de captura).	A ramificação não foi concluída.

Falhas por baixa similaridade geram novas tentativas antes de o status ser definido: o usuário tem até face_match_max_attempts tentativas de captura (3 por padrão), e apenas a pontuação da última tentativa é aplicada. Regras de status personalizadas configuradas no nó do fluxo podem ajustar ainda mais o status resultante. Elas se combinam com o status derivado da pontuação seguindo a precedência Declined > In Review > Approved.

Exemplos

Aprovado: correspondência sem ressalvas

{
  "face_matches": [
    {
      "status": "Approved",
      "node_id": "feature_face_match_1",
      "score": 96.42,
      "source_image_session_id": null,
      "source_image": "https://<media-host>/source-image.jpg",
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": []
    }
  ]
}

Em revisão: similaridade no limite

{
  "face_matches": [
    {
      "status": "In Review",
      "node_id": "feature_face_match_1",
      "score": 65.43,
      "source_image_session_id": null,
      "source_image": "https://<media-host>/source-image.jpg",
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "LOW_FACE_MATCH_SIMILARITY",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face match similarity",
          "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.",
          "node_id": "feature_face_match_1"
        }
      ]
    }
  ]
}

Recusado: nenhuma imagem de referência para comparação

{
  "face_matches": [
    {
      "status": "Declined",
      "node_id": "feature_face_match_1",
      "score": null,
      "source_image_session_id": null,
      "source_image": null,
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "NO_REFERENCE_IMAGE",
          "additional_data": null,
          "log_type": "error",
          "short_description": "No source image found for performing face match",
          "long_description": "A reference image for facial comparison is missing, preventing the system from completing the face matching process.",
          "node_id": "feature_face_match_1"
        }
      ]
    }
  ]
}

Nota de segurança

As URLs assinadas de source_image e target_image são dados biométricos e expiram após um curto período de validade. Trate-as como temporárias: não as armazene em cache nem as exponha publicamente. Normalmente, sua aplicação só precisa de status e score. Armazene o mínimo possível para reduzir os dados biométricos nos seus servidores.

Relacionados

Avisos de correspondência facial: enum completo de avisos, causas e como corrigi-los.
Relatório de prova de vida: a etapa anterior, que captura a imagem de destino.
Webhooks: ouça session.status.updated para receber o relatório.
Modelos de dados: Correspondência facial: esquema canônico com todos os campos.

Autenticação

Verificação

Monitoramento

Plataforma

Relatório Face Match: JSON da pontuação de similaridade

Visão geral

Onde aparece nas respostas da API

Esquema

Valores de status

Exemplos

Aprovado: correspondência sem ressalvas

Em revisão: similaridade no limite

Recusado: nenhuma imagem de referência para comparação

Nota de segurança

Relacionados

​Visão geral

​Onde aparece nas respostas da API

​Esquema

​Valores de status

​Exemplos

​Aprovado: correspondência sem ressalvas

​Em revisão: similaridade no limite

​Recusado: nenhuma imagem de referência para comparação

​Nota de segurança

​Relacionados

Visão geral

Onde aparece nas respostas da API

Esquema

Valores de status

Exemplos

Aprovado: correspondência sem ressalvas

Em revisão: similaridade no limite

Recusado: nenhuma imagem de referência para comparação

Nota de segurança

Relacionados