> ## 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. # Prova di residenza: avvisi e codici di errore > Tutti i codici di avviso della Prova di residenza di Didit: discrepanza del nome, documenti scaduti e regole di rifiuto automatico. ## Panoramica La verifica della prova di residenza (POA) emette avvisi su `poa_verifications[].warnings[]` per ogni problema di qualità, autenticità o corrispondenza rilevato durante l'estrazione e l'analisi forense. Ciascun avviso è un [oggetto avviso](https://docs.didit.me/it/reference/data-models.md#oggetto-avviso) con `feature` impostato su `"PROOF_OF_ADDRESS"`. Una manciata di rischi impone sempre `Declined`; i restanti seguono un'azione per singolo rischio (`DECLINE` / `REVIEW` / `NO_ACTION`) configurata nel tuo workflow. Ciascun rischio indicato di seguito è verificato rispetto alla pipeline decisionale di produzione; le stringhe esatte delle descrizioni brevi e lunghe sono riprodotte testualmente nelle tabelle. > [!NOTE] > > L'estrazione POA introduce una latenza di **5–15 secondi** per documento. Gli avvisi vengono registrati solo quando il passaggio del workflow è completato; non effettuare il polling a intervalli inferiori a 5 s. ## Due percorsi di produzione Gli avvisi POA vengono generati su due percorsi diversi e l'insieme dei rischi differisce tra di essi: * **Sessioni di workflow** (il passaggio POA all'interno di una sessione di verifica): l'endpoint di caricamento esegue innanzitutto una validazione bloccante con un ciclo di nuovi tentativi (vedi [Comportamento dei nuovi tentativi](#comportamento-dei-tentativi-sessioni-di-workflow)), quindi gli avvisi finali memorizzati vengono calcolati da `check_poa_risks` insieme al controllo del nome su più documenti. * **API autonoma** (`POST /v3/poa/`): gli avvisi provengono esclusivamente da `check_poa_risks`. Non è presente alcun ciclo di nuovi tentativi, né contesto dell'ID verificato e vi è un solo documento; pertanto `NAME_MISMATCH_ID_VERIFICATION`, `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS`, `POA_MAX_ATTEMPTS_EXCEEDED` e `FUTURE_ISSUE_DATE` non vengono **mai** generati dall'API autonoma. Gli errori di validazione pre-estrazione vengono scartati in questo percorso. `POOR_DOCUMENT_QUALITY` è definito nell'enum dei rischi e riservato nella mappatura delle azioni, ma **nessun percorso di codice nella pipeline POA lo genera**: non compare mai in `warnings[]` in nessuno dei due percorsi. Non gestire rami condizionali su di esso. ## Avvisi con rifiuto automatico (impongono sempre `Declined`) Questi rischi rientrano in `AUTO_DECLINE_RISKS`; quando vengono registrati, lo stato della POA è `Declined` a prescindere dalla configurazione, e `log_type` è sempre `error`. | Rischio | Causa | Risoluzione consigliata | | - | - | - | | `MISSING_ADDRESS_INFORMATION` | Non è stato possibile estrarre alcun indirizzo dal documento. | Chiedi all'utente di inviare nuovamente un documento che mostri chiaramente il proprio indirizzo. | | `POA_DOCUMENT_EXPIRED` | Il documento è scaduto secondo uno dei due percorsi: la sua **data di scadenza stampata** è trascorsa oppure è **più vecchio dell'età massima configurata** per la sua tipologia. Valori predefiniti: **3 mesi** per `UTILITY_BILL` e `BANK_STATEMENT`, **12 mesi** per `GOVERNMENT_ISSUED_DOCUMENT` e `OTHER_POA_DOCUMENT` (un mese equivale a 30 giorni; `-1` disabilita il controllo). `additional_data` include sempre `expiration_reason` (`printed_expiration` o `age_window`), `document_type`, `document_subtype` e `issue_date`; il percorso `printed_expiration` aggiunge `expiration_date`, mentre il percorso `age_window` aggiunge `max_age_months`. | Chiedi all'utente un documento valido o più recente, oppure aumenta `age_months` per quel tipo. | | `INVALID_DOCUMENT_TYPE` | Non è stato possibile classificare il documento in alcun tipo di POA supportato (`document_type` viene impostato su `UNKNOWN`). | Chiedi all'utente di inviare nuovamente il documento; verifica che il file non sia danneggiato. | | `UNABLE_TO_VALIDATE_DOCUMENT_AGE` | Il controllo dell'età del documento non è riuscito (errore durante il calcolo della scadenza a partire dalla data di emissione). | Chiedi all'utente un documento con una data di emissione chiaramente leggibile. | Anche `FUTURE_ISSUE_DATE` è presente in `AUTO_DECLINE_RISKS`, ma ha un solo generatore nella validazione pre-estrazione (una data di emissione successiva di oltre 7 giorni rispetto alla data odierna) i cui errori alimentano esclusivamente il **ciclo di nuovi tentativi del workflow**: in quel caso si presenta come un errore di caricamento bloccante, non viene mai generato dall'API autonoma e non viene scritto in `warnings[]`. Vedi [Comportamento dei nuovi tentativi](#comportamento-dei-tentativi-sessioni-di-workflow). ## Avvisi configurabili Ciascuno di questi avvisi segue un'impostazione di azione del nodo POA del workflow (`DECLINE` / `REVIEW` / `NO_ACTION`). Il `log_type` dell'avviso riflette l'azione configurata: `error` per Rifiuta, `warning` per Revisione, `information` per Nessuna azione. | Rischio | Causa | Impostazione di azione | Predefinito | | - | - | - | - | | `NAME_MISMATCH_WITH_PROVIDED` | Il nome sul documento ottiene un punteggio inferiore a `poa_name_match_score_threshold` (predefinito 86) rispetto al nome fornito alla creazione della sessione (`expected_details`). | `poa_name_or_address_mismatch_action` | Revisione | | `NAME_MISMATCH_ID_VERIFICATION` | Il nome sul documento ottiene un punteggio inferiore alla soglia rispetto al documento d'identità verificato. `additional_data`: `{ poa_name, kyc_name, match_score }`. Solo per le sessioni workflow. | `poa_name_or_address_mismatch_action` | Revisione | | `ADDRESS_MISMATCH_WITH_PROVIDED` | L'indirizzo estratto è diverso dall'indirizzo fornito tramite API, oppure uno dei due indirizzi non può essere verificato come indirizzo residenziale. | `poa_name_or_address_mismatch_action` | Revisione | | `POA_COUNTRY_MISMATCH_WITH_PROVIDED` | Il paese del documento non corrisponde al paese fornito tramite API (normalizzato in ISO-3). `additional_data`: `{ expected_country, extracted_country }`. | `poa_name_or_address_mismatch_action` | Revisione | | `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS` | Due o più documenti POA nella stessa sessione riportano nomi diversi. `additional_data` include entrambi gli ID dei nodi, entrambi i nomi e il punteggio di corrispondenza. Solo per le sessioni workflow. | `poa_name_or_address_mismatch_action` | Revisione | | `DOCUMENT_METADATA_MISMATCH` | Il file è vuoto (`file_size` 0) oppure le date EXIF sono malformate. | `poa_document_issues_action` | Revisione | | `SUSPECTED_DOCUMENT_MANIPULATION` | L'analisi forense ha rilevato prove di manipolazione: modifica dopo la firma digitale (`is_tampered`), manipolazione del testo sovrapposto (con i rettangoli `additional_data.manipulated_regions`), un noto editor PDF, date EXIF incoerenti oppure una riesportazione sospetta. `additional_data.detection_method` indica il controllo che ha generato l'avviso. | `poa_document_authenticity_action` | **Rifiuta** | | `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` | Un campo di testo è stato cancellato e riscritto con un altro carattere, ma il file non contiene alcuna prova che consenta di stabilire se il contenuto sia cambiato: anche gli editor online riscrivono il testo non modificato. Questo avviso non genera mai da solo `SUSPECTED_DOCUMENT_MANIPULATION`; se un altro segnale genera quest'ultimo sullo stesso documento, decide l'azione più severa tra le due. `additional_data.detection_method` è `unproven_text_replacement`, con `replaced_text` e `manipulated_regions`. Anche un file che non è stato controllato per intero genera questo avviso, perché la parte non controllata potrebbe contenere un campo del genere: in tal caso `detection_method` è `analysis_incomplete`, con `replaced_text` e `manipulated_regions` vuoti, a meno che un campo non sia stato trovato nella parte controllata. | `poa_document_unproven_text_replacement_action` | Revisione | | `UNSUPPORTED_DOCUMENT_LANGUAGE` | La lingua del documento non è inclusa in `poa_languages_allowed`. | `poa_unsupported_language_action` | **Rifiuta** | | `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | Il tipo di documento rilevato non è abilitato in `poa_documents_allowed` per il paese del documento, oppure il suo sottotipo è disabilitato esplicitamente. | `poa_unsupported_document_type_action` | **Rifiuta** | | `ISSUER_NOT_IDENTIFIED` | L'istituto emittente non può essere identificato dal documento. | `poa_issuer_not_identified_action` | Revisione | | `UNABLE_TO_EXTRACT_ISSUE_DATE` | Nel documento non è stata trovata una data di emissione valida. | `poa_issue_date_not_detected_action` | Revisione | | `POA_NAME_NOT_DETECTED` | Nel documento non è stato rilevato alcun nome. | `poa_issue_date_not_detected_action` (impostazione condivisa) | Revisione | | `UNPARSABLE_OR_INVALID_ADDRESS` | È stato estratto un indirizzo, ma non può essere analizzato e geocodificato come indirizzo residenziale valido. | `poa_unparsable_or_invalid_address_action` | Revisione | | `POA_MAX_ATTEMPTS_EXCEEDED` | L'utente ha esaurito `poa_max_retry_attempts` (predefinito 2) nel ciclo di nuovi tentativi del workflow. `additional_data`: `{ attempts }`. Solo per le sessioni workflow. | `poa_max_attempts_exceeded_action` | **Rifiuta** | > [!NOTE] > > C'è **un'unica azione condivisa** per tutte le discrepanze di nome e indirizzo: `poa_name_or_address_mismatch_action` copre entrambi i rischi relativi al nome, entrambi i rischi relativi all'indirizzo e il controllo incrociato dei nomi tra documenti. Non è possibile configurare separatamente il comportamento per le discrepanze di nome e quello per le discrepanze di indirizzo. Sull'API standalone lo stesso gruppo segue l'opzione della richiesta `poa_address_mismatch_action` (l'opzione `poa_name_mismatch_action` è accettata ma non viene mai letta). ## Differenze dell'API standalone (`POST /v3/poa/`) L'endpoint standalone crea la stessa mappatura rischio-azione ma con opzioni a livello di richiesta che accettano solo `DECLINE` o `NO_ACTION` (tutte con valore predefinito `DECLINE`): * `UNABLE_TO_EXTRACT_ISSUE_DATE` e `POA_NAME_NOT_DETECTED` sono **impostati rigidamente su Rifiuta** su questo endpoint. * `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` e `UNPARSABLE_OR_INVALID_ADDRESS` sono **informativi** in questo caso; le loro azioni sono predefinite su Nessuna azione e non sono configurabili per richiesta. * `FUTURE_ISSUE_DATE`, `POOR_DOCUMENT_QUALITY`, `NAME_MISMATCH_ID_VERIFICATION`, `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS` e `POA_MAX_ATTEMPTS_EXCEEDED` non vengono mai generati; un documento con data futura **non** viene rifiutato automaticamente su questo endpoint. Consulta il [riferimento API di POST /v3/poa/](https://docs.didit.me/it/standalone-apis/proof-of-address.md) per le opzioni di richiesta. ## Comportamento dei tentativi (sessioni di workflow) In una sessione di verifica, il passaggio di caricamento della POA esegue una convalida bloccante prima che il documento venga accettato. Quando rileva un errore bloccante — `INVALID_DOCUMENT_TYPE`, `UNABLE_TO_EXTRACT_ISSUE_DATE`, `FUTURE_ISSUE_DATE`, `POA_NAME_NOT_DETECTED`, `MISSING_ADDRESS_INFORMATION`, `POA_COUNTRY_MISMATCH_WITH_PROVIDED`, `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`, `UNSUPPORTED_DOCUMENT_LANGUAGE` o `POA_DOCUMENT_EXPIRED` — il caricamento viene rifiutato con `400` e il codice di rischio come messaggio, e l'utente può riprovare con un documento migliore. Per `POA_DOCUMENT_EXPIRED`, il corpo della risposta `400` include anche `expiration_reason` (`printed_expiration` o `age_window`) in modo che la tua interfaccia utente possa mostrare il motivo preciso; nel percorso `age_window` include inoltre `max_age_months`. Nel percorso `printed_expiration`, `max_age_months` viene intenzionalmente omesso, poiché il documento è stato rifiutato per la data di scadenza stampata anziché per una finestra temporale di validità. Una volta che l'utente ha esaurito i tentativi previsti da `poa_max_retry_attempts` (predefinito 2, configurabile tra 2 e 5), l'invio viene comunque accettato: gli avvisi memorizzati vengono ricalcolati a partire dal documento salvato, viene aggiunto `POA_MAX_ATTEMPTS_EXCEEDED` e lo stato viene risolto in base all'intero insieme di rischi. Questo è il motivo per cui `FUTURE_ISSUE_DATE` può bloccare un caricamento senza mai comparire in `warnings[]`. ## Impostazioni configurabili Il nodo POA del workflow espone queste opzioni (corrispondenti ai campi di `VerificationSettings`): | Impostazione | Controlla | Predefinito | | - | - | - | | `poa_name_or_address_mismatch_action` | `NAME_MISMATCH_WITH_PROVIDED`, `NAME_MISMATCH_ID_VERIFICATION`, `ADDRESS_MISMATCH_WITH_PROVIDED`, `POA_COUNTRY_MISMATCH_WITH_PROVIDED`, `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS` | Revisione | | `poa_document_issues_action` | `DOCUMENT_METADATA_MISMATCH` | Revisione | | `poa_document_authenticity_action` | `SUSPECTED_DOCUMENT_MANIPULATION` | Rifiuto | | `poa_document_unproven_text_replacement_action` | `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` | Revisione (un workflow che non prevede mai la revisione utilizza il proprio `poa_document_authenticity_action` quando questo è Rifiuto, altrimenti Nessuna azione; l'API indipendente segue il parametro `poa_document_authenticity_action` della richiesta) | | `poa_unsupported_language_action` | `UNSUPPORTED_DOCUMENT_LANGUAGE` | Rifiuto | | `poa_unsupported_document_type_action` | `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | Rifiuto | | `poa_issuer_not_identified_action` | `ISSUER_NOT_IDENTIFIED` | Revisione | | `poa_issue_date_not_detected_action` | `UNABLE_TO_EXTRACT_ISSUE_DATE`, `POA_NAME_NOT_DETECTED` | Revisione | | `poa_unparsable_or_invalid_address_action` | `UNPARSABLE_OR_INVALID_ADDRESS` | Revisione | | `poa_max_attempts_exceeded_action` | `POA_MAX_ATTEMPTS_EXCEEDED` | Rifiuto | | `poa_documents_allowed` | Tipi di documenti accettati per paese, ciascuno con `enabled` e `age_months` (`-1` = illimitato); override per sottotipo tramite `document_subtypes_config`. | Bolletta ed estratto conto bancario: 3 mesi; documenti rilasciati dal governo e altri documenti: 12 mesi | | `poa_languages_allowed` | Lingue del documento accettate. | Tutte le lingue supportate | | `poa_name_match_score_threshold` | Punteggio minimo di corrispondenza del nome (0–100) prima che scattino i rischi `NAME_MISMATCH*`. | 86 | | `poa_max_retry_attempts` | Tentativi di caricamento prima che il ciclo di nuovi tentativi si interrompa (2–5). | 2 | ## Logica di corrispondenza del nome La corrispondenza del nome nella POA tollera le variazioni più comuni: * **Secondi nomi e iniziali** vengono confrontati con tolleranza (la presenza/assenza è consentita). * **Nomi candidati** — ogni nome rilevato sul documento (`name_on_document` più `additional_names`) riceve un punteggio e viene mantenuto il candidato con il punteggio migliore. * **Soglia di corrispondenza** — la soglia predefinita `poa_name_match_score_threshold` è **86**; un punteggio inferiore attiva il relativo avviso `NAME_MISMATCH*`. I punteggi numerici sono esposti nel report come `name_match_score_expected_details` e `name_match_score_id_verification` (0–100). I valori del punteggio sono utili per una revisione dettagliata anche quando non è stato generato alcun avviso. ## Esempi ### Manipolazione tramite overlay (Rifiuto per impostazione predefinita) ```json theme={null} { "warnings": [ { "feature": "PROOF_OF_ADDRESS", "risk": "SUSPECTED_DOCUMENT_MANIPULATION", "additional_data": { "reason": "Overlay-text manipulation detected: same base font embedded with multiple subset prefixes on 1 page(s).", "detection_method": "overlay_text_manipulation", "signals": ["duplicate_font_subset", "glyph_fragmentation"], "duplicate_font_subsets": [{ "page": 1, "base_font": "Helvetica" }], "fragmented_fonts": [], "manipulated_regions": [ { "page": 1, "x": 102.4, "y": 318.1, "width": 187.0, "height": 18.0, "page_width": 595, "page_height": 842 } ] }, "log_type": "error", "short_description": "Suspected document manipulation", "long_description": "The system detected signs of potential document manipulation or editing.", "node_id": "feature_poa_1" } ] } ``` ### Documento scaduto + indirizzo mancante (rifiuto automatico) ```json theme={null} { "warnings": [ { "feature": "PROOF_OF_ADDRESS", "risk": "POA_DOCUMENT_EXPIRED", "additional_data": { "expiration_reason": "age_window", "max_age_months": 3, "document_subtype": "ELECTRICITY_BILL", "document_type": "UTILITY_BILL", "issue_date": "2025-11-02" }, "log_type": "error", "short_description": "Document expired", "long_description": "The submitted document is older than the maximum accepted age of 3 months from its issue date, which exceeds the acceptable time period for validity.", "node_id": "feature_poa_1" }, { "feature": "PROOF_OF_ADDRESS", "risk": "MISSING_ADDRESS_INFORMATION", "additional_data": null, "log_type": "error", "short_description": "Missing address information", "long_description": "The document does not contain complete or clear address information that can be extracted.", "node_id": "feature_poa_1" } ] } ``` ### Mancata corrispondenza del nome (Revisione per impostazione predefinita) ```json theme={null} { "warnings": [ { "feature": "PROOF_OF_ADDRESS", "risk": "NAME_MISMATCH_ID_VERIFICATION", "additional_data": { "poa_name": "JOHN B SMYTH", "kyc_name": "John A. Smith", "match_score": 60 }, "log_type": "warning", "short_description": "Name mismatch with ID verification", "long_description": "The full name on the document does not match the name from the user's verified identity documents.", "node_id": "feature_poa_1" } ] } ``` ## Correlati * [Report della prova di residenza](https://docs.didit.me/it/core-technology/proof-of-address/report-proof-of-address.md) — formato completo della risposta, analisi forense delle manipolazioni tramite overlay, semantica dello stato * [Panoramica sulla prova di residenza](https://docs.didit.me/it/core-technology/proof-of-address/overview.md) — tipi di documenti accettati * [Modelli di dati — Prova di residenza](https://docs.didit.me/it/reference/data-models.md#prova-di-residenza) — schema canonico e oggetto Warning * [Webhook](https://docs.didit.me/it/integration/webhooks.md) — `status.updated` include gli avvisi della POA ### Tipi di avviso This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.