> ## 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 prova de vida: pontuação e correspondências

> Consulte o relatório de prova de vida da Didit: estado, pontuação de confiança, método, estimativa de idade, correspondências faciais e respostas.

## Visão geral

O **relatório de prova de vida** regista tudo o que a Didit observou ao verificar que uma pessoa real e viva estava em frente à câmara — e não uma fotografia impressa, uma reprodução de ecrã ou um deepfake. Inclui o método de prova de vida, uma pontuação de confiança de 0 a 100, a selfie de referência e o vídeo de captura, uma estimativa de idade opcional, métricas de qualidade de prova de vida passiva e correspondências faciais entre sessões com o histórico e a lista de bloqueio da sua aplicação.

O relatório é gerado após o utilizador concluir o passo de prova de vida num fluxo (ou chamar o endpoint facial independente). A Didit executa um dos três métodos de prova de vida (3D ativo, intermitência ou passivo), pontua a captura, faz a triagem de padrões de spoofing conhecidos e compara o rosto biometricamente com todos os outros rostos observados na sua aplicação.

Cada relatório inclui o seu próprio `status` — independente do estado geral da sessão — que reflete como o passo de prova de vida foi resolvido isoladamente:

* **Aprovada** — rosto detetado, pontuação de prova de vida acima do limiar de revisão, nenhum aviso de recusa automática acionado.
* **Em análise** — um ou mais avisos encaminhados para revisão foram acionados, ou a pontuação está no limiar de revisão ou abaixo deste, mas acima do limiar de recusa.
* **Recusada** — uma condição de recusa automática foi acionada (`NO_FACE_DETECTED`, `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST` ou os riscos de idade em fluxos de estimativa de idade), um aviso configurável foi encaminhado para recusa, ou a pontuação está no limiar de recusa ou abaixo deste.
* **Não concluída** — o utilizador nunca concluiu o passo de prova de vida.

## Onde surge nas respostas da API

O relatório de prova de vida surge como `liveness_checks[]` em `GET /v3/session/{sessionId}/decision/` — **sempre como um array JSON**, nunca como um objeto `liveness` singular. Surgem múltiplas entradas quando um fluxo executa a prova de vida mais de uma vez (por exemplo, uma verificação principal mais uma nova captura).

* **API de decisão da sessão** — `GET /v3/session/{sessionId}/decision/` devolve `liveness_checks[]` 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 `liveness_checks[]` assim que o passo tiver produzido dados. Consulte [Webhooks](https://docs.didit.me/pt/integration/webhooks.md).
* **API independente de prova de vida** — consulte [API independente de prova de vida](https://docs.didit.me/pt/standalone-apis/passive-liveness.md).

> [!NOTE]
>
> Leia `response.liveness_checks[0]` e itere o array — a estrutura singular `liveness` referida em alguns tutoriais mais antigos não existe no endpoint de decisão 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#verificação-de-prova-de-vida). Os campos abaixo refletem esse esquema canónico.

| Campo | Tipo | Descrição |
| - | - | - |
| `status` | `"Approved" \| "Declined" \| "In Review" \| "Not Finished" \| "Resub Requested"` | Estado do passo de prova de vida (ver abaixo). |
| `node_id` | string \| null | Nó do grafo do fluxo que gerou este relatório. |
| `method` | `"ACTIVE_3D" \| "FLASHING" \| "PASSIVE"` | O método de prova de vida que gerou esta captura. |
| `score` | number 0–100 \| null | Pontuação de confiança da prova de vida, arredondada a 2 casas decimais. |
| `reference_image` | string (URL assinado) \| null | Selfie de referência extraída da captura. URL assinado com uma janela de validade limitada. |
| `video_url` | string (URL assinado) \| null | Vídeo completo da captura de prova de vida (métodos ativos). URL assinado com uma janela de validade limitada. |
| `age_estimation` | number \| null | Idade estimada em anos do maior rosto presente na imagem de referência. |
| `face_quality` | number 0–100 \| null | Qualidade facial da prova de vida passiva, normalizada para uma percentagem. Preenchida apenas quando `method = "PASSIVE"`. |
| `face_luminance` | number 0–100 \| null | Luminância facial da prova de vida passiva, normalizada de 0–255 para uma percentagem. Preenchida apenas quando `method = "PASSIVE"`. |
| `matches[]` | array | Correspondências faciais entre sessões (ver abaixo). |
| `warnings[]` | array | Avisos ao nível do módulo — consulte [Avisos de prova de vida](https://docs.didit.me/pt/core-technology/liveness/warnings-liveness.md). Cada entrada segue a estrutura do [Objeto de aviso](https://docs.didit.me/pt/reference/data-models.md#objeto-de-aviso) (`feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`). |

### Correspondências faciais entre sessões

O campo `matches[]` lista os rostos no histórico da sua aplicação que excederam o limiar de semelhança biométrica face a esta selfie — até 5 entradas, com rostos na lista de bloqueio e na lista de permissões primeiro, seguidos por ordem decrescente de semelhança. Os candidatos elegíveis são rostos na lista de bloqueio, rostos na lista de permissões, rostos de sessões com `Approved` e rostos importados associados aos seus utilizadores do fornecedor. Os rostos pertencentes ao mesmo utilizador (mesmo `vendor_data`, ou o mesmo utilizador do fornecedor quando disponível) são excluídos de **toda** a pesquisa — tanto da deteção de duplicados como da triagem de lista de bloqueio.

Cada entrada inclui:

| Campo | Tipo | Descrição |
| - | - | - |
| `session_id` | string (UUID) \| null | A sessão correspondente. `null` quando `source` é `imported` ou `list_entry`. |
| `session_number` | number \| null | Número sequencial da sessão para a sessão correspondente. `null` para origens que não sejam sessões. |
| `similarity_percentage` | number 0–100 | Pontuação de semelhança biométrica, limitada a 0–100. |
| `vendor_data` | string \| null | Os seus dados de referência da sessão correspondente (ou utilizador do fornecedor, para rostos importados). |
| `verification_date` | string (ISO 8601) \| null | Quando a sessão correspondente (ou o rosto importado) foi criada. |
| `user_details` | object \| null | `{ full_name, document_type, document_number }` do KYC da sessão correspondente. Rostos importados preenchem apenas `full_name` (os dois campos de documento são `null`); `null` quando não existem detalhes registados. |
| `match_image_url` | string (URL assinado) \| null | Rosto de referência da sessão correspondente, rosto importado ou entrada de lista. |
| `status` | string \| null | Estado da sessão correspondente (por exemplo, `"Approved"`). `null` para origens que não sejam sessões. |
| `is_blocklisted` | boolean | `true` quando o rosto correspondente está na sua lista de bloqueio de rostos. |
| `is_allowlisted` | boolean | `true` quando o rosto correspondente está na sua lista de permissões de rostos (as ações de rostos duplicados são ignoradas). |
| `api_service` | string \| null | Definido quando o rosto correspondente teve origem numa chamada autónoma à API (por exemplo, `"PASSIVE_LIVENESS"`); `null` para sessões de fluxo e origens que não sejam sessões. |
| `source` | `"session" \| "imported" \| "list_entry"` | Origem do rosto correspondente: outra sessão de verificação, um rosto carregado associado a um utilizador do fornecedor ou um rosto de lista de permissão/bloqueio gerida pela organização. |

## Valores de estado

Os estados são provenientes do enum partilhado de estados de funcionalidades (`FeatureStatusChoices`).

| Estado | Significado | Efeito a jusante |
| - | - | - |
| `Approved` | Rosto detetado, pontuação de prova de vida acima do limiar de revisão, nenhum aviso de recusa automática acionado. | Conta como uma verificação de prova de vida bem-sucedida. |
| `In Review` | Pontuação igual ou abaixo do limiar de revisão mas acima do limiar de recusa, ou foi acionado um aviso encaminhado para revisão. | A sessão também passa para `In Review` até que um revisor intervenha. |
| `Declined` | Foi acionado um risco de recusa automática (`NO_FACE_DETECTED`, `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST` ou os riscos de idade em fluxos de estimativa de idade), um aviso configurável foi encaminhado para recusa ou a pontuação é igual ou inferior ao limiar de recusa. | A sessão é recusada, a menos que outra ramificação aprovada satisfaça o fluxo. |
| `Not Finished` | O utilizador abandonou o passo de prova de vida (ou uma falha de captura passível de nova tentativa está a aguardar outra tentativa). | A ramificação de prova de vida não produziu um resultado. |
| `Resub Requested` | Um revisor solicitou o reenvio deste passo a partir da consola. | Transitório — substituído assim que o utilizador efetuar uma nova captura. |

## Exemplos

### Approved — captura 3D ativa limpa

```json theme={null}
{
  "liveness_checks": [
    {
      "status": "Approved",
      "node_id": "liveness_primary",
      "method": "ACTIVE_3D",
      "score": 92.4,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": "https://<media-host>/.../liveness.mp4?signature=...",
      "age_estimation": 24.3,
      "face_quality": null,
      "face_luminance": null,
      "matches": [],
      "warnings": []
    }
  ]
}
```

### In Review — prova de vida passiva, captura de baixa qualidade e um possível duplicado

```json theme={null}
{
  "liveness_checks": [
    {
      "status": "In Review",
      "node_id": "liveness_primary",
      "method": "PASSIVE",
      "score": 76.1,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": null,
      "age_estimation": 31.0,
      "face_quality": 12.4,
      "face_luminance": 18.7,
      "matches": [
        {
          "session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
          "session_number": 123,
          "similarity_percentage": 96.8,
          "vendor_data": "user-555",
          "verification_date": "2024-07-15T10:23:45Z",
          "user_details": {
            "full_name": "John Smith",
            "document_type": "Passport",
            "document_number": "SAMPLE-DOC-12345"
          },
          "match_image_url": "https://<media-host>/.../matched.jpg?signature=...",
          "status": "Approved",
          "is_blocklisted": false,
          "is_allowlisted": false,
          "api_service": null,
          "source": "session"
        }
      ],
      "warnings": [
        {
          "feature": "LIVENESS",
          "risk": "LOW_FACE_QUALITY",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face quality",
          "long_description": "The facial image quality is below the acceptable threshold, which may affect the reliability of liveness detection. This could be due to camera resolution, focus, or compression artifacts.",
          "node_id": "liveness_primary"
        },
        {
          "feature": "LIVENESS",
          "risk": "LOW_FACE_LUMINANCE",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face luminance",
          "long_description": "The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended.",
          "node_id": "liveness_primary"
        },
        {
          "feature": "LIVENESS",
          "risk": "POSSIBLE_DUPLICATED_FACE",
          "additional_data": {
            "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
            "duplicated_session_number": 123,
            "api_service": null
          },
          "log_type": "warning",
          "short_description": "Possible duplicated face from other approved session",
          "long_description": "The system identified a possible duplicate face from another approved session, requiring further investigation.",
          "node_id": "liveness_primary"
        }
      ]
    }
  ]
}
```

Aqui, a qualidade facial (12.4) situa-se abaixo do limiar de revisão predefinido (15), a luminância (18.7) situa-se abaixo do mínimo predefinido (20) e a ação de rosto duplicado do fluxo está configurada para Revisão — pelo que todos os três avisos apresentam `log_type: "warning"` e o relatório é resolvido com `In Review`.

## Nota de segurança

Os vídeos e as selfies de prova de vida constituem dados biométricos — os URLs assinados são temporários e expiram (após 4 horas por predefinição). Trate-os como de curta duração: não os guarde em cache nem os exponha publicamente. Normalmente, a sua aplicação necessita apenas de `status`, `score` e dos avisos — armazene o mínimo possível para minimizar os dados biométricos nos seus servidores.

## Relacionados

* [Avisos de prova de vida](https://docs.didit.me/pt/core-technology/liveness/warnings-liveness.md) — enum completo de avisos, causas e resolução.
* [Webhooks](https://docs.didit.me/pt/integration/webhooks.md) — monitorize `session.status.updated` para receber o relatório.
* [Modelos de dados — Verificação de prova de vida](https://docs.didit.me/pt/reference/data-models.md#verificação-de-prova-de-vida) — esquema canónico com todos os campos.
* [Relatório de correspondência facial](https://docs.didit.me/pt/core-technology/face-match/report-face-match.md) — a correspondência facial 1:1 complementar com o retrato do documento.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.