Relatório de liveness: score, método e correspondências

Visão geral

O relatório de prova de vida registra tudo o que a Didit observou ao verificar que havia uma pessoa real e viva diante da câmera, e não uma foto impressa, uma reprodução de tela ou um deepfake. Ele 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 da captura, uma estimativa de idade opcional, métricas de qualidade da prova de vida passiva e correspondências faciais entre sessões em relação ao histórico e à lista de bloqueio da sua aplicação. O relatório é gerado depois que o usuário conclui a etapa de prova de vida em um fluxo de verificação (workflow) ou chama o endpoint facial independente. A Didit executa um dos três métodos de prova de vida (3D ativo, flashing ou passivo), atribui uma pontuação à captura, procura padrões de spoofing conhecidos e compara biometricamente o rosto com todos os outros rostos já vistos na sua aplicação. Cada relatório tem seu próprio status, independente do status geral da sessão, que reflete apenas o resultado da etapa de prova de vida:

Aprovado: rosto detectado, pontuação de prova de vida acima do limiar de revisão e nenhum aviso de recusa automática disparado.
Em Revisão: um ou mais avisos encaminhados para revisão foram disparados, ou a pontuação está igual ou abaixo do limiar de revisão, mas acima do limiar de recusa.
Recusado: uma condição de recusa automática foi disparada (NO_FACE_DETECTED, LIVENESS_FACE_ATTACK, FACE_IN_BLOCKLIST ou os riscos de idade em fluxos de estimativa de idade), um aviso configurável encaminhado para recusa foi disparado, ou a pontuação está igual ou abaixo do limiar de recusa.
Não concluído: o usuário nunca concluiu a etapa de prova de vida.

Onde aparece nas respostas da API

O relatório de prova de vida aparece como liveness_checks[] em GET /v3/session/{sessionId}/decision/. É sempre um array JSON, nunca um objeto liveness singular. Várias entradas aparecem 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/ retorna liveness_checks[] no nível superior. Consulte Obter a decisão da sessão.
Webhooks: os payloads de session.status.updated incluem o mesmo array liveness_checks[] assim que a etapa gera dados. Consulte Webhooks.
API independente de prova de vida: consulte API independente de prova de vida.

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

Schema

O schema canônico, campo a campo, está na página de referência Modelos de dados. Os campos abaixo espelham esse schema canônico.

Campo	Tipo	Descrição
`status`	`"Approved" \| "Declined" \| "In Review" \| "Not Finished" \| "Resub Requested"`	Status da etapa de prova de vida (veja abaixo).
`node_id`	string \| null	Nó do grafo do fluxo de verificação (workflow) 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 para 2 casas decimais.
`reference_image`	string (URL assinada) \| null	Selfie de referência extraída da captura. URL assinada com janela de validade limitada.
`video_url`	string (URL assinada) \| null	Vídeo completo da captura de prova de vida (métodos ativos). URL assinada com janela de validade limitada.
`age_estimation`	number \| null	Idade estimada, em anos, do maior rosto na imagem de referência.
`face_quality`	number 0–100 \| null	Qualidade do rosto na prova de vida passiva, normalizada para uma porcentagem. Preenchido apenas quando `method = "PASSIVE"`.
`face_luminance`	number 0–100 \| null	Luminância facial na prova de vida passiva, normalizada de 0–255 para uma porcentagem. Preenchido apenas quando `method = "PASSIVE"`.
`matches[]`	array	Correspondências faciais entre sessões (veja abaixo).
`warnings[]`	array	Avisos do módulo: veja Avisos de prova de vida. Cada item segue o formato do objeto Warning (`feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`).

Correspondências faciais entre sessões

matches[] lista os rostos do histórico da sua aplicação que ultrapassaram o limiar de similaridade biométrica em relação a esta selfie: até 5 itens, primeiro os rostos na lista de bloqueio e na lista de permissões, depois em ordem decrescente de similaridade. São candidatos elegíveis os rostos na lista de bloqueio, os rostos na lista de permissões, os rostos de sessões Approved e os rostos importados para os seus usuários do fornecedor (vendor users). Os rostos que pertencem ao mesmo usuário (mesmo vendor_data ou, quando disponível, o mesmo usuário do fornecedor) são excluídos de toda a busca: tanto da detecção de duplicatas quanto da verificação na lista de bloqueio. Cada item 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 correspondente. `null` para origens que não são sessões.
`similarity_percentage`	number 0–100	Pontuação de similaridade biométrica, limitada ao intervalo 0–100.
`vendor_data`	string \| null	Seus dados de referência da sessão correspondente (ou do usuário do fornecedor, no caso de 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 há dados registrados.
`match_image_url`	string (URL assinada) \| null	Rosto de referência da sessão correspondente, do rosto importado ou do item da lista.
`status`	string \| null	Status da sessão correspondente (por exemplo, `"Approved"`). `null` para origens que não são 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 para rosto duplicado são ignoradas).
`api_service`	string \| null	Definido quando o rosto correspondente veio de uma chamada de API avulsa (por exemplo, `"PASSIVE_LIVENESS"`); `null` para sessões de fluxo e origens que não são sessões.
`source`	`"session" \| "imported" \| "list_entry"`	De onde veio o rosto correspondente: outra sessão de verificação, um rosto enviado para um usuário do fornecedor ou um rosto de uma lista de permissões/bloqueio gerenciada pela organização.

Valores de status

Os status vêm do enum compartilhado de status de recursos (FeatureStatusChoices).

Status	Significado	Efeito posterior
`Approved`	Rosto detectado, pontuação de prova de vida acima do limiar de revisão e nenhum aviso de recusa automática disparado.	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 um aviso direcionado para revisão foi disparado.	A sessão também passa para `In Review` até que um revisor aja.
`Declined`	Um risco de recusa automática foi acionado (`NO_FACE_DETECTED`, `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST` ou os riscos de idade em fluxos com estimativa de idade), um aviso configurável foi direcionado para recusa ou a pontuação está igual ou abaixo do limiar de recusa.	A sessão é recusada, a menos que outra ramificação aprovada satisfaça as condições do fluxo.
`Not Finished`	O usuário abandonou a etapa de prova de vida (ou uma falha de captura que permite nova tentativa aguarda outra tentativa).	A ramificação de prova de vida não produziu resultado.
`Resub Requested`	Um revisor solicitou, pelo console, o reenvio desta etapa.	Temporário: é substituído assim que o usuário refaz a captura.

Exemplos

Approved: captura 3D ativa sem problemas

{
  "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 possível duplicata

{
  "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) está abaixo do limiar de revisão padrão (15), a luminância (18.7) está abaixo do mínimo padrão (20) e a ação do fluxo de trabalho para faces duplicadas está definida como Review; por isso, os três avisos têm log_type: "warning" e o relatório é definido como In Review.

Nota de segurança

Vídeos e selfies de prova de vida são dados biométricos: as URLs assinadas são temporárias e expiram (após 4 horas, por padrão). Considere-as de curta duração: não as armazene em cache nem as exponha publicamente. Normalmente, sua aplicação precisa apenas de status, score e dos avisos; armazene o mínimo possível para reduzir os dados biométricos nos seus servidores.

Relacionados

Avisos de prova de vida: enum completo de avisos, causas e como corrigi-los.
Webhooks: escute session.status.updated para receber o relatório.
Modelos de dados: verificação de prova de vida: schema 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

Monitoramento

Plataforma

Relatório de liveness: score, método e correspondências

Visão geral

Onde aparece nas respostas da API

Schema

Correspondências faciais entre sessões

Valores de status

Exemplos

Approved: captura 3D ativa sem problemas

In Review: prova de vida passiva, captura de baixa qualidade e possível duplicata

Nota de segurança

Relacionados

​Visão geral

​Onde aparece nas respostas da API

​Schema

​Correspondências faciais entre sessões

​Valores de status

​Exemplos

​Approved: captura 3D ativa sem problemas

​In Review: prova de vida passiva, captura de baixa qualidade e possível duplicata

​Nota de segurança

​Relacionados

Visão geral

Onde aparece nas respostas da API

Schema

Correspondências faciais entre sessões

Valores de status

Exemplos

Approved: captura 3D ativa sem problemas

In Review: prova de vida passiva, captura de baixa qualidade e possível duplicata

Nota de segurança

Relacionados