> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Relatório Face Match: JSON da pontuação de similaridade > Como ler o relatório de face match 1:1 da Didit: status, pontuação de similaridade, URLs das imagens de origem/destino, avisos e onde aparece na API. ## 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](https://docs.didit.me/pt-br/standalone-apis/face-match.md) 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](https://docs.didit.me/pt-br/core-technology/age-estimation/overview.md#estimativa-de-idade-adaptativa) 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](https://docs.didit.me/pt-br/sessions-api/retrieve-session.md). * **Webhooks**: os payloads de `session.status.updated` incluem o mesmo array `face_matches[]` assim que a etapa produz dados. Consulte [Webhooks](https://docs.didit.me/pt-br/integration/webhooks.md). * **API de Correspondência facial independente**: para comparações 1:1 diretas, consulte [API independente de Correspondência facial](https://docs.didit.me/pt-br/standalone-apis/face-match.md). > [!NOTE] > > 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](https://docs.didit.me/pt-br/reference/data-models.md#correspondência-facial). 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](https://docs.didit.me/pt-br/core-technology/face-match/warnings-face-match.md). | ## 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 ```json theme={null} { "face_matches": [ { "status": "Approved", "node_id": "feature_face_match_1", "score": 96.42, "source_image_session_id": null, "source_image": "https:///source-image.jpg", "target_image": "https:///target-image.jpg", "warnings": [] } ] } ``` ### Em revisão: similaridade no limite ```json theme={null} { "face_matches": [ { "status": "In Review", "node_id": "feature_face_match_1", "score": 65.43, "source_image_session_id": null, "source_image": "https:///source-image.jpg", "target_image": "https:///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 ```json theme={null} { "face_matches": [ { "status": "Declined", "node_id": "feature_face_match_1", "score": null, "source_image_session_id": null, "source_image": null, "target_image": "https:///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](https://docs.didit.me/pt-br/core-technology/face-match/warnings-face-match.md): enum completo de avisos, causas e como corrigi-los. * [Relatório de prova de vida](https://docs.didit.me/pt-br/core-technology/liveness/report-liveness.md): a etapa anterior, que captura a imagem de destino. * [Webhooks](https://docs.didit.me/pt-br/integration/webhooks.md): ouça `session.status.updated` para receber o relatório. * [Modelos de dados: Correspondência facial](https://docs.didit.me/pt-br/reference/data-models.md#correspondência-facial): esquema canônico com todos os campos. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.