> ## 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 e codici di errore della verifica dell'identità

> Tutti gli avvisi del modulo di verifica dell'identità Didit: trigger di rifiuto, codici di manomissione e rischio con cause e soluzioni.

## Panoramica

Gli avvisi nel report di verifica dell'identità segnalano ogni condizione rilevata da Didit durante la lettura e la validazione del documento. Vengono inseriti nell'array `warnings[]` di ciascun elemento di `id_verifications[]` (consulta [Report di verifica dell'identità](https://docs.didit.me/it/core-technology/id-verification/report-id-verification.md)), con la struttura descritta in [Modelli di dati — Oggetto dell'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 ha tre livelli:

1. **Il codice `risk`** — un identificativo stabile da usare per il confronto nel codice.
2. **Il `log_type`** — derivato dall'azione assegnata dalla tua configurazione al rischio in fase di valutazione: **Rifiuta → `error`**, **Revisione → `warning`**, qualsiasi altra cosa → `information`.
3. **L'impatto sulla decisione** — definito dai gruppi di rischio configurabili del workflow. Lo stesso codice `risk` può essere indirizzato verso **Approva**, **Revisione** o **Rifiuta** a seconda di come è configurata la tua applicazione.

## Condizioni di rifiuto automatico

Nei workflow, i seguenti rischi forzano sempre il report di verifica dell'identità (e la sessione) allo stato `Declined`. Non sono configurabili:

| Rischio | Trigger |
| - | - |
| `DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | Il tipo di documento inviato non è presente nell'elenco dei documenti consentiti per la tua applicazione. `additional_data` include `issuing_state`, `document_type`, `document_subtype`, `document_region` e `document_region_with_subtype` per consentirti di abilitare il documento specifico nel tuo workflow. |
| `DOCUMENT_EXPIRED` | La data di scadenza del documento è stata superata al momento dell'acquisizione. |
| `PORTRAIT_IMAGE_NOT_DETECTED` | Non è stato possibile individuare alcuna immagine del ritratto sul documento. |
| `ID_DOCUMENT_IN_BLOCKLIST` | Il documento corrisponde a una voce presente nella blocklist della tua applicazione. |
| `FRONT_CAMERA_FACE_IN_BLOCKLIST` | Il selfie scattato dalla fotocamera anteriore durante l'acquisizione del documento corrisponde a un volto presente nella tua blocklist dei volti. |
| `AGE_BELOW_MINIMUM` | Solo per i workflow di verifica dell'età adattivi: l'età estratta è inferiore al minimo. |
| `AGE_NOT_DETECTED` | Solo per i workflow di verifica dell'età adattivi: non è stato possibile estrarre l'età dal documento. |

Per l'**API OCR autonoma**, il set di rifiuto incondizionato comprende `DOCUMENT_EXPIRED`, `MINIMUM_AGE_NOT_MET`, `PORTRAIT_IMAGE_NOT_DETECTED`, `SCREEN_CAPTURE_DETECTED`, `PRINTED_COPY_DETECTED`, `PORTRAIT_MANIPULATION_DETECTED` e `PUBLIC_DOCUMENT_IMAGE_DETECTED`. Nei workflow, l'età minima è configurabile (Rifiuta per impostazione predefinita) e i tre rischi di vitalità del documento sono gestiti tramite soglie (vedi sotto).

I parametri di richiesta per i rischi configurabili di tale API accettano `DECLINE` o `NO_ACTION` anziché un verdetto di Revisione. L'unico esito di Revisione che può restituire non è configurabile: quando un controllo di vitalità del documento richiesto non produce un punteggio utilizzabile, la risposta è `In Review` con un avviso `DOCUMENT_LIVENESS_NOT_COMPUTED` (consulta [Vitalità del documento](#vitalità-del-documento-manomissione)).

| Parametro della richiesta | Rischi | Predefinito |
| - | - | - |
| `invalid_mrz_action` | `MRZ_VALIDATION_FAILED`, `MRZ_NOT_DETECTED` | `DECLINE` |
| `inconsistent_data_action` | `DATA_INCONSISTENT`, `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME`, `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS` | `DECLINE` |
| `expiration_date_not_detected_action` | `EXPIRATION_DATE_NOT_DETECTED` | `NO_ACTION` |
| `critical_field_occlusion_action` | `CRITICAL_FIELD_OCCLUSION_DETECTED` | `DECLINE` |
| `document_or_personal_number_format_mismatch_action` | `DOCUMENT_NUMBER_FORMAT_MISMATCH`, `PERSONAL_NUMBER_FORMAT_MISMATCH` | `NO_ACTION` |

## Impostazioni di verifica configurabili

Nella console Didit, i restanti rischi relativi ai documenti d'identità sono raggruppati in impostazioni che puoi instradare verso **Approva**, **Revisione** o **Rifiuta** (per workflow e per nodo nei workflow a grafo):

| Gruppo | Rischi | Azione predefinita |
| - | - | - |
| **Età Minima** | `MINIMUM_AGE_NOT_MET` | Rifiuta |
| **Età massima** | `MAXIMUM_AGE_EXCEEDED` | Rifiuta |
| **Utente duplicato** | `POSSIBLE_DUPLICATED_USER` (omesso se il numero di documento è presente nella tua lista di documenti consentiti) | Approva (informazione) |
| **Codice non valido** | `QR_NOT_DETECTED`, `BARCODE_NOT_DETECTED`, `QR_VALIDATION_FAILED`, `BARCODE_VALIDATION_FAILED` | Approva (informazione) |
| **MRZ non valido** | `MRZ_VALIDATION_FAILED`, `MRZ_NOT_DETECTED` | Approva (informazione) |
| **Incoerenza dei dati** | `DATA_INCONSISTENT`, `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME`, `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS`, `DOCUMENT_SIDES_MISMATCH`, `ID_VERIFICATION_DATA_MISMATCH_BETWEEN_DOCUMENTS` | Approva (informazione) |
| **Validazione non riuscita** | `INVALID_DATE`, `COULD_NOT_RECOGNIZE_DOCUMENT`, `DOCUMENT_NUMBER_NOT_DETECTED`, `COULD_NOT_DETECT_DOCUMENT_TYPE`, `NAME_NOT_DETECTED`, `DATE_OF_BIRTH_NOT_DETECTED` | Revisione |
| **Mancata corrispondenza dei dettagli previsti** | `FULL_NAME_MISMATCH_WITH_PROVIDED`, `GENDER_MISMATCH_WITH_PROVIDED`, `DOB_MISMATCH_WITH_PROVIDED`, `COUNTRY_MISMATCH_WITH_PROVIDED`, `NATIONALITY_MISMATCH_WITH_PROVIDED`, `IDENTIFICATION_NUMBER_MISMATCH_WITH_PROVIDED` | Revisione |
| **Data di scadenza non rilevata** | `EXPIRATION_DATE_NOT_DETECTED` | Approva (informazione) |
| **Mancata corrispondenza del formato del numero di documento o personale** | `DOCUMENT_NUMBER_FORMAT_MISMATCH`, `PERSONAL_NUMBER_FORMAT_MISMATCH` (un'unica azione condivisa) | Revisione |
| **Campo critico coperto** | `CRITICAL_FIELD_OCCLUSION_DETECTED` | Revisione |
| **Indirizzo non analizzato** | `UNPARSED_ADDRESS` | Approva (informazione) |
| **Qualità dell'immagine** | `IMAGE_TOO_BLURRY`, `IMAGE_TOO_DARK`, `IMAGE_TOO_BRIGHT` (un'azione per rischio) | Approva (informazione) |
| **Documento senza ritratto** | `DOCUMENT_HAS_NO_PORTRAIT` | Revisione |
| **Volto duplicato nell'acquisizione silenziosa** | `FRONT_CAMERA_DUPLICATED_FACE`, `POSSIBLE_FRONT_CAMERA_DUPLICATED_FACE` (un'unica azione condivisa) | Approva (informazione) |
| **Duplicato nell'acquisizione silenziosa con nome diverso** | `FRONT_CAMERA_DUPLICATED_FACE_NAME_MISMATCH` (può solo rendere più rigoroso l'esito del volto duplicato) | Revisione |
| **Duplicato nell'acquisizione silenziosa con data di nascita diversa** | `FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH` (può solo rendere più rigoroso l'esito del volto duplicato) | Revisione |

I rischi di duplicato e blocklist dell'acquisizione silenziosa provengono dalla [Ricerca facciale sul selfie scattato durante l'acquisizione del documento](https://docs.didit.me/it/core-technology/face-search/overview.md#il-selfie-scattato-durante-l’acquisizione-del-documento). La ricerca viene eseguita quando **Ricerca facciale con acquisizione silenziosa** (`document_selfie_face_search_enabled`) è attiva, impostazione predefinita, e la Ricerca facciale non è disattivata nel passaggio di Rilevamento della vitalità; altrimenti nessuno di questi sei rischi viene generato.

Due famiglie di rischi relativi ai documenti d'identità sono **basate su soglie** anziché su selettori Approva/Revisione/Rifiuta:

* **Rilevamento della vitalità del documento** — `SCREEN_CAPTURE_DETECTED`, `PRINTED_COPY_DETECTED`, `PORTRAIT_MANIPULATION_DETECTED`. Ciascun tipo di frode ha le proprie soglie di rifiuto e revisione: punteggio inferiore alla soglia di rifiuto → `error` + Rifiutata; inferiore alla soglia di revisione → `warning` + In revisione; altrimenti `information`.
* **Confronto facciale tra fotocamere** — `LOW_FRONT_CAMERA_FACE_MATCH_SIMILARITY`, regolato da `document_selfie_portrait_match_decline_threshold` / `document_selfie_portrait_match_review_threshold`.

### Configurazione delle soglie di rilevamento della vitalità del documento

Nell'editor dei workflow queste soglie si trovano nella scheda **Falsificazione** del passaggio di Verifica dell'identità, con una scheda per ciascun tipo di frode: **Sostituzione del ritratto**, **Copia stampata** e **Cattura schermo**.

Ciascun controllo assegna al documento un punteggio da `0` a `100` che ne indica l'autenticità apparente. **Un punteggio più alto indica che il documento è più probabilmente autentico.** I due valori su ciascuna scheda dividono tale scala in tre fasce:

| Punteggio | Risultato |
| - | - |
| Inferiore al valore **Rifiuta** | `error`, la sessione è Rifiutata |
| Pari o superiore al valore **Rifiuta** e inferiore al valore **Revisione** | `warning`, la sessione passa a In revisione |
| Pari o superiore al valore **Revisione** | `information`, il controllo viene superato |

Aumentando uno dei due valori il controllo diventa più rigoroso: un numero maggiore di sessioni finisce nella fascia superiore. Abbassando un valore si lascia passare un numero maggiore di sessioni. Nell'editor il valore Rifiuta non può superare il valore Revisione. Tramite API, un valore Rifiuta superiore al valore Revisione rimuove la fascia In revisione.

Valori predefiniti della piattaforma, utilizzati quando un workflow non imposta un valore:

| Tipo di frode | Rifiuta se inferiore a | Revisione se inferiore a | Chiavi di configurazione del workflow |
| - | - | - | - |
| Sostituzione del ritratto | `35` | `70` | `document_liveness_portrait_replace_decline_threshold`, `document_liveness_portrait_replace_review_threshold` |
| Copia stampata | `35` | `77` | `document_liveness_printed_copy_decline_threshold`, `document_liveness_printed_copy_review_threshold` |
| Cattura schermo | `30` | `70` | `document_liveness_screen_replay_decline_threshold`, `document_liveness_screen_replay_review_threshold` |

Inizia dai valori predefiniti e modifica un valore alla volta. Ciascuna scheda mostra il valore predefinito e un pulsante **Ripristina valori predefiniti**, così puoi sempre tornarvi. L'editor ti avvisa inoltre in merito a queste configurazioni:

* **Revisione a `100`.** Solo un punteggio perfetto supera il controllo, quindi quasi ogni sessione passa a In revisione o viene rifiutata.
* **Rifiuta a `100`.** Solo un punteggio perfetto evita il rifiuto, quindi quasi ogni sessione viene rifiutata.
* **Entrambi i valori a `0`.** Nessun punteggio viene mai segnalato, quindi il controllo è di fatto disattivato.

Impostando entrambi i valori sullo stesso numero si rimuove la fascia In revisione: un punteggio inferiore viene rifiutato e qualsiasi altro punteggio supera il controllo.

Quando sia **Copia stampata** che **Cattura schermo** segnalerebbero lo stesso documento, viene riportato solo `SCREEN_CAPTURE_DETECTED`.

Il confronto facciale tra fotocamere utilizza lo stesso principio con una differenza sul limite: un punteggio pari alla relativa soglia di revisione passa comunque a In revisione.

Quattro rischi relativi all'ID non sono né configurabili né basati su soglie. `POSSIBLE_FRONT_CAMERA_FACE_IN_BLOCKLIST` reindirizza sempre a **Revisione**: un selfie che si avvicina a un volto presente nella blocklist, senza essere una corrispondenza confermata, deve essere valutato da una persona; non dà mai luogo a un rifiuto automatico e non viene mai ignorato. `BARCODE_SIGNATURE_INVALID` reindirizza sempre a **Revisione**. Si attiva solo quando un codice a barre riporta una firma dell'autorità di emissione che non supera la verifica crittografica, quindi non esiste alcuna configurazione in cui una contraffazione accertata venga ignorata. `DOCUMENT_BACK_SIDE_NOT_AVAILABLE` è sempre di tipo **informativo** e non influisce mai sulla decisione: segnala una limitazione del catalogo dei documenti di Didit, non una caratteristica del documento presentato, quindi non esiste alcuna configurazione in cui possa rifiutare o inviare in revisione un titolare autentico.
`FRONT_CAMERA_CAPTURED_DOCUMENT` reindirizza sempre a **Revisione**.
Si attiva solo quando il fotogramma della fotocamera frontale acquisito durante la scansione del documento mostra un documento d'identità e nessuna persona, così che un'acquisizione che non dice nulla su chi reggesse il documento raggiunga sempre una persona.
Viene controllato ogni volta che il confronto tra selfie e acquisizione del documento (`is_document_selfie_portrait_match_enabled`) è attivo.

## Avvisi generati

Verificato rispetto a `collect_ocr_logs`, al flusso di acquisizione del documento e a `process_ocr_logs_and_get_status`. Le descrizioni brevi di seguito rappresentano le stringhe esatte di `short_description` restituite dall'API.

### Riconoscimento e qualità del documento

| Rischio | Descrizione breve | Causa | Gravità |
| - | - | - | - |
| `COULD_NOT_RECOGNIZE_DOCUMENT` | Could not validate Document | Il sistema non ha potuto confermare l'autenticità o la validità del documento inviato: spesso a causa di una scarsa qualità dell'immagine o di un tipo di documento non supportato. Utilizzato anche come fallback per errori di elaborazione non riconosciuti. | Configurabile — Invalid Validation, predefinito Revisione |
| `COULD_NOT_DETECT_DOCUMENT_TYPE` | Could not detect document type | Il fronte del documento non corrisponde con un livello elevato di affidabilità al layout di un documento ufficiale noto, oppure il motore OCR non è riuscito a classificare la famiglia del documento (passaporto vs documento d'identità vs patente di guida). Un documento che contiene dati validi ma il cui layout non corrisponde ad alcun modello ufficiale (un documento modificato o generato al computer, oppure un nuovo modello non ancora supportato) ricade qui. Quando questo evento si attiva, `DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` viene soppresso (il tipo è sconosciuto, quindi "non supportato" risulterebbe contraddittorio). | Configurabile — Invalid Validation, predefinito Revisione |
| `DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | Document not supported for your application | Il tipo di documento riconosciuto non è presente nell'elenco di quelli consentiti per l'applicazione. `additional_data` include paese, tipo di documento, sottotipo e sottotipo regionale. | `error` — **rifiuto automatico** |
| `DOCUMENT_EXPIRED` | Document expired | Al momento dell'acquisizione: la data di scadenza del documento è passata (`error`, rifiuto automatico). Post-approvazione: il monitoraggio continuo della scadenza aggiunge questo avviso con `log_type: "warning"` quando la data di un documento approvato viene superata, e lo stato del report diventa `Expired`. | `error` all'acquisizione; `warning` dal monitoraggio |
| `DOCUMENT_SIDES_MISMATCH` | Document sides mismatch | Le immagini del fronte e del retro non appartengono allo stesso documento. | Configurabile — Data Inconsistency, predefinito informativa |
| `DOCUMENT_BACK_SIDE_NOT_AVAILABLE` | Back side not available for this document | Il workflow ha richiesto entrambi i lati, il fronte è stato riconosciuto e il catalogo dei documenti di Didit non registra alcun retro per quel documento specifico, pertanto è stato possibile raccogliere solo il fronte. Le prove nel report riguardano un solo lato. Non è presente alcun problema nel documento presentato, al titolare non viene mai richiesto di ripetere l'acquisizione e una nuova scansione non può aggiungere un retro. `additional_data` include il `front_document_name` riconosciuto. | `information` — non influisce mai sulla decisione |
| `PORTRAIT_IMAGE_NOT_DETECTED` | Portrait image not detected | Non è stato possibile individuare alcuna fototessera su un documento che dovrebbe averne una (il rilevamento viene posticipato quando l'utente carica prima il lato privo di fototessera). | `error` — **rifiuto automatico** |
| `DOCUMENT_HAS_NO_PORTRAIT` | Document has no portrait | La famiglia di documenti riconosciuta non include mai una fototessera su nessun lato (alcuni permessi di soggiorno, tessere sanitarie, certificati di registrazione, tessere fiscali e un sottoinsieme di patenti/documenti d'identità). Si tratta di una caratteristica a livello di catalogo per quel tipo di documento, non di un problema di qualità dell'immagine: una nuova scansione del documento non può modificare l'esito. | Configurabile — Document Without Portrait, predefinito Revisione |
| `IMAGE_TOO_BLURRY` / `IMAGE_TOO_DARK` / `IMAGE_TOO_BRIGHT` | Document image is too blurry / too dark / too bright | Il controllo di qualità dell'immagine ha rifiutato un caricamento (all'utente viene chiesto di ripetere lo scatto). `additional_data` include il lato (`side`) non conforme. Un nuovo tentativo riuscito cancella l'avviso obsoleto; il controllo viene saltato all'ultimo tentativo consentito all'utente, in modo da evitare un blocco definitivo. | Configurabile — azione Image Quality per rischio, predefinito informativa |

> [!NOTE]
>
> Il flusso di acquisizione può anche rifiutare un caricamento con i codici di feedback `IMAGE_RESOLUTION_TOO_LOW`, `DOCUMENT_NOT_FULLY_VISIBLE`, `IMAGE_QUALITY_TOO_LOW` e `DOCUMENT_OCCLUSION_DETECTED` (un dito o un oggetto viene ritenuto fisicamente sovrapposto al testo stampato). Ciascuno di essi richiede un nuovo tentativo nell'SDK e viene registrato nel report come rischio a sé stante, instradato dalle impostazioni di Image Quality; `DOCUMENT_OCCLUSION_DETECTED` e `IMAGE_QUALITY_TOO_LOW` condividono la stessa azione. Questi codici descrivono l'*acquisizione*: un nuovo tentativo riuscito cancella l'avviso. La questione se un campo coperto debba influire sulla decisione viene gestita separatamente dal controllo di integrità `CRITICAL_FIELD_OCCLUSION_DETECTED` riportato sotto, che viene generato al momento della decisione e ha come valore predefinito Revisione.

> [!TIP]
>
> Se il tuo workflow basa l'identità sul confronto facciale (Face Match) anziché sulla fototessera del documento, valuta la possibilità di indirizzare **Document Without Portrait** verso il rifiuto; in caso contrario, una famiglia di documenti senza fototessera raggiungerà il confronto facciale senza alcun elemento con cui effettuare la comparazione.

### Estrazione dei campi

| Rischio | Descrizione breve | Causa | Gravità |
| - | - | - | - |
| `NAME_NOT_DETECTED` | First name and/or last name not detected | Non è stato possibile estrarre il nome e/o il cognome. Esente nel caso in cui il titolare abbia legittimamente un solo nome (nei paesi con nome singolo oppure quando la MRZ stessa riporta un solo nome) e sia stato estratto almeno un valore del nome. | Configurabile — Invalid Validation, predefinito Revisione |
| `DATE_OF_BIRTH_NOT_DETECTED` | Date of birth not detected | Non è stato possibile estrarre la data di nascita da un documento che dovrebbe averne una. | Configurabile — Invalid Validation, predefinito Revisione |
| `DOCUMENT_NUMBER_NOT_DETECTED` | Document number not detected | Non è stato possibile estrarre né il numero del documento né un codice identificativo personale. | Configurabile — Invalid Validation, predefinito Revisione |
| `EXPIRATION_DATE_NOT_DETECTED` | Expiration date not detected | Non è stato possibile estrarre la data di scadenza da un documento che dovrebbe averne una. | Configurabile — Expiration Date Not Detected, predefinito informativa |
| `INVALID_DATE` | Invalid Date | Una data presente sul documento (data di nascita o di scadenza) non può essere convertita in una data valida. Nell'attuale flusso di acquisizione, questo problema si manifesta come una richiesta di ripetizione dello scatto durante il caricamento anziché come un avviso memorizzato; il codice rimane nel gruppo di instradamento Invalid Validation e può comparire nelle sessioni più datate. | Configurabile — Invalid Validation, predefinito Revisione |
| `DOCUMENT_NUMBER_FORMAT_MISMATCH` | Formato del numero di documento non corrispondente | Il numero del documento non corrisponde al formato previsto configurato per questo tipo di documento. `additional_data` include `expected_format` e `extracted_value`. | Configurabile — Formato non corrispondente, predefinito Revisione |
| `PERSONAL_NUMBER_FORMAT_MISMATCH` | Formato del numero personale non corrispondente | Il numero personale non corrisponde al formato previsto configurato per questo tipo di documento. | Configurabile — Formato non corrispondente, predefinito Revisione |
| `CRITICAL_FIELD_OCCLUSION_DETECTED` | Un campo critico del documento è coperto | Il controllo dell'occlusione ha rilevato che un campo critico stampato era fisicamente coperto nell'acquisizione: un numero di identificazione, un nome, la data di nascita o la data di scadenza. Si tratta di un segnale di integrità del documento, non di qualità dell'acquisizione: coprire proprio i numeri con cui viene riconciliato un report è tipico di un documento oscurato o manomesso. Il valore letto per un campo coperto viene scartato dall'estrazione anziché essere restituito come confermato, pertanto il rischio corrispondente `*_NOT_DETECTED` di solito accompagna questo avviso. `additional_data` include i nomi dei campi coperti in `covered_fields` e `covered_identifiers` quando uno di essi alimenta `document_number` o `personal_number`. | Configurabile — Campo critico coperto, predefinito Revisione |

### MRZ, QR, codice a barre

Tutti e tre i rischi MRZ vengono saltati per i tipi di documenti con MRZ notoriamente inaffidabili.

| Rischio | Breve descrizione | Causa | Gravità |
| - | - | - | - |
| `MRZ_NOT_DETECTED` | MRZ non rilevata | Non è stato possibile individuare la MRZ su un documento che dovrebbe averne una. | Configurabile — MRZ non valida, predefinito informazione |
| `MRZ_VALIDATION_FAILED` | MRZ non valida | La MRZ non ha superato la convalida di checksum / formato. Spesso si tratta di un'acquisizione di bassa qualità; può indicare manomissione. | Configurabile — MRZ non valida, predefinito informazione |
| `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME` | La MRZ e i dati estratti dall'OCR presentano discrepanze | Il contenuto della MRZ non coincide con l'OCR della VIZ (zona visibile). Possibile alterazione. | Configurabile — Incoerenza dei dati, predefinito informazione |
| `QR_NOT_DETECTED` | QR non rilevato | Non è stato possibile individuare il codice QR su un documento che dovrebbe averne uno. | Configurabile — Codice non valido, predefinito informazione |
| `QR_VALIDATION_FAILED` | Convalida QR non riuscita | Non è stato possibile convalidare il contenuto del codice QR rispetto al resto del documento. | Configurabile — Codice non valido, predefinito informazione |
| `BARCODE_NOT_DETECTED` | Codice a barre non rilevato | Non è stato possibile individuare il codice a barre su un documento che dovrebbe averne uno. | Configurabile — Codice non valido, predefinito informazione |
| `BARCODE_VALIDATION_FAILED` | Convalida del codice a barre non riuscita | Non è stato possibile convalidare il contenuto del codice a barre rispetto al resto del documento. | Configurabile — Codice non valido, predefinito informazione |
| `BARCODE_SIGNATURE_INVALID` | Firma del codice a barre non valida | Il codice a barre contiene una firma digitale dell'autorità di emissione e tale firma non è stata verificata: i dati nel codice a barre non corrispondono a quelli firmati dall'autorità, il che indica un documento falsificato o alterato. Attualmente verificato per i codici a barre **francesi 2D-Doc (ANTS)**, dove una firma verificata consente a Didit di considerare attendibili i campi senza richiedere la conferma della MRZ; le firme AAMVA (patenti di guida e documenti di identità di Stati Uniti e Canada) vengono solo rilevate e registrate, ma non ancora applicate. | Fisso - Revisione (gruppo di azioni dedicato `invalid_barcode_signature_action`; non ancora configurabile tramite console/API) |
| `DATA_INCONSISTENT` | I dati OCR nel documento non sono coerenti | I dati estratti da parti diverse del documento non concordano, in genere tra il fronte e il retro dello stesso documento. | Configurabile — Incoerenza dei dati, predefinito informazione |

> [!NOTE]
>
> La verifica della firma del codice a barre copre attualmente le carte d'identità nazionali francesi, il cui codice a barre ANTS 2D-Doc è firmato dall'autorità di emissione. `BARCODE_SIGNATURE_INVALID` viene generato solo quando lo stesso controllo della firma rifiuta il payload. Un codice a barre senza firma, uno firmato da un'autorità non ancora presente nell'archivio delle autorità attendibili di Didit o uno la cui firma non può essere decodificata viene trattato come dato non autenticato e convalidato rispetto alla MRZ e al testo stampato come in precedenza, senza generare questo rischio.
>
> I codici a barre delle patenti di guida statunitensi e canadesi (AAMVA) non sono verificati crittograficamente: la firma digitale in tali contesti è opzionale e specifica per giurisdizione, e nessuna giurisdizione pubblica le chiavi di verifica, quindi Didit rileva e registra solo se un payload presenta una firma; la firma in sé non viene mai controllata. Gli errori di firma AAMVA non costituiscono oggi un segnale di rischio. Un payload AAMVA manomesso emerge solo come `BARCODE_VALIDATION_FAILED`, e solo se la manomissione fa sì che il codice a barre sia in disaccordo con la MRZ o i dati stampati/OCR: una firma falsificata su un payload altrimenti internamente coerente passa senza alcun segnale.
>
> All'utente non viene mai richiesto di ripetere l'acquisizione in caso di `BARCODE_SIGNATURE_INVALID`: una firma che non corrisponde al payload non può essere corretta scattando una foto migliore.

### Corrispondenza dell'identità

| Rischio | Breve descrizione | Causa | Gravità |
| - | - | - | - |
| `ID_DOCUMENT_IN_BLOCKLIST` | Documento d'identità in blocklist | Il documento corrisponde a un documento presente in blocklist (stessa data di nascita, paese di emissione e numero di documento esatto) o a un numero di documento inserito manualmente in blocklist. `additional_data` include il riferimento della sessione in blocklist. | `error` — **rifiutata automaticamente** |
| `ID_DOCUMENT_IN_ALLOWLIST` | Documento d'identità in allowlist | Il numero del documento corrisponde alla tua allowlist di documenti, pertanto l'azione per utente duplicato è stata saltata. `additional_data` include `document_number`. | `information` |
| `POSSIBLE_DUPLICATED_USER` | Possibile utente duplicato da un'altra sessione | Un altro documento nella tua applicazione ha la stessa data di nascita, lo stesso paese di emissione e un nome completo molto simile, associato a un utente diverso (`vendor_data`), indipendentemente dallo stato di quella sessione. `additional_data` include il riferimento della sessione duplicata. | Configurabile — Utente duplicato, predefinito informazione |
| `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS` | Il nome sul documento differisce da altri documenti approvati | Il nome su questo documento differisce da quello dei documenti precedentemente approvati per lo stesso utente. Generato solo per gli account con protocollo Didit (UserKYC), non per le sessioni API standard. | Configurabile — Incoerenza dei dati, predefinito informazione |
| `ID_VERIFICATION_DATA_MISMATCH_BETWEEN_DOCUMENTS` | Discrepanza nei dati tra i documenti di verifica dell'identità | Due documenti d'identità nella stessa sessione non concordano su nome / data di nascita. | Configurabile — Discrepanza dati, impostazione predefinita information |
| `LOW_FRONT_CAMERA_FACE_MATCH_SIMILARITY` | Il selfie durante l'acquisizione del documento non corrisponde al ritratto sul documento | Il volto acquisito dalla fotocamera frontale dell'utente durante l'acquisizione del documento non corrisponde a sufficienza al ritratto presente sul documento. | Basato su soglia: `error` al di sotto della soglia di rifiuto, `warning` pari o al di sotto della soglia di revisione |
| `FRONT_CAMERA_FACE_IN_BLOCKLIST` | Il selfie durante l'acquisizione del documento corrisponde a un volto nella blocklist | Il volto in un selfie scattato dalla fotocamera frontale durante l'acquisizione del documento corrisponde con elevata affidabilità a un volto nella tua blocklist dei volti, sia che tale volto sia stato aggiunto da un controllo di vitalità, dal selfie di acquisizione del documento di un'altra sessione o tramite caricamento. `additional_data` include il riferimento alla sessione da cui proviene il volto nella blocklist (`blocklisted_session_id`, `blocklisted_session_number`) quando il volto nella blocklist proviene da una sessione, e `face_image_source` (`front_image_camera_front` o `back_image_camera_front`) per il selfie che ha generato la corrispondenza. | `error` — **rifiuto automatico** |
| `POSSIBLE_FRONT_CAMERA_FACE_IN_BLOCKLIST` | Il selfie durante l'acquisizione del documento potrebbe corrispondere a un volto nella blocklist | Il volto in un selfie di acquisizione del documento è simile a un volto presente nella tua blocklist dei volti, ma non abbastanza simile da costituire una corrispondenza confermata. Stesso `additional_data` descritto sopra. | `warning` — **sempre Revisione** |
| `FRONT_CAMERA_DUPLICATED_FACE` | Il selfie durante l'acquisizione del documento corrisponde a un utente approvato | Il volto nel selfie scattato dalla fotocamera frontale durante l'acquisizione del documento corrisponde con elevata affidabilità al volto di un utente già approvato nella tua applicazione; pertanto, la stessa persona potrebbe tentare una nuova verifica con un altro account. `additional_data` include la sessione corrispondente (`duplicated_session_id`, `duplicated_session_number`) e `face_image_source` per il selfie che ha generato la corrispondenza. | In base a **Volto duplicato nell'acquisizione silenziosa** (predefinito Approva, `information`) |
| `POSSIBLE_FRONT_CAMERA_DUPLICATED_FACE` | Il selfie durante l'acquisizione del documento potrebbe corrispondere a un utente approvato | Il volto in un selfie di acquisizione del documento è simile al volto di un utente già approvato nella tua applicazione, ma non abbastanza simile da costituire una corrispondenza confermata. Stesso `additional_data` descritto sopra. | In base a **Volto duplicato nell'acquisizione silenziosa** (predefinito Approva, `information`) |
| `FRONT_CAMERA_DUPLICATED_FACE_NAME_MISMATCH` | Il selfie di acquisizione del documento corrisponde a un utente con un nome diverso | Generato in aggiunta a `FRONT_CAMERA_DUPLICATED_FACE` quando l'utente approvato è stato verificato con un nome diverso. `additional_data` aggiunge `name_match_score`; non riporta mai il nome dell'altro utente. | In base a **Duplicato dell'acquisizione silenziosa con nome diverso** (predefinito Revisione, `warning`) |
| `FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH` | Il selfie di acquisizione del documento corrisponde a un utente con una data di nascita diversa | Generato in aggiunta a `FRONT_CAMERA_DUPLICATED_FACE` quando il documento d'identità dell'utente approvato mostra una data di nascita diversa. Un documento diverso della stessa persona (ad esempio un passaporto dopo una carta d'identità), un documento rinnovato o lo stesso numero di documento dello stesso paese non viene segnalato. `additional_data` aggiunge `mismatch_dimensions`, mai i dati del documento dell'altro utente. | In base a **Duplicato dell'acquisizione silenziosa con data di nascita diversa** (predefinito Revisione, `warning`) |
| `FRONT_CAMERA_CAPTURED_DOCUMENT` | La fotocamera frontale ha acquisito un documento d'identità invece dell'utente | Il fotogramma della fotocamera frontale acquisito durante la scansione del documento mostra un documento d'identità (ad esempio una tessera tenuta davanti alla fotocamera) e nessuna persona. Il confronto del selfie di acquisizione del documento non viene calcolato per quel fotogramma. | Sempre **Revisione** |

### Vitalità del documento (manomissione)

Basato su soglie per tipo di frode nei workflow. Sull'API OCR autonoma questi tre rischi comportano il rifiuto incondizionato, e un controllo richiesto che non produce alcun punteggio utilizzabile restituisce `In Review` invece di approvare.

I punteggi stessi sono presenti su ogni report V3 come [`document_liveness`](https://docs.didit.me/it/core-technology/id-verification/report-id-verification#punteggi-del-rilevamento-della-vitalità-del-documento), anche quando non è scattato alcun avviso, consentendo comunque l'audit di un documento approvato.

| Rischio | Descrizione breve | Causa | Gravità |
| - | - | - | - |
| `SCREEN_CAPTURE_DETECTED` | Rilevata acquisizione da schermo del documento | Il documento è stato acquisito da uno schermo anziché da un documento fisico. | `error` al di sotto della soglia di rifiuto, `warning` al di sotto della soglia di revisione, altrimenti `information` |
| `PRINTED_COPY_DETECTED` | Rilevata copia stampata del documento | Il documento sembra essere una copia stampata anziché l'originale. | Stesse soglie a tre livelli |
| `PORTRAIT_MANIPULATION_DETECTED` | Rilevata manipolazione del ritratto | L'area del ritratto sembra essere stata sostituita o alterata. | Stesse soglie a tre livelli |
| `DOCUMENT_LIVENESS_NOT_COMPUTED` | Impossibile calcolare il controllo di vitalità del documento | Il controllo richiesto di vitalità del documento (contraffazione) non ha restituito alcun punteggio utilizzabile — si è verificato un errore del fornitore, ha risposto con codice diverso da 200 o ha risposto con HTTP 200 con `status="ERR"` — pertanto il documento non è mai stato verificato per la sostituzione del ritratto, la copia stampata o la riproduzione da schermo. Un punteggio mancante non è prova della genuinità del documento. Solo API OCR autonoma. | `warning` + `In Review` (non configurabile; non sovrascrive mai un `Declined`) |

### Integrità del canale di acquisizione

| Rischio | Descrizione breve | Causa | Configurabile tramite | Predefinito |
| - | - | - | - | - |
| `INJECTION_ATTACK_DETECTED` | Rilevato attacco di iniezione | L'acquisizione è stata iniettata anziché essere ripresa direttamente dalla fotocamera del dispositivo: una fotocamera virtuale software in grado di riprodurre qualsiasi video, un flusso video generato dalla pagina o tramite automazione del browser, una fotocamera manipolata tramite hook o uno strumento di strumentazione collegato all'applicazione hanno fornito i fotogrammi. `additional_data.reasons` elenca solo i motivi comprovanti, e `source` è `capture_integrity`. Si applica sia all'acquisizione del documento sia al selfie scattato per la ricerca dell'ID. | `id_verification_injection_attack_action` | **Rifiuta** |

Il `log_type` riflette l'azione configurata: `error` per Rifiuta, `warning` per Revisione, `information` per Nessuna azione.
Azione consigliata: tratta una sessione rifiutata come un'acquisizione iniettata e chiedi alla persona di effettuare un nuovo tentativo su un dispositivo fisico con la sua fotocamera integrata.
I segnali che una persona reale può produrre non generano mai `INJECTION_ATTACK_DETECTED` e rimangono informativi.
Le app che trasmettono una fotocamera reale, come un telefono usato come webcam o una sovrapposizione di effetti su una webcam reale, non vengono segnalate come attacchi di iniezione.
Questo è il rilevamento degli attacchi di iniezione, che è distinto dal rilevamento degli attacchi di presentazione (un falso mostrato a una fotocamera reale).

### Immagini di documenti pubblici noti

| Rischio | Descrizione breve | Causa | Gravità |
| - | - | - | - |
| `PUBLIC_DOCUMENT_IMAGE_DETECTED` | Rilevata immagine di documento nota e pubblicamente disponibile su Internet | L'immagine del documento inviata corrisponde a un'immagine Internet nota pubblicamente disponibile (ad esempio un fac-simile, una foto per la stampa o di stock di un documento), pertanto non può essere una foto del documento fisico dell'utente. Il confronto utilizza un'impronta esatta e percettiva (pHash/dHash) rispetto al corpus di Didit di immagini di documenti pubblici noti; `additional_data` include `match_type` (`exact` o `perceptual`), `source`, `source_url` e un `similarity_score` (0-100). | Fissa - Revisione nei workflow; **rifiuto automatico** sull'API autonoma `/id-verification` |

### Mancate corrispondenze con i dettagli previsti

Quando passi `expected_details` a una sessione, Didit genera un avviso di mancata corrispondenza per ogni campo non corrispondente. Un unico raggruppamento (`expected_details_mismatch_action`, predefinito Revisione) controlla l'instradamento per tutti questi casi:

| Rischio | Descrizione breve | Causa |
| - | - | - |
| `FULL_NAME_MISMATCH_WITH_PROVIDED` | Mancata corrispondenza del nome completo con le informazioni fornite | Il nome fornito ottiene un punteggio inferiore alla soglia di corrispondenza del nome rispetto al documento. |
| `DOB_MISMATCH_WITH_PROVIDED` | Mancata corrispondenza della data di nascita con le informazioni fornite | La data di nascita fornita non corrisponde. |
| `GENDER_MISMATCH_WITH_PROVIDED` | Mancata corrispondenza del genere con le informazioni fornite | Il genere fornito non corrisponde. |
| `COUNTRY_MISMATCH_WITH_PROVIDED` | Mancata corrispondenza del paese con le informazioni fornite | Il paese fornito non corrisponde a `issuing_state`. |
| `NATIONALITY_MISMATCH_WITH_PROVIDED` | Mancata corrispondenza della nazionalità con le informazioni fornite | La nazionalità fornita non corrisponde. |
| `IDENTIFICATION_NUMBER_MISMATCH_WITH_PROVIDED` | Mancata corrispondenza del numero di identificazione con le informazioni fornite | Il numero di identificazione fornito non corrisponde al numero del documento, al numero personale o all'identificativo fiscale. |

Ogni avviso di mancata corrispondenza include i valori previsti ed estratti in `additional_data`.

### Età

| Rischio | Descrizione breve | Causa | Gravità |
| - | - | - | - |
| `MINIMUM_AGE_NOT_MET` | Età minima non raggiunta | Il titolare è al di sotto dell'età minima configurata (globale o per paese/stato). `additional_data` include `min_age_allowed` e `user_age`. | Configurabile — Età minima, predefinito Rifiuta (`error`); rifiuto incondizionato sull'API OCR autonoma |
| `MAXIMUM_AGE_EXCEEDED` | Età massima superata | Il titolare è al di sopra dell'età massima configurata. `additional_data` include `max_age_allowed` e `user_age`. | Configurabile — Età massima, predefinito Rifiuta (`error`) |
| `AGE_NOT_DETECTED` | Età non rilevata | Workflow di verifica adattiva dell'età: non è stato possibile estrarre l'età dal documento. | `error` — **rifiuto automatico** |
| `AGE_BELOW_MINIMUM` | Età al di sotto del minimo | Workflow di verifica adattiva dell'età: l'età estratta è inferiore al minimo. | `error` — **rifiuto automatico** |

### Indirizzo

| Rischio | Descrizione breve | Causa | Gravità |
| - | - | - | - |
| `UNPARSED_ADDRESS` | Impossibile determinare la posizione dell'indirizzo | Il documento definisce un campo indirizzo, ma l'indirizzo estratto non ha potuto essere analizzato o geolocalizzato. | Configurabile — Indirizzo non analizzato, predefinito Informazione |

## Corrispondenze di documenti tra sessioni

Oltre agli avvisi sopra indicati, il report V3 di verifica dell'identità include un array `matches[]` — fino a 5 altri documenti nella tua applicazione con la stessa data di nascita, lo stesso paese di emissione e un nome completo altamente simile (i documenti nella blocklist richiedono inoltre una corrispondenza esatta del numero di documento), escluse le sessioni che appartengono allo stesso utente. I documenti aggiunti alla tua blocklist compaiono con `is_blocklisted: true`. I documenti nella tua lista consentita compaiono comunque tra le corrispondenze, ma l'azione associata all'utente duplicato viene ignorata.

Ogni corrispondenza include `session_id`, `session_number`, `vendor_data`, `verification_date`, `user_details` (`name`, `document_type`, `document_number`), `status`, `is_blocklisted`, `api_service` e un `front_image_url` firmato.

## Esempi

### Avviso configurabile con instradamento predefinito (informazione)

```json theme={null}
"warnings": [
  {
    "feature": "ID_VERIFICATION",
    "risk": "QR_NOT_DETECTED",
    "additional_data": null,
    "log_type": "information",
    "short_description": "QR not detected",
    "long_description": "The system couldn't find or read the QR code on the document. This could be due to poor image quality or an unsupported document type.",
    "node_id": "id_primary"
  }
]
```

### Rifiuto automatico per documento scaduto

```json theme={null}
"warnings": [
  {
    "feature": "ID_VERIFICATION",
    "risk": "DOCUMENT_EXPIRED",
    "additional_data": null,
    "log_type": "error",
    "short_description": "Document expired",
    "long_description": "The document's expiration date has passed, rendering it no longer valid for use.",
    "node_id": "id_primary"
  }
]
```

### Mancata corrispondenza dei dettagli previsti con payload

```json theme={null}
"warnings": [
  {
    "feature": "ID_VERIFICATION",
    "risk": "DOB_MISMATCH_WITH_PROVIDED",
    "additional_data": {
      "expected_dob": "1990-01-01",
      "extracted_dob": "1991-03-15"
    },
    "log_type": "warning",
    "short_description": "Date of birth mismatch with provided information",
    "long_description": "The provided date of birth in `expected_details` doesn't match the date extracted from the document.",
    "node_id": "id_primary"
  }
]
```

## Tipi di avviso

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

## Correlati

* [Report di verifica dell'identità](https://docs.didit.me/it/core-technology/id-verification/report-id-verification.md) — schema completo del report e stati.
* [Monitoraggio dei documenti](https://docs.didit.me/it/core-technology/id-verification/document-monitoring-id-verification.md) — come Didit rileva le manomissioni e i duplicati tra sessioni.
* [Webhook](https://docs.didit.me/it/integration/webhooks.md) — `session.status.updated` include gli avvisi non appena il passaggio ID termina.
* [Modelli di dati — Verifica dell'identità](https://docs.didit.me/it/reference/data-models.md#verifica-dell’identità) — schema canonico campo per campo.
* [Modelli di dati — Oggetto 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.