> ## 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 liveness: score, método e correspondências > Relatório de liveness da Didit: status, pontuação de confiança, método, estimativa de idade, correspondências faciais e onde aparece na API. ## 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](https://docs.didit.me/pt-br/sessions-api/retrieve-session.md). * **Webhooks**: os payloads de `session.status.updated` incluem o mesmo array `liveness_checks[]` assim que a etapa gera dados. Consulte [Webhooks](https://docs.didit.me/pt-br/integration/webhooks.md). * **API independente de prova de vida**: consulte [API independente de prova de vida](https://docs.didit.me/pt-br/standalone-apis/passive-liveness.md). > [!NOTE] > > 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](https://docs.didit.me/pt-br/reference/data-models.md#verificação-de-prova-de-vida). 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](https://docs.didit.me/pt-br/core-technology/liveness/warnings-liveness.md). Cada item segue o formato do [objeto Warning](https://docs.didit.me/pt-br/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 `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 ```json theme={null} { "liveness_checks": [ { "status": "Approved", "node_id": "liveness_primary", "method": "ACTIVE_3D", "score": 92.4, "reference_image": "https:///.../reference.jpg?signature=...", "video_url": "https:///.../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 ```json theme={null} { "liveness_checks": [ { "status": "In Review", "node_id": "liveness_primary", "method": "PASSIVE", "score": 76.1, "reference_image": "https:///.../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:///.../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](https://docs.didit.me/pt-br/core-technology/liveness/warnings-liveness.md): enum completo de avisos, causas e como corrigi-los. * [Webhooks](https://docs.didit.me/pt-br/integration/webhooks.md): escute `session.status.updated` para receber o relatório. * [Modelos de dados: verificação de prova de vida](https://docs.didit.me/pt-br/reference/data-models.md#verificação-de-prova-de-vida): schema canônico com todos os campos. * [Relatório de correspondência facial](https://docs.didit.me/pt-br/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.