> ## 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. # Avvisi dell'autenticazione biometrica e codici > Gestisci gli avvisi di autenticazione biometrica su Didit: LOW_LIVENESS_SCORE, attacchi facciali, blocklist e soglie per le azioni di rifiuto. L'Autenticazione biometrica combina un controllo di vitalità con un confronto facciale 1:1 opzionale rispetto al volto di riferimento determinato alla creazione della sessione (il `portrait_image` fornito o il volto memorizzato dell'utente cercato tramite `vendor_data`). Ogni passaggio genera i propri avvisi nel payload di decisione V3. Questa pagina elenca tutti i codici, dove compaiono e come le soglie si traducono nello stato finale della sessione. ## Panoramica Quando viene eseguita una sessione di autenticazione biometrica, Didit: * Acquisisce un selfie dal vivo utilizzando 3D Action, Flash o Passive Liveness (`method`: `ACTIVE_3D`, `FLASHING` o `PASSIVE`). * Estrae il volto più grande dall'acquisizione e ne calcola il punteggio di vitalità. * Se il workflow include il Confronto facciale, confronta il volto acquisito con il volto di riferimento della sessione (`portrait_image` fornito o il volto memorizzato dell'utente). * Scrive l'esito di ogni passaggio e gli eventuali avvisi nella decisione della sessione. Gli avvisi mantengono la struttura condivisa dell'[oggetto di avviso](https://docs.didit.me/it/reference/data-models.md#oggetto-avviso) utilizzata nell'intera piattaforma: `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description` e `node_id`. ## Dove compaiono gli avvisi | Chiave di risposta della decisione | Tag della funzionalità sull'avviso | Quando si attiva | | - | - | - | | `liveness_checks[].warnings[]` | `LIVENESS` | Calcolo del punteggio di vitalità, qualità del volto, luminosità, volti multipli e controlli su blocklist / allowlist / volti duplicati. | | `face_matches[].warnings[]` | `FACEMATCH` | Confronto facciale rispetto al volto di riferimento della sessione (`portrait_image` fornito o volto memorizzato dell'utente). | In una tipica sessione di autenticazione biometrica è presente un elemento in ciascun array. Nei workflow con più istanze, il `node_id` di ciascun avviso indica chiaramente quale passaggio lo ha generato. ## Condizioni di rifiuto automatico I seguenti avvisi determinano sempre il rifiuto del rispettivo passaggio (`log_type: "error"`), a prescindere da come hai configurato il workflow: | Rischio | Funzionalità | Motivo del rifiuto automatico | | - | - | - | | `FACE_IN_BLOCKLIST` | `LIVENESS` | Il volto corrisponde a una voce presente nella tua blocklist dei volti. | | `NO_FACE_DETECTED` | `LIVENESS` | Non è stato individuato alcun volto durante l'acquisizione della vitalità, oppure l'utente ha esaurito i tentativi aggiuntivi di acquisizione. | | `LIVENESS_FACE_ATTACK` | `LIVENESS` | È stato rilevato un attacco di presentazione (maschera, replay su schermo, spoofing di tipo deepfake). | | `NO_REFERENCE_IMAGE` | `FACEMATCH` | Non era disponibile alcuna immagine di riferimento per eseguire il confronto. Quando si attiva questo avviso, `LOW_FACE_MATCH_SIMILARITY` viene soppresso. | Quando si attiva `NO_FACE_DETECTED`, `LOW_LIVENESS_SCORE` viene soppresso (non c'è alcun volto di cui calcolare il punteggio). ## Soglie e azioni configurabili A questi avvisi viene assegnato un punteggio, mappato successivamente a uno stato tramite le soglie e le azioni impostate per ciascun workflow: | Rischio | Funzionalità | Comportamento configurabile | | - | - | - | | `LOW_LIVENESS_SCORE` | `LIVENESS` | Punteggio pari o inferiore alla soglia di revisione → `In Review`; pari o inferiore alla soglia di rifiuto → `Declined`. | | `LOW_FACE_MATCH_SIMILARITY` | `FACEMATCH` | Punteggio pari o inferiore alla soglia di revisione (predefinita 70) → `In Review`; pari o inferiore alla soglia di rifiuto (predefinita 50) → `Declined`. | | `LOW_FACE_QUALITY` | `LIVENESS` | Soglia di revisione (predefinita 15) → `In Review`; soglia di rifiuto (predefinita 0, ovvero rifiuto disabilitato) → `Declined`. Solo per Passive Liveness. | | `LOW_FACE_LUMINANCE` | `LIVENESS` | Inferiore alla soglia minima di luminosità (predefinita 20): Nessuna azione / Revisione (predefinita) / Rifiuto. Solo per Passive Liveness. | | `HIGH_FACE_LUMINANCE` | `LIVENESS` | Superiore alla soglia massima di luminosità (predefinita 80): Nessuna azione / Revisione (predefinita) / Rifiuto. Solo per Passive Liveness. | | `MULTIPLE_FACES_DETECTED` | `LIVENESS` | Nessuna azione (predefinita) / Revisione / Rifiuto quando viene acquisito più di un volto. Solo per Passive Liveness. | | `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` | `LIVENESS` | Un'unica azione condivisa per i volti duplicati: Nessuna azione (predefinita) / Revisione / Rifiuto per le corrispondenze con volti approvati o importati di altri utenti. | | `DUPLICATED_FACE_NAME_MISMATCH` | `LIVENESS` | Azione dedicata (`face_liveness_duplicated_face_name_mismatch_action`): Nessuna azione / Revisione (predefinita) / Rifiuto. Generato insieme a `DUPLICATED_FACE` quando l'identità della sessione corrispondente non coincide con il nome determinato per questa sessione — vedi [Avvisi di vitalità](https://docs.didit.me/it/core-technology/liveness/warnings-liveness.md#confronto-facciale-tra-sessioni). | `POSSIBLE_FACE_IN_BLOCKLIST` (`LIVENESS`) **non** è configurabile: una corrispondenza nella blocklist a minore affidabilità viene sempre instradata verso Revisione (`log_type: "warning"`). ## Nuovi tentativi di acquisizione I fallimenti dovuti esclusivamente a rischi risolvibili legati alla qualità dell'acquisizione (punteggio basso, nessun volto, qualità, luminosità, volti multipli — e bassa somiglianza nel confronto facciale) entrano in un ciclo di nuovi tentativi prima che lo stato diventi definitivo: l'utente ha a disposizione fino a `face_liveness_max_attempts` / `face_match_max_attempts` tentativi totali (valore predefinito 3, configurabile da 2 a 5 per nodo del workflow). Una volta esaurito il numero di tentativi, si applica lo stato calcolato dell'ultimo tentativo e viene registrato `LIVENESS_MAX_ATTEMPTS_EXCEEDED` o `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` come `information` per tenerne traccia. ## Avvisi sul rilevamento della vitalità L'API restituisce queste stringhe `short_description` e `long_description`: | `risk` | `short_description` | `long_description` | | - | - | - | | `LOW_LIVENESS_SCORE` | Punteggio di vitalità basso | Il controllo della vitalità ha prodotto un punteggio basso, indicando il potenziale utilizzo di rappresentazioni facciali non provenienti da una persona reale o dati biometrici di scarsa qualità. | | `NO_FACE_DETECTED` | Nessun volto rilevato nella vitalità | Il sistema non è riuscito a identificare un volto durante il controllo della vitalità, il che potrebbe essere dovuto a una scarsa qualità dell'immagine, a un posizionamento non corretto o a problemi tecnici. | | `LIVENESS_FACE_ATTACK` | Attacco facciale alla vitalità | Il sistema ha rilevato un potenziale tentativo di eludere il controllo della vitalità. | | `FACE_IN_BLOCKLIST` | Volto nella blocklist | Il sistema ha identificato un volto nella blocklist, il che significa che per questo volto la verifica non è consentita. | | `POSSIBLE_FACE_IN_BLOCKLIST` | Possibile volto nella blocklist | Il sistema ha identificato un possibile volto nella blocklist, il che significa che per questo volto la verifica non è consentita. | | `FACE_IN_ALLOWLIST` | Volto nella allowlist | Il volto corrisponde alla allowlist dei volti dell'applicazione, pertanto le azioni per volto duplicato sono state ignorate per questo segnale. | | `POSSIBLE_FACE_IN_ALLOWLIST` | Possibile volto nella allowlist | Il volto corrisponde probabilmente alla allowlist dei volti dell'applicazione, pertanto le azioni per possibile volto duplicato sono state ignorate per questo segnale. | | `DUPLICATED_FACE` | Volto duplicato da un'altra sessione approvata | Il sistema ha identificato un volto duplicato da un'altra sessione approvata, richiedendo ulteriori indagini. | | `POSSIBLE_DUPLICATED_FACE` | Possibile volto duplicato da un'altra sessione approvata | Il sistema ha identificato un possibile volto duplicato da un'altra sessione approvata, richiedendo ulteriori indagini. | | `DUPLICATED_FACE_NAME_MISMATCH` | Volto duplicato con un nome diverso | Lo stesso volto è già stato approvato in un'altra sessione, ma con un nome diverso. L'identità associata al duplicato non corrisponde all'identità dichiarata in questa sessione, il che rappresenta un forte indicatore di frode d'identità. | | `MULTIPLE_FACES_DETECTED` *(solo passivo)* | Rilevati più volti | Sono stati rilevati più volti nell'immagine di vitalità. Il sistema utilizza il volto più grande per la verifica della vitalità e il confronto facciale, ma la presenza di più volti potrebbe richiedere una revisione aggiuntiva. | | `LOW_FACE_QUALITY` *(solo passivo)* | Bassa qualità del volto | La qualità dell'immagine facciale è inferiore alla soglia accettabile, il che potrebbe influire sull'affidabilità del rilevamento della vitalità. Ciò potrebbe essere dovuto alla risoluzione della fotocamera, alla messa a fuoco o ad artefatti di compressione. | | `LOW_FACE_LUMINANCE` *(solo passivo)* | Bassa luminosità del volto | L'immagine facciale è troppo scura, il che potrebbe influire sulla precisione del rilevamento della vitalità. Si consigliano condizioni di illuminazione migliori. | | `HIGH_FACE_LUMINANCE` *(solo passivo)* | Elevata luminosità del volto | L'immagine facciale è troppo luminosa o sovraesposta, il che potrebbe influire sulla precisione del rilevamento della vitalità. Si consiglia di ridurre l'illuminazione o di evitare la luce diretta. | | `LIVENESS_MAX_ATTEMPTS_EXCEEDED` | Numero massimo di tentativi di vitalità superato | È stato raggiunto il numero massimo di tentativi di acquisizione della vitalità. È stato applicato lo stato calcolato dell'ultimo tentativo (rifiuto o revisione). | I riscontri con blocklist, allowlist e volti duplicati contengono `additional_data` con la sessione corrispondente (`blocklisted_session_id` / `allowlisted_session_id` / `duplicated_session_id`, il corrispondente `*_session_number` e `api_service`). Solo uno di questi sei codici appare in ciascun report. `DUPLICATED_FACE_NAME_MISMATCH` rappresenta l'eccezione: viene emesso **in aggiunta a** `DUPLICATED_FACE`, mai al suo posto, quando l'identità della sessione corrispondente non coincide con il nome risolto di questa sessione. Il suo `additional_data` aggiunge `name_match_score` agli stessi campi della sessione duplicata. Un nome scritto in un sistema di scrittura diverso su ciascun lato non viene trattato come una mancata corrispondenza quando i documenti d'identità di entrambe le sessioni condividono lo stato di emissione, un numero di documento o identificativo personale esatto e una data di nascita non contraddittoria. Consulta [Avvisi sul rilevamento della vitalità](https://docs.didit.me/it/core-technology/liveness/warnings-liveness.md#confronto-facciale-tra-sessioni). ## Avvisi sul confronto facciale | `risk` | `short_description` | `long_description` | | - | - | - | | `LOW_FACE_MATCH_SIMILARITY` | Bassa somiglianza nel confronto facciale | I tratti somatici dell'immagine fornita non corrispondono strettamente all'immagine di riferimento, suggerendo una potenziale mancata corrispondenza dell'identità. | | `NO_REFERENCE_IMAGE` | Nessuna immagine sorgente trovata per eseguire il confronto facciale | Manca un'immagine di riferimento per il confronto facciale, impedendo al sistema di completare il processo di confronto facciale. | | `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` | Numero massimo di tentativi di confronto facciale superato | È stato raggiunto il numero massimo di tentativi di acquisizione del confronto facciale. È stato applicato lo stato calcolato dell'ultimo tentativo (rifiuto o revisione). | ## Esempio — rifiutata per attacco facciale ```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 } ``` ## Esempio — in revisione per bassa somiglianza ```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" } ] } ] } ``` Il punteggio (58.70) si colloca tra la soglia di rifiuto (predefinita a 50) e la soglia di revisione (predefinita a 70), quindi l'avviso riporta `log_type: "warning"` e lo stato del confronto facciale è `In Review`. In questo esempio l'avviso è scattato su una sessione il cui `session_id` è `11111111-2222-3333-4444-555555555555` — `source_image_session_id` riporta l'ID stesso della sessione perché il riferimento proviene dal ritratto salvato al momento della creazione della sessione. ## Tipi di avviso A ciascun rischio viene assegnato un tipo di avviso in base alla configurazione della tua applicazione. Gli avvisi rientrano in tre categorie di gravità: ## Correlati > [card] [Report di autenticazione biometrica](https://docs.didit.me/it/core-technology/biometric-auth/report-biometric-authentication.md) > > Dove compaiono `liveness_checks[]` e `face_matches[]` nella decisione V3. > [card] [Avvisi sul rilevamento della vitalità](https://docs.didit.me/it/core-technology/liveness/warnings-liveness.md) > > Riferimento completo agli avvisi di vitalità, inclusa la corrispondenza dei volti duplicati. > [card] [Avvisi sul confronto facciale](https://docs.didit.me/it/core-technology/face-match/warnings-face-match.md) > > Riferimento completo agli avvisi di confronto facciale per i confronti 1:1. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.