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

# Rilevamento della vitalità: avvisi e codici di errore

> Tutti gli avvisi del rilevamento della vitalità di Didit: attacchi facciali, punteggi bassi, blocklist e volti duplicati, con cause e soluzioni.

## Panoramica

Gli avvisi nel report di rilevamento della vitalità segnalano ogni condizione rilevata da Didit durante l'esecuzione del controllo di vitalità. Vengono inseriti nell'array `warnings[]` di ogni elemento di `liveness_checks[]` (vedi [Report di rilevamento della vitalità](https://docs.didit.me/it/core-technology/liveness/report-liveness.md)), con `feature` impostato su `"LIVENESS"`. Ogni voce segue la struttura condivisa dell'[oggetto avviso](https://docs.didit.me/it/reference/data-models.md#oggetto-avviso): `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`.

Ogni avviso è composto da tre livelli:

1. **Il codice `risk`** — un identificatore stabile che puoi verificare nel tuo codice (i codici sono elencati di seguito).
2. **Il `log_type`** — uno tra `information`, `warning` o `error`. I rischi di rifiuto automatico presentano sempre `error`. Per i rischi configurabili viene ricavato dall'azione configurata: **Nessuna azione** → `information`, **Revisione** → `warning`, **Rifiuta** → `error`. Per i rischi basati su soglie (`LOW_LIVENESS_SCORE`, `LOW_FACE_QUALITY`) è `error` quando il valore raggiunge o scende al di sotto della soglia di rifiuto e `warning` quando raggiunge o scende al di sotto solo della soglia di revisione.
3. **L'impatto sulla decisione** — lo stesso routing determina lo `status` del report di rilevamento della vitalità: un'azione Revisione lo sposta su `In Review`, un'azione Rifiuta (o qualsiasi rischio di rifiuto automatico) su `Declined`, mentre Nessuna azione lo lascia invariato.

Alcuni rischi vengono emessi solo quando il metodo di rilevamento della vitalità è `PASSIVE` (controlli su volti multipli, qualità e luminanza). Le tabelle seguenti elencano la serie completa di codici di rischio di vitalità e i relativi livelli di gravità — non esistono altri codici di rischio per la vitalità.

## Condizioni di rifiuto automatico

I seguenti rischi impostano sempre il report di rilevamento della vitalità (e la sessione) su `Declined`, con `log_type: "error"`:

| Risk | Trigger |
| - | - |
| `NO_FACE_DETECTED` | Nessun volto individuato durante l'acquisizione della vitalità, oppure l'utente ha esaurito i tentativi disponibili. |
| `LIVENESS_FACE_ATTACK` | Il modello ha rilevato un attacco di presentazione (maschera, riproduzione su schermo, spoofing di tipo deepfake). |
| `FACE_IN_BLOCKLIST` | Il volto corrisponde a una voce presente nella blocklist dei volti della tua applicazione. |
| `AGE_BELOW_MINIMUM` | Età stimata inferiore al minimo configurato. Emesso solo nei workflow di verifica dell'età adattivi e nei nodi `AGE_ESTIMATION`. |
| `AGE_NOT_DETECTED` | Impossibile stimare l'età. Emesso solo nei flussi di stima dell'età con fallback alla verifica dell'identità disabilitato. |

Quando si attiva `NO_FACE_DETECTED`, `LOW_LIVENESS_SCORE` viene soppresso (non c'è alcun volto a cui assegnare un punteggio).

## Impostazioni di verifica configurabili

Nella console Didit, i rischi di vitalità sono raggruppati nelle seguenti impostazioni del workflow:

| Gruppo | Rischi | Configurazione |
| - | - | - |
| **Soglie del punteggio di vitalità** | `LOW_LIVENESS_SCORE` | Soglia di revisione + soglia di rifiuto su `score`. Pari o inferiore alla soglia di revisione → `In Review`; pari o inferiore alla soglia di rifiuto → `Declined`. |
| **Azione per volto duplicato** | `DUPLICATED_FACE`, `POSSIBLE_DUPLICATED_FACE` | Un'unica impostazione condivisa: Nessuna azione (predefinita) / Revisione / Rifiuta. I rischi vengono completamente ignorati quando il volto corrispondente si trova nella tua allowlist dei volti. |
| **Mancata corrispondenza dell'identità per volto duplicato** | `DUPLICATED_FACE_NAME_MISMATCH` | Impostazione dedicata (`face_liveness_duplicated_face_name_mismatch_action`): Nessuna azione / Revisione (predefinita) / Rifiuta. Valutata solo quando si attiva anche `DUPLICATED_FACE` — vedi sotto. |
| **Confronto facciale con attacco alla vitalità** | `FACE_MATCHES_LIVENESS_ATTACK` | Impostazione dedicata (`face_liveness_attack_face_match_action`): Nessuna azione (predefinita) / Revisione. L'impostazione Rifiuta qui viene accettata ma applicata come Revisione. Disponibile anche nel nodo Stima dell'età. |
| **Possibile volto in blocklist** | `POSSIBLE_FACE_IN_BLOCKLIST` | Non configurabile nei workflow — instradato sempre a Revisione (`log_type: "warning"`). |
| **Azione per volti multipli** *(solo in modalità passiva)* | `MULTIPLE_FACES_DETECTED` | Nessuna azione (predefinita) / Revisione / Rifiuta. |
| **Soglie di qualità del volto** *(solo in modalità passiva)* | `LOW_FACE_QUALITY` | Soglia di revisione (predefinita a 15) + soglia di rifiuto (predefinita a 0, ossia rifiuto disabilitato). |
| **Luminanza del volto** *(solo in modalità passiva)* | `LOW_FACE_LUMINANCE`, `HIGH_FACE_LUMINANCE` | Soglie minima / massima (predefinite a 20 / 80 sulla scala normalizzata 0–100) + un'azione per direzione (predefinita a Revisione). |
| **Soglie di età** *(workflow adattivi / nodo `AGE_ESTIMATION`)* | `AGE_BELOW_MINIMUM`, `AGE_NOT_DETECTED` | Soglie di età minima e borderline; entrambi i rischi comportano il rifiuto automatico del passaggio di rilevamento della vitalità. Con il fallback alla verifica dell'identità abilitato, il workflow indirizza l'utente a un controllo del documento invece di terminare la sessione. |

## Avvisi generati

### Vitalità principale

| Rischio | Causa | Gravità | Influisce sullo stato? | Rimedio |
| - | - | - | - | - |
| `NO_FACE_DETECTED` | Nessun volto individuato durante l'acquisizione, oppure l'utente ha esaurito i tentativi disponibili (`MAX_ATTEMPTS_REACHED`). | `error` | **Rifiuto automatico** | Ripeti l'acquisizione con un'illuminazione migliore; assicurati che il volto sia centrato. |
| `LIVENESS_FACE_ATTACK` | Il modello ha rilevato un attacco di presentazione. | `error` | **Rifiuto automatico** | Consideralo una frode. La sessione viene rifiutata automaticamente. |
| `LOW_LIVENESS_SCORE` | `score` pari o inferiore alla soglia di revisione del workflow. Soppresso quando è presente anche `NO_FACE_DETECTED`. | `warning`; passa a `error` quando il punteggio è pari o inferiore alla soglia di rifiuto | Configurabile (soglie di revisione / rifiuto) | Ripeti l'acquisizione; regola le soglie se osservi falsi positivi. |

### Integrità del canale di acquisizione

Segnali di attacco di iniezione segnalati dal client al momento dell'acquisizione. A differenza degli attacchi di presentazione (un artefatto posto davanti a una fotocamera reale), questi descrivono la sostituzione o l'intercettazione del feed della fotocamera stesso.

Ciascuno è configurabile per workflow e l'impostazione predefinita è **nessuna azione**, quindi l'abilitazione della funzionalità non modifica alcuna decisione finché non attivi esplicitamente la funzionalità.

| Rischio | Causa | Chiave di configurazione | Predefinito |
| - | - | - | - |
| `VIRTUAL_CAMERA_DETECTED` | Il dispositivo di acquisizione è stato identificato come una fotocamera virtuale software (OBS, ManyCam, Snap Camera, DroidCam e simili) anziché una fotocamera fisica. | `virtual_camera_action` | `NO_ACTION` |
| `EXTERNAL_CAPTURE_DEVICE_DETECTED` | Il dispositivo di acquisizione era una fotocamera esterna o una scheda di acquisizione anziché una fotocamera integrata. | `external_capture_device_action` | `NO_ACTION` |
| `FRAME_INJECTION_SUSPECTED` | I fotogrammi acquisiti mostrano indicatori di composizione software o di iniezione nella pipeline della fotocamera anziché una reale acquisizione dal vivo, **o** l'acquisizione è stata eseguita su hardware emulato o virtualizzato (un emulatore Android o una macchina virtuale desktop), dove non esiste alcun sensore fisico della fotocamera e ogni fotogramma viene fornito dall'host. | `frame_injection_action` | `NO_ACTION` |
| `INJECTION_ATTACK_DETECTED` | L'acquisizione è stata iniettata anziché ripresa dalla fotocamera del dispositivo stesso: una fotocamera virtuale software, un feed della fotocamera generato dalla pagina o dall'automazione del browser, una fotocamera sottoposta a hooking o uno strumento di instrumentazione collegato all'app. `additional_data.reasons` elenca solo i motivi che lo dimostrano. I segnali che una persona reale può produrre non lo attivano mai. Per la vitalità e il confronto facciale segue `frame_injection_action`, quindi le decisioni relative ai selfie non cambiano. | `frame_injection_action` | `NO_ACTION` |
| `SCREEN_CAPTURE_DURING_CAPTURE` | La registrazione dello schermo o la condivisione dello schermo era attiva sul dispositivo durante l'acquisizione biometrica. | `screen_capture_action` | `NO_ACTION` |

> [!NOTE]
>
> I browser non espongono alcuna attestazione a livello di sistema operativo sull'origine della fotocamera a nessun fornitore, quindi sul web questi segnali costituiscono prove a supporto piuttosto che prove certe. Sul web, un verdetto pari a `null` indica **non determinato** (le etichette dei dispositivi non sono disponibili finché non viene concesso il permesso per la fotocamera) e non genera mai un rischio.

Una fotocamera virtuale viene identificata dal nome del dispositivo, quindi una fotocamera che il sistema operativo presenta con un nome comune non viene riconosciuta in questo modo. All'interno di un emulatore Android la fotocamera rimappata viene etichettata come una qualsiasi integrata, motivo per cui il caso dell'hardware emulato viene segnalato tramite `FRAME_INJECTION_SUSPECTED`: viene rilevato dall'ambiente del dispositivo (lo stack di rendering e il modello del dispositivo segnalati nello user agent) anziché dal nome della fotocamera. I rilievi generati dall'ambiente del dispositivo contengono `additional_data.reason: "emulated_capture_device"`, distinguendosi così dall'analisi dei frame eseguita dal modello di liveness stesso.

> [!NOTE]
>
> Il rilevamento della macchina da un browser costituisce una prova indiziaria, non un'attestazione, e un utente malintenzionato determinato può interferire con esso. Gli SDK nativi per dispositivi mobili segnalano segnali di integrità più solidi a livello di sistema operativo che un browser non può rilevare (emulatore, dispositivo sottoposto a root o jailbreak, hooking del runtime, debugger collegato), ciascuno con la propria azione configurabile in [Integrità del runtime e del dispositivo](https://docs.didit.me/it/core-technology/ip-analysis/warnings-ip-analysis.md#integrità-del-dispositivo-e-del-runtime). Questi segnali aumentano notevolmente i costi per l'attaccante, ma da soli non provano che un'acquisizione provenga da un dispositivo autentico. I segnali di integrità del dispositivo sono indipendenti dal metodo di liveness, pertanto si combinano con qualsiasi modalità tra Passiva, 3D Flash o 3D Action & Flash.

### Analisi forense dell'integrità della registrazione

`LIVENESS_VIDEO_ANOMALY` viene calcolato **lato server sulla registrazione di liveness archiviata**, indipendentemente dal modello di liveness. Rileva una sequenza in movimento ripetuta su più cicli, compatibile con un feed riprodotto in loop.

| Rischio | Causa | Chiave di configurazione | Predefinito |
| - | - | - | - |
| `LIVENESS_VIDEO_ANOMALY` | La registrazione contiene una sequenza in movimento ripetuta. Blocchi della fotocamera, fotogrammi statici ripetuti, sequenze iniziali scure e una consegna lenta dei fotogrammi non attivano da soli questo segnale. | `face_liveness_video_anomaly_action` | `NO_ACTION` |

Imposta l'azione sul tuo nodo Rilevamento della vitalità o Stima dell'età: `NO_ACTION` registra un rilievo informativo, `REVIEW` può far passare una verifica con decisione presa allo stato In revisione, e `DECLINE` può farla passare a Rifiutata. Il controllo viene eseguito in modo asincrono, quindi un'escalation può arrivare dopo il risultato iniziale. Una decisione esistente più severa non viene declassata e le decisioni di revisione manuale vengono mantenute.

I rilievi della versione 2 includono `forensics_version: 2`, prove di `repeated_sequence` e `repeated_moving_sequence` in `anomaly_reasons`. Le misurazioni di consegna come `unique_frame_ratio`, `static_pair_ratio`, `decoded_fps_ratio` e `max_frame_gap_seconds` rimangono diagnostiche; non possono da sole dimostrare che si tratta di un replay. I rilievi più datati descrivono la versione del rilevatore utilizzata all'epoca e non vengono riclassificati retroattivamente.

> [!NOTE]
>
> Si tratta di un segnale aggiuntivo prudenziale, non di un rilevamento completo di media sintetici o video iniettati. Una registrazione senza anomalie non costituisce una prova di vitalità. Acquisizioni brevi o ambigue e acquisizioni prive di prove di replay utilizzabili non vengono contrassegnate da questo controllo. Le registrazioni mancanti o illeggibili non producono alcun rilievo da questo controllo; continuano ad applicarsi gli altri controlli di verifica.

### Confronto facciale tra sessioni

| Rischio | Causa | Dati aggiuntivi | Gravità |
| - | - | - | - |
| `FACE_IN_BLOCKLIST` | Il volto corrisponde a un volto presente in blocklist. | `blocklisted_session_id`, `blocklisted_session_number`, `api_service` | `error` — **rifiuto automatico** |
| `POSSIBLE_FACE_IN_BLOCKLIST` | Il volto corrisponde a un volto presente in blocklist in una fascia di affidabilità inferiore. | `blocklisted_session_id`, `blocklisted_session_number`, `api_service` | `warning` — instradato sempre a Revisione nei workflow |
| `FACE_IN_ALLOWLIST` | Il volto corrisponde a un volto presente in allowlist. | `allowlisted_session_id`, `allowlisted_session_number`, `api_service` | `information` — azione per volto duplicato ignorata |
| `POSSIBLE_FACE_IN_ALLOWLIST` | Il volto corrisponde a un volto presente in allowlist in una fascia di affidabilità inferiore. | `allowlisted_session_id`, `allowlisted_session_number`, `api_service` | `information` — azione per possibile volto duplicato ignorata |
| `DUPLICATED_FACE` | Il volto corrisponde a un volto già approvato di un altro utente (una sessione `Approved` con diverso `vendor_data`, o un volto importato associato a uno dei tuoi utenti vendor). | `duplicated_session_id`, `duplicated_session_number`, `api_service` | Configurabile — `information` per impostazione predefinita |
| `POSSIBLE_DUPLICATED_FACE` | Il volto corrisponde a un altro volto approvato o importato in una fascia di affidabilità inferiore. | `duplicated_session_id`, `duplicated_session_number`, `api_service` | Configurabile — `information` per impostazione predefinita |
| `DUPLICATED_FACE_NAME_MISMATCH` | Emesso insieme a `DUPLICATED_FACE` quando l'identità della sessione corrispondente non coincide con il nome risolto di questa sessione (documento d'identità, `expected_details` o utente vendor collegato), utilizzando lo stesso punteggio di corrispondenza del nome e la stessa soglia della verifica dell'identità. Un volto riutilizzato con un nome diverso costituisce un segnale di frode più forte rispetto a un semplice duplicato, pertanto prevede un'azione configurabile dedicata. | `duplicated_session_id`, `duplicated_session_number`, `api_service`, `name_match_score` | Configurabile — `warning` per impostazione predefinita. Non riduce mai l'esito configurato di `DUPLICATED_FACE`, ma può solo aggravarlo. |
| `DUPLICATED_FACE_DOCUMENT_MISMATCH` | Emesso insieme a `DUPLICATED_FACE` quando il documento d'identità dell'utente corrispondente riporta una data di nascita diversa rispetto al documento di questa sessione. La stessa persona non viene segnalata se presenta un documento diverso (ad esempio un passaporto dopo una carta d'identità) o un documento rinnovato, e due sessioni che condividono lo stesso numero di documento dello stesso paese non vengono mai segnalate. | `duplicated_session_id`, `duplicated_session_number`, `api_service`, `mismatch_dimensions` | Configurabile (`face_liveness_duplicated_face_document_mismatch_action`) - `Review` per impostazione predefinita. Non riduce mai l'esito configurato di `DUPLICATED_FACE`, ma può solo aggravarlo. |
| `FACE_MATCHES_LIVENESS_ATTACK` | Il volto corrisponde a un volto di una sessione precedente di questa applicazione, appartenente a un altro utente, la cui acquisizione della vitalità è stata valutata come un attacco con elevata affidabilità. Costituisce un elemento per la revisione, non una prova certa di un attacco. | `liveness_attack_session_id`, `liveness_attack_session_number`, `similarity_percentage`, `liveness_attack_sessions_count` | Configurabile - `information` per impostazione predefinita (Nessuna azione) |

Per le corrispondenze con volti importati o voci di elenco (che non hanno una sessione), i valori di `*_session_id`, `*_session_number` e `api_service` in `additional_data` sono `null`.

I volti appartenenti allo stesso utente (stesso `vendor_data`, o lo stesso utente vendor quando disponibile) sono esclusi dall'**intera** ricerca nell'indice — sia dal rilevamento dei duplicati sia dallo screening delle blocklist. L'ordine di precedenza delle corrispondenze è: blocklist esatta → allowlist esatta → duplicato esatto → blocklist possibile → allowlist possibile → duplicato possibile — solo uno di questi sei codici mutuamente esclusivi compare per ciascun report. `DUPLICATED_FACE_NAME_MISMATCH` non fa parte di questo gruppo di precedenza: è un codice aggiuntivo emesso **in aggiunta a** `DUPLICATED_FACE` quando fallisce anche il controllo dell'identità, mai al suo posto. `additional_data.name_match_score` non include mai i nomi messi a confronto — solo gli ID e un punteggio, evitando così l'inclusione di PII nel payload dell'avviso.

Un nome scritto in un sistema di scrittura diverso su ciascun documento (ad esempio ebraico su uno e latino sull'altro) può ottenere un punteggio inferiore alla soglia anche se entrambe le sessioni appartengono alla stessa persona. In questo caso specifico, `DUPLICATED_FACE_NAME_MISMATCH` non viene emesso se i documenti d'identità delle due sessioni si confermano a vicenda su tutti i seguenti elementi:

* Entrambi i documenti riportano lo stesso stato emittente.
* Un identificativo corrisponde esattamente tra i due documenti. `document_number` e `personal_number` sono intercambiabili, poiché lo stesso numero nazionale può comparire in entrambi i campi a seconda del tipo di documento.
* Laddove entrambi i documenti riportino una data di nascita, questa corrisponde alla stessa data.

Se i nomi utilizzano lo stesso sistema di scrittura, se l'identificativo o lo stato emittente differiscono o sono assenti, oppure se le date di nascita sono in contrasto tra loro, l'avviso viene comunque emesso come descritto in precedenza.

### Qualità della vitalità passiva (solo quando `method = "PASSIVE"`)

| Rischio | Causa | Gravità | Rimedio |
| - | - | - | - |
| `MULTIPLE_FACES_DETECTED` | È stato rilevato più di un volto durante l'acquisizione. Il volto più grande viene sempre utilizzato per il calcolo del punteggio e il confronto. | Configurabile — `information` per impostazione predefinita | Ripetere l'acquisizione da soli. |
| `LOW_FACE_QUALITY` | Qualità del volto inferiore alla soglia di revisione (valore predefinito: 15). | `warning`; `error` quando inferiore alla soglia di rifiuto (valore predefinito: 0 — rifiuto disabilitato) | Migliore messa a fuoco / minore occlusione / volto centrato. |
| `LOW_FACE_LUMINANCE` | Luminanza normalizzata inferiore alla soglia minima (valore predefinito: 20). | Configurabile — `warning` per impostazione predefinita (l'azione predefinita è Revisione) | Illuminazione migliore. |
| `HIGH_FACE_LUMINANCE` | Luminanza normalizzata superiore alla soglia massima (valore predefinito: 80). | Configurabile — `warning` per impostazione predefinita (l'azione predefinita è Revisione) | Ridurre l'illuminazione; evitare il controluce. |

`LOW_FACE_LUMINANCE` e `HIGH_FACE_LUMINANCE` sono mutuamente esclusivi — la luminanza è o inferiore al minimo o superiore al massimo, mai entrambi.

### Stima dell'età (workflow adattivi e nodi `AGE_ESTIMATION`)

| Rischio | Causa | Gravità | Rimedio |
| - | - | - | - |
| `AGE_BELOW_MINIMUM` | Età stimata inferiore al minimo configurato (o alla soglia limite quando il fallback sulla verifica dell'identità è abilitato). | `error` | Il workflow esegue il fallback sulla verifica dell'identità se configurato. |
| `AGE_NOT_DETECTED` | Impossibile stimare l'età e il fallback sulla verifica dell'identità è disabilitato. | `error` | Abilita il fallback o ripeti l'acquisizione. |

## Stringhe di descrizione esatte

L'API restituisce queste stringhe esatte di `short_description` e `long_description` per ciascun rischio:

| `risk` | `short_description` | `long_description` |
| - | - | - |
| `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. |
| `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. |
| `LIVENESS_VIDEO_ANOMALY` | Liveness video stream anomaly | The recorded liveness video contains a repeated moving sequence consistent with a looped feed. Camera stalls, repeated still frames and slow frame delivery alone do not raise this signal. This is an independent recording check, not a complete assessment of whether the capture is live. |
| `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. |
| `FACE_MATCHES_LIVENESS_ATTACK` | Face matches a liveness attack | The face in this liveness capture matches a face from an earlier session of this application whose own capture the liveness engine judged to be an attack with high confidence, in a session of another user. A genuine user can be rejected by mistake, so this is a signal for review, not proof of an attack. |
| `MULTIPLE_FACES_DETECTED` | 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` | 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` | 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` | 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. |
| `AGE_BELOW_MINIMUM` | Age below minimum | The age of the face is below the minimum age threshold for the application. |
| `AGE_NOT_DETECTED` | Age not detected | The system couldn't identify the age of the face, which is necessary for document verification. |

## API autonoma di rilevamento passivo della vitalità

La [Liveness API](https://docs.didit.me/it/standalone-apis/passive-liveness.md) standalone riutilizza gli stessi codici di rischio con alcune differenze di comportamento:

* `NO_FACE_DETECTED` e `LOW_LIVENESS_SCORE` si escludono a vicenda: il controllo del punteggio viene eseguito solo se viene trovato un volto. `LOW_LIVENESS_SCORE` si attiva rispetto al valore di `face_liveness_score_decline_threshold` della richiesta (predefinito 30) e restituisce sempre `log_type: "error"`.
* `POSSIBLE_FACE_IN_BLOCKLIST` viene gestito come un rifiuto (`log_type: "error"`) invece che come revisione.
* `MULTIPLE_FACES_DETECTED` restituisce `log_type: "warning"`, mentre i rischi legati a volti duplicati rimangono informativi. Solo gli avvisi di livello `error` impostano il campo `status` della risposta standalone su `Declined`.
* Le voci di avviso standalone includono `feature` ma nessun `node_id`.

## Esempi

### Rifiuto automatico su attacco rilevato

```json theme={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": "liveness_primary"
  }
]
```

### Avvisi configurabili su un'acquisizione passiva

```json theme={null}
"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": "MULTIPLE_FACES_DETECTED",
    "additional_data": null,
    "log_type": "information",
    "short_description": "Multiple faces detected",
    "long_description": "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.",
    "node_id": "liveness_primary"
  }
]
```

### Volto duplicato con payload

```json theme={null}
"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "DUPLICATED_FACE",
    "additional_data": {
      "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
      "duplicated_session_number": 123,
      "api_service": null
    },
    "log_type": "warning",
    "short_description": "Duplicated face from other approved session",
    "long_description": "The system identified a duplicated face from another approved session, requiring further investigation.",
    "node_id": "liveness_primary"
  }
]
```

In questo caso l'azione per il volto duplicato è impostata su Review, quindi l'avviso include `log_type: "warning"` e lo stato del report di rilevamento della vitalità è `In Review`. Con l'impostazione predefinita (No action) includerebbe invece `log_type: "information"`. `api_service` è `null` perché il volto corrispondente proveniva da una sessione di workflow e non da una chiamata API autonoma.

### Volto duplicato con un nome diverso

```json theme={null}
"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "DUPLICATED_FACE",
    "additional_data": {
      "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
      "duplicated_session_number": 123,
      "api_service": null
    },
    "log_type": "information",
    "short_description": "Duplicated face from other approved session",
    "long_description": "The system identified a duplicated face from another approved session, requiring further investigation.",
    "node_id": "liveness_primary"
  },
  {
    "feature": "LIVENESS",
    "risk": "DUPLICATED_FACE_NAME_MISMATCH",
    "additional_data": {
      "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
      "duplicated_session_number": 123,
      "api_service": null,
      "name_match_score": 42.5
    },
    "log_type": "warning",
    "short_description": "Duplicated face under a different name",
    "long_description": "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.",
    "node_id": "liveness_primary"
  }
]
```

`DUPLICATED_FACE` mantiene l'azione configurata (qui, No action — `log_type: "information"`), mentre `DUPLICATED_FACE_NAME_MISMATCH` riporta la propria azione, che per impostazione predefinita è Review (`log_type: "warning"`). Lo stato del report di rilevamento della vitalità assume il livello più grave tra i due: qui `In Review`, anche se la sola impostazione del volto duplicato non lo avrebbe segnalato.

### Anomalia di integrità della registrazione con le relative misurazioni

```json theme={null}
"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "LIVENESS_VIDEO_ANOMALY",
    "additional_data": {
      "forensics_version": 2,
      "duration_seconds": 6.0,
      "repeated_sequence": {
        "period_frames": 6,
        "cycles": 3,
        "matched_pairs": 12
      },
      "anomaly_reasons": ["repeated_moving_sequence"]
    },
    "log_type": "information",
    "short_description": "Liveness video stream anomaly",
    "long_description": "The recorded liveness video contains a repeated moving sequence consistent with a looped feed. Camera stalls, repeated still frames and slow frame delivery alone do not raise this signal. This is an independent recording check, not a complete assessment of whether the capture is live.",
    "node_id": "liveness_primary"
  }
]
```

Questo esempio mostra le prove di replay provenienti da una registrazione contenente tre copie di una sequenza in movimento. `log_type` è `information` perché l'azione configurata è `NO_ACTION`. La diagnostica della consegna dei frame, omessa in questo esempio per brevità, non attiva la segnalazione.

## Tipi di avviso

A ciascun rischio viene assegnata una gravità in base alla configurazione della tua applicazione. I tre livelli di gravità sono:

## Correlati

* [Report di rilevamento della vitalità](https://docs.didit.me/it/core-technology/liveness/report-liveness.md) — schema completo del report e degli stati.
* [Avvisi di confronto facciale](https://docs.didit.me/it/core-technology/face-match/warnings-face-match.md) — avvisi associati al confronto facciale 1:1.
* [Webhook](https://docs.didit.me/it/integration/webhooks.md) — `session.status.updated` trasmette gli avvisi non appena termina il passaggio di rilevamento della vitalità.
* [Modelli di dati — Controllo di rilevamento della vitalità](https://docs.didit.me/it/reference/data-models.md#rilevamento-della-vitalità) — schema canonico con tutti i campi.
* [Modelli di dati — Oggetto di avviso](https://docs.didit.me/it/reference/data-models.md#oggetto-avviso) — la struttura di ogni voce in `warnings[]`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.