Avvisi dell'autenticazione biometrica e codici

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 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à.

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à.

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

{
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Declined",
      "method": "ACTIVE_3D",
      "score": 12.40,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../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

{
  "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://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../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

Report di autenticazione biometrica

Dove compaiono liveness_checks[] e face_matches[] nella decisione V3.

Avvisi sul rilevamento della vitalità

Riferimento completo agli avvisi di vitalità, inclusa la corrispondenza dei volti duplicati.

Avvisi sul confronto facciale

Riferimento completo agli avvisi di confronto facciale per i confronti 1:1.

Autenticazione

Verifica

Monitoraggio

Piattaforma

Avvisi dell'autenticazione biometrica e codici

Panoramica

Dove compaiono gli avvisi

Condizioni di rifiuto automatico

Soglie e azioni configurabili

Nuovi tentativi di acquisizione

Avvisi sul rilevamento della vitalità

Avvisi sul confronto facciale

Esempio — rifiutata per attacco facciale

Esempio — in revisione per bassa somiglianza

Tipi di avviso

Correlati

Report di autenticazione biometrica

Avvisi sul rilevamento della vitalità

Avvisi sul confronto facciale

​Panoramica

​Dove compaiono gli avvisi

​Condizioni di rifiuto automatico

​Soglie e azioni configurabili

​Nuovi tentativi di acquisizione

​Avvisi sul rilevamento della vitalità

​Avvisi sul confronto facciale

​Esempio — rifiutata per attacco facciale

​Esempio — in revisione per bassa somiglianza

​Tipi di avviso

​Correlati

Report di autenticazione biometrica

Avvisi sul rilevamento della vitalità

Avvisi sul confronto facciale

Panoramica

Dove compaiono gli avvisi

Condizioni di rifiuto automatico

Soglie e azioni configurabili

Nuovi tentativi di acquisizione

Avvisi sul rilevamento della vitalità

Avvisi sul confronto facciale

Esempio — rifiutata per attacco facciale

Esempio — in revisione per bassa somiglianza

Tipi di avviso

Correlati