> ## 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. # Autenticação biométrica: avisos e códigos > Trate avisos de autenticação biométrica no Didit: ataques faciais, LOW_LIVENESS_SCORE e listas de bloqueio. Defina limiares e ações de recusa. A Autenticação biométrica combina uma verificação de prova de vida com uma correspondência facial 1:1 opcional em relação à face de referência resolvida na criação da sessão (a `portrait_image` fornecida ou a face guardada do utilizador consultada através de `vendor_data`). Cada passo emite os seus próprios avisos no payload de decisão V3. Esta página lista cada código, onde surge e como os limiares se traduzem num estado final da sessão. ## Visão geral Quando uma sessão de autenticação biométrica é executada, a Didit: * Captura uma selfie em direto através de 3D Action, Flash ou Prova de vida passiva (`method`: `ACTIVE_3D`, `FLASHING` ou `PASSIVE`). * Extrai a maior face da captura e calcula a pontuação da sua prova de vida. * Se o fluxo de verificação incluir Correspondência facial, compara a face capturada com a face de referência da sessão (`portrait_image` fornecida ou a face guardada do utilizador). * Regista o resultado de cada passo, juntamente com eventuais avisos, na decisão da sessão. Os avisos mantêm a estrutura partilhada do [objeto de aviso](https://docs.didit.me/pt/reference/data-models.md#objeto-de-aviso) utilizada em toda a plataforma: `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description` e `node_id`. ## Onde surgem os avisos | Chave da resposta de decisão | Tag de funcionalidade no aviso | Quando é acionado | | - | - | - | | `liveness_checks[].warnings[]` | `LIVENESS` | Pontuação de prova de vida, qualidade da face, luminância, múltiplas faces e verificações de lista de bloqueio / lista de permissões / faces duplicadas. | | `face_matches[].warnings[]` | `FACEMATCH` | Correspondência facial em relação à face de referência da sessão (`portrait_image` fornecida ou a face guardada do utilizador). | Numa sessão típica de autenticação biométrica existe um elemento em cada array. Em fluxos com múltiplas instâncias, o `node_id` em cada aviso permite distinguir qual o passo que o gerou. ## Condições de recusa automática Os seguintes avisos recusam sempre o respetivo passo (`log_type: "error"`), independentemente de como configurou o fluxo: | Risco | Funcionalidade | Motivo da recusa automática | | - | - | - | | `FACE_IN_BLOCKLIST` | `LIVENESS` | A face correspondeu a uma entrada na sua lista de bloqueio de faces. | | `NO_FACE_DETECTED` | `LIVENESS` | Nenhuma face foi localizada durante a captura de prova de vida, ou o utilizador esgotou as tentativas de captura. | | `LIVENESS_FACE_ATTACK` | `LIVENESS` | Foi detetado um ataque de apresentação (máscara, reprodução em ecrã, spoofing do tipo deepfake). | | `NO_REFERENCE_IMAGE` | `FACEMATCH` | Não estava disponível nenhuma imagem de referência para realizar a comparação. Quando este aviso é acionado, `LOW_FACE_MATCH_SIMILARITY` é suprimido. | Quando `NO_FACE_DETECTED` é acionado, `LOW_LIVENESS_SCORE` é suprimido (não existe qualquer face para pontuar). ## Limiares e ações configuráveis Estes avisos são pontuados e depois associados a um estado através de limiares e ações que define por fluxo: | Risco | Funcionalidade | Comportamento configurável | | - | - | - | | `LOW_LIVENESS_SCORE` | `LIVENESS` | Pontuação igual ou inferior ao limiar de revisão → `In Review`; igual ou inferior ao limiar de recusa → `Declined`. | | `LOW_FACE_MATCH_SIMILARITY` | `FACEMATCH` | Pontuação igual ou inferior ao limiar de revisão (predefinição 70) → `In Review`; igual ou inferior ao limiar de recusa (predefinição 50) → `Declined`. | | `LOW_FACE_QUALITY` | `LIVENESS` | Limiar de revisão (predefinição 15) → `In Review`; limiar de recusa (predefinição 0, ou seja, recusa desativada) → `Declined`. Apenas Prova de vida passiva. | | `LOW_FACE_LUMINANCE` | `LIVENESS` | Abaixo do limiar mínimo de luminância (predefinição 20): Nenhuma ação / Revisão (predefinição) / Recusa. Apenas Prova de vida passiva. | | `HIGH_FACE_LUMINANCE` | `LIVENESS` | Acima do limiar máximo de luminância (predefinição 80): Nenhuma ação / Revisão (predefinição) / Recusa. Apenas Prova de vida passiva. | | `MULTIPLE_FACES_DETECTED` | `LIVENESS` | Nenhuma ação (predefinição) / Revisão / Recusa quando é capturada mais de uma face. Apenas Prova de vida passiva. | | `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` | `LIVENESS` | Uma ação partilhada para faces duplicadas: Nenhuma ação (predefinição) / Revisão / Recusa para correspondências com faces aprovadas ou importadas de outros utilizadores. | | `DUPLICATED_FACE_NAME_MISMATCH` | `LIVENESS` | Ação específica (`face_liveness_duplicated_face_name_mismatch_action`): Nenhuma ação / Revisão (predefinição) / Recusa. Emitido juntamente com `DUPLICATED_FACE` quando a identidade da sessão correspondente não coincide com o nome resolvido desta sessão — consulte [Avisos de prova de vida](https://docs.didit.me/pt/core-technology/liveness/warnings-liveness.md#correspondência-facial-entre-sessões). | `POSSIBLE_FACE_IN_BLOCKLIST` (`LIVENESS`) **não** é configurável — uma correspondência de menor confiança com a lista de bloqueio é sempre encaminhada para Revisão (`log_type: "warning"`). ## Novas tentativas de captura As falhas causadas apenas por riscos corrigíveis de qualidade de captura (pontuação baixa, ausência de face, qualidade, luminância, múltiplas faces — e baixa similaridade na correspondência facial) entram num ciclo de repetição antes de o estado se tornar definitivo: o utilizador obtém até um total de `face_liveness_max_attempts` / `face_match_max_attempts` tentativas (predefinição: 3; configurável entre 2 e 5 por nó do fluxo). Quando o limite de tentativas é esgotado, aplica-se o estado calculado da última tentativa e `LIVENESS_MAX_ATTEMPTS_EXCEEDED` ou `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` é registado como `information` para o registar. ## Avisos de prova de vida A API devolve exatamente estas strings de `short_description` e `long_description`: | `risk` | `short_description` | `long_description` | | - | - | - | | `LOW_LIVENESS_SCORE` | Low liveness score | The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data. | | `NO_FACE_DETECTED` | No Face Detected in liveness | The system couldn't identify a face during the liveness check, which may be due to poor image quality, improper positioning, or technical issues. | | `LIVENESS_FACE_ATTACK` | Liveness Face Attack | The system detected a potential attempt to bypass the liveness check. | | `FACE_IN_BLOCKLIST` | Face in blocklist | The system identified a face in the blocklist, which means the face is not allowed to be verified. | | `POSSIBLE_FACE_IN_BLOCKLIST` | Possible face in blocklist | The system identified a possible face in the blocklist, which means the face is not allowed to be verified. | | `FACE_IN_ALLOWLIST` | Face in allowlist | The face matched the application's face allowlist, so duplicate-face actions were skipped for this signal. | | `POSSIBLE_FACE_IN_ALLOWLIST` | Possible face in allowlist | The face possibly matched the application's face allowlist, so possible duplicate-face actions were skipped for this signal. | | `DUPLICATED_FACE` | Duplicated face from other approved session | The system identified a duplicated face from another approved session, requiring further investigation. | | `POSSIBLE_DUPLICATED_FACE` | Possible duplicated face from other approved session | The system identified a possible duplicate face from another approved session, requiring further investigation. | | `DUPLICATED_FACE_NAME_MISMATCH` | Duplicated face under a different name | The same face was already approved on another session, but under a different name. The identity behind the duplicate does not match the identity declared on this session, which is a strong indicator of identity fraud. | | `MULTIPLE_FACES_DETECTED` *(Apenas passiva)* | Multiple faces detected | Multiple faces were detected in the liveness image. The system uses the largest face for liveness verification and face comparison, but the presence of multiple faces may require additional review. | | `LOW_FACE_QUALITY` *(Apenas passiva)* | Low face quality | 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. | | `LOW_FACE_LUMINANCE` *(Apenas passiva)* | Low face luminance | The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended. | | `HIGH_FACE_LUMINANCE` *(Apenas passiva)* | High face luminance | The facial image is too bright or overexposed, which may affect the accuracy of liveness detection. Reduced lighting or avoiding direct light is recommended. | | `LIVENESS_MAX_ATTEMPTS_EXCEEDED` | Maximum liveness attempts exceeded | The maximum number of liveness capture attempts has been reached. The last attempt's computed status (decline or review) has been applied. | Correspondências na lista de bloqueio, lista de permissões e duplicados incluem `additional_data` com a sessão correspondente (`blocklisted_session_id` / `allowlisted_session_id` / `duplicated_session_id`, o respetivo `*_session_number` e `api_service`). Apenas um desses seis códigos surge por relatório. `DUPLICATED_FACE_NAME_MISMATCH` é a exceção: é emitido **em conjunto com** `DUPLICATED_FACE`, nunca em sua substituição, quando a identidade da sessão correspondente não coincide com o nome resolvido desta sessão. O respetivo `additional_data` adiciona `name_match_score` aos mesmos campos da sessão duplicada. Um nome escrito num sistema de escrita diferente em cada lado não é considerado uma divergência quando os documentos de identificação de ambas as sessões partilham o mesmo estado emissor, um número de documento ou número de identificação pessoal exato e uma data de nascimento sem contradições. Consulte [Avisos de prova de vida](https://docs.didit.me/pt/core-technology/liveness/warnings-liveness.md#correspondência-facial-entre-sessões). ## Avisos de correspondência facial | `risk` | `short_description` | `long_description` | | - | - | - | | `LOW_FACE_MATCH_SIMILARITY` | Low face match similarity | The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch. | | `NO_REFERENCE_IMAGE` | No source image found for performing face match | A reference image for facial comparison is missing, preventing the system from completing the face matching process. | | `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` | Maximum face match attempts exceeded | The maximum number of face match capture attempts has been reached. The last attempt's computed status (decline or review) has been applied. | ## Exemplo — recusada por ataque facial ```json theme={null} { "liveness_checks": [ { "node_id": "feature_liveness", "status": "Declined", "method": "ACTIVE_3D", "score": 12.40, "reference_image": "https:///.../reference.jpg", "video_url": "https:///.../video.mp4", "age_estimation": null, "matches": [], "face_quality": null, "face_luminance": null, "warnings": [ { "feature": "LIVENESS", "risk": "LIVENESS_FACE_ATTACK", "additional_data": null, "log_type": "error", "short_description": "Liveness Face Attack", "long_description": "The system detected a potential attempt to bypass the liveness check.", "node_id": "feature_liveness" } ] } ], "face_matches": null } ``` ## Exemplo — em análise por baixa similaridade ```json theme={null} { "face_matches": [ { "node_id": "feature_face_match", "status": "In Review", "score": 58.70, "source_image_session_id": "11111111-2222-3333-4444-555555555555", "source_image": "https:///.../source.jpg", "target_image": "https:///.../target.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" } ] } ] } ``` A pontuação (58.70) situa-se entre o limiar de recusa (por defeito 50) e o limiar de revisão (por defeito 70), pelo que o aviso inclui `log_type: "warning"` e o estado da correspondência facial é `In Review`. Neste exemplo, o aviso disparou numa sessão cujo `session_id` é `11111111-2222-3333-4444-555555555555` — `source_image_session_id` inclui o próprio id da sessão porque a referência teve origem no retrato guardado no momento da criação da sessão. ## Tipos de aviso A cada risco é atribuído um tipo de aviso com base na configuração da sua aplicação. Os avisos dividem-se em três categorias de gravidade: ## Conteúdo relacionado > [card] [Relatório de Autenticação Biométrica](https://docs.didit.me/pt/core-technology/biometric-auth/report-biometric-authentication.md) > > Onde `liveness_checks[]` e `face_matches[]` surgem na decisão V3. > [card] [Avisos de prova de vida](https://docs.didit.me/pt/core-technology/liveness/warnings-liveness.md) > > Referência completa de avisos de prova de vida, incluindo correspondência de rostos duplicados. > [card] [Avisos de correspondência facial](https://docs.didit.me/pt/core-technology/face-match/warnings-face-match.md) > > Referência completa de avisos de correspondência facial para comparações 1:1. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.