> ## 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 de correspondência facial: JSON de similaridade > Consulte o relatório de correspondência facial 1:1 da Didit: estados, pontuação de similaridade, URLs de imagens, avisos e respostas da API. ## Visão geral O **relatório de correspondência facial** regista uma comparação biométrica 1:1 entre a selfie em direto capturada durante a prova de vida e uma imagem de referência — mais frequentemente o retrato extraído do documento de identificação. Devolve uma pontuação de semelhança única de 0 a 100, URLs assinados para as duas imagens comparadas, a sessão de origem da imagem de referência e quaisquer avisos gerados pela correspondência. O relatório é gerado após o utilizador concluir tanto o passo de prova de vida como o passo de documento num fluxo (ou, no caso de fluxos baseados em retrato, como a autenticação biométrica, apenas após a prova de vida), ou diretamente através da [API de correspondência facial](https://docs.didit.me/pt/standalone-apis/face-match.md) autónoma quando fornece por si próprio duas imagens de rostos arbitrárias. Cada relatório inclui o seu próprio `status` — independente do estado geral da sessão — que reflete como o passo de correspondência facial foi resolvido isoladamente: * **Aprovado** — o `score` está acima do limiar de revisão e não foi acionado nenhum aviso de recusa automática. * **Em Revisão** — o `score` está entre os limiares de recusa e de revisão, ou não foi possível calcular nenhuma pontuação e `face_match_not_computed_action` é `REVIEW`. * **Recusado** — o `score` está no limiar de recusa ou abaixo dele, `NO_REFERENCE_IMAGE` foi acionado, ou não foi possível calcular nenhuma pontuação e `face_match_not_computed_action` é `DECLINE`. * **Reenvio solicitado** — um revisor solicitou que o utilizador submetesse novamente este passo a partir da consola. * **Não concluído** — o passo de correspondência facial ainda não produziu um resultado (incluindo enquanto o utilizador está a tentar novamente uma captura que falhou). ## Onde surge nas respostas da API O relatório de correspondência facial é incluído dentro do array `face_matches[]` — **sempre um array JSON**, nunca um objeto `face_match` singular. Fica a `null` até que pelo menos um passo de correspondência facial tenha produzido dados, e surgem múltiplas entradas quando um fluxo executa a correspondência facial mais de uma vez. Um fluxo de [Adaptive Age Verification](https://docs.didit.me/pt/core-technology/age-estimation/overview.md#estimativa-de-idade-adaptativa) também o preenche quando é executada a alternativa de verificação de identidade: essa entrada reporta o nó de estimativa de idade como o seu `node_id`, uma vez que o fluxo não tem um nó de correspondência facial próprio. * **API de decisão de sessão** — `GET /v3/session/{sessionId}/decision/` devolve `face_matches[]` no nível superior. Consulte [Obter decisão da sessão](https://docs.didit.me/pt/sessions-api/retrieve-session.md). * **Webhooks** — os payloads de `session.status.updated` incluem o mesmo array `face_matches[]` assim que o passo tiver produzido dados. Consulte [Webhooks](https://docs.didit.me/pt/integration/webhooks.md). * **API de correspondência facial autónoma** — para comparações diretas 1:1, consulte [API de correspondência facial autónoma](https://docs.didit.me/pt/standalone-apis/face-match.md). > [!NOTE] > > Leia `response.face_matches[0]` e itere pelo array — a estrutura singular `face_match` referida em alguns tutoriais mais antigos não existe no endpoint de decisão da v3. ## Esquema O esquema canónico campo a campo encontra-se na página de referência [Modelos de dados](https://docs.didit.me/pt/reference/data-models.md#correspondência-facial). Os campos abaixo refletem esse esquema canónico. | Campo | Tipo | Descrição | | - | - | - | | `status` | `"Approved" \| "Declined" \| "In Review" \| "Resub Requested" \| "Not Finished"` | Estado do passo de correspondência facial (`FeatureStatusChoices`). | | `node_id` | string \| null | Nó do grafo do fluxo que produziu este relatório. | | `score` | number 0–100 \| null | Pontuação de semelhança biométrica, arredondada a 2 casas decimais. `null` quando não foi possível realizar qualquer comparação. | | `source_image_session_id` | string \| null | UUID da sessão cujo retrato guardado forneceu a imagem de referência (origem) — definido em fluxos baseados em retrato (autenticação biométrica ou um retrato fornecido 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 assinado) | A imagem de referência (geralmente o retrato do documento). URL assinado de curta duração — descarregue de imediato, nunca persista o URL. | | `target_image` | string (URL assinado) | A imagem de destino (geralmente a selfie da prova de vida). URL assinado de curta duração — descarregue de imediato, nunca persista o URL. | | `warnings[]` | array | Avisos ao nível do módulo. Cada entrada inclui `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/core-technology/face-match/warnings-face-match.md). | ## Valores de estado | Estado | Significado | Efeito a jusante | | - | - | - | | `Approved` | Pontuação acima do limiar de revisão e nenhum aviso de recusa automática acionado. | Conta como uma correspondência facial bem-sucedida. | | `In Review` | Pontuação acima do limiar de recusa, mas igual ou inferior ao limiar de revisão, ou não foi possível calcular nenhuma pontuação (`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 muda para `In Review` até que um revisor intervenha. | | `Declined` | Pontuação igual ou inferior ao limiar de recusa, `NO_REFERENCE_IMAGE` acionado, ou não foi possível calcular nenhuma pontuação 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 o reenvio deste passo a partir da consola. | É solicitado ao utilizador que efetue uma nova captura. | | `Not Finished` | O passo de correspondência facial não produziu um resultado (faltava uma entrada, o fluxo nunca atingiu o passo de comparação, ou o utilizador ainda se encontra no ciclo de nova tentativa de captura). | A ramificação não foi concluída. | As falhas por baixa semelhança são novamente tentadas antes de o estado se tornar definitivo: o utilizador pode efetuar até `face_match_max_attempts` capturas (3 por predefinição), e apenas a pontuação da tentativa final é aplicada. Regras de estado personalizadas configuradas no nó do fluxo podem ajustar ainda mais o estado resultante, combinando-se com o estado derivado da pontuação sob a precedência `Declined` > `In Review` > `Approved`. ## Exemplos ### Aprovado — correspondência limpa ```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 — semelhança limítrofe ```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 — sem 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 Os URLs assinados para `source_image` e `target_image` constituem dados biométricos e expiram após uma janela de validade curta. Trate-os como efémeros: não os guarde em cache nem os exponha publicamente. Normalmente, a sua aplicação apenas precisa de `status` e `score` — armazene o mínimo possível para minimizar os dados biométricos nos seus servidores. ## Relacionado * [Avisos de correspondência facial](https://docs.didit.me/pt/core-technology/face-match/warnings-face-match.md) — enum completo de avisos, causas e remediação. * [Relatório de prova de vida](https://docs.didit.me/pt/core-technology/liveness/report-liveness.md) — o passo a montante que captura a imagem de destino. * [Webhooks](https://docs.didit.me/pt/integration/webhooks.md) — monitorize `session.status.updated` para receber o relatório. * [Modelos de dados — Correspondência facial](https://docs.didit.me/pt/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.