Relatório de prova de vida: pontuação e correspondências

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.
Webhooks — os payloads de session.status.updated incluem o mesmo array liveness_checks[] assim que o passo tiver produzido dados. Consulte Webhooks.
API independente de prova de vida — consulte API independente de prova de vida.

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. 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. Cada entrada segue a estrutura do 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

{
  "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

{
  "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 — enum completo de avisos, causas e resolução.
Webhooks — monitorize session.status.updated para receber o relatório.
Modelos de dados — Verificação de prova de vida — esquema canónico com todos os campos.
Relatório de correspondência facial — a correspondência facial 1:1 complementar com o retrato do documento.

Autenticação

Verificação

Monitorização

Plataforma

Relatório de prova de vida: pontuação e correspondências

Visão geral

Onde surge nas respostas da API

Esquema

Correspondências faciais entre sessões

Valores de estado

Exemplos

Approved — captura 3D ativa limpa

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

Nota de segurança

Relacionados

​Visão geral

​Onde surge nas respostas da API

​Esquema

​Correspondências faciais entre sessões

​Valores de estado

​Exemplos

​Approved — captura 3D ativa limpa

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

​Nota de segurança

​Relacionados

Visão geral

Onde surge nas respostas da API

Esquema

Correspondências faciais entre sessões

Valores de estado

Exemplos

Approved — captura 3D ativa limpa

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

Nota de segurança

Relacionados