> ## 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. # API Prova di residenza: verifica POA e OCR > Didit verifica utenze, estratti conto e contratti di locazione con POST /v3/poa/. OCR indirizzo, controlli di autenticità, prezzo a consumo. ## OpenAPI ````yaml it/openapi-25.json POST /v3/poa/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API di verifica dell'identità. Autenticati con l'intestazione x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/poa/: post: tags: - Standalone APIs summary: Prova di residenza (OCR documento + controlli indirizzo) description: >- Estrai e convalida un documento di Prova di residenza — bollette delle utenze, estratti conto bancari e documenti rilasciati dal governo — in un'unica chiamata. Restituisce l'emittente, le date di emissione/scadenza, il nome dell'intestatario, l'indirizzo grezzo e analizzato/geocodificato, uno `status` `Approved`/`Declined` e un elenco `warnings` che illustra ogni problema riscontrato. **Latenza.** L'estrazione è basata su LLM: le chiamate tipiche richiedono **5–15 secondi**, i PDF multipagina fino a **~30 secondi**. Configura un timeout del client di **almeno 45 secondi** e non effettuare un nuovo tentativo prima del completamento della chiamata. **Come funziona.** Il documento (immagine o PDF, fino a 15 MB; i PDF crittografati richiedono `document_password`) viene classificato in un tipo e sottotipo di documento (ad es. `UTILITY_BILL` / `WATER_BILL`), e l'emittente, le date, il nome dell'intestatario e l'indirizzo vengono estratti tramite estrazione basata su LLM. L'indirizzo viene analizzato e geocodificato in `poa_parsed_address`. Le analisi forensi su PDF/EXIF verificano la presenza di manomissioni — modifiche successive alla firma digitale, editor PDF noti, manipolazione del testo in sovrimpressione, riesportazioni sospette — segnalando `SUSPECTED_DOCUMENT_MANIPULATION` o `DOCUMENT_METADATA_MISMATCH`. Un campo di testo cancellato e riscritto con un altro font, nei casi in cui il file stesso non contenga prove sull'eventuale modifica del contenuto, genera `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`. L'anzianità del documento viene convalidata rispetto a `poa_document_age_months`, e la lingua rispetto a `poa_languages_allowed`. Se passi `expected_address`, `expected_country` o `expected_first_name`/`expected_last_name`, i valori estratti vengono confrontati e le discrepanze vengono segnalate. **Logica di decisione.** `status` è `Approved` a meno che almeno un avviso non si risolva in un rifiuto. Gli errori critici comportano sempre un rifiuto: `MISSING_ADDRESS_INFORMATION`, `POA_DOCUMENT_EXPIRED`, `INVALID_DOCUMENT_TYPE`, `UNABLE_TO_VALIDATE_DOCUMENT_AGE`, oltre a `UNABLE_TO_EXTRACT_ISSUE_DATE` e `POA_NAME_NOT_DETECTED` (non configurabili su questo endpoint). Cinque gruppi di rischio sono configurabili per richiesta tramite le opzioni `poa_*_action` (`DECLINE` o `NO_ACTION`, tutte impostate in modo predefinito su `DECLINE`). `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` e `UNPARSABLE_OR_INVALID_ADDRESS` sono informativi su questo endpoint e non comportano mai un rifiuto. Un documento che non può essere elaborato affatto restituisce `400`; un documento leggibile ma problematico restituisce `200` con `status: "Declined"` — esamina sempre `poa.status` e `poa.warnings`, non solo il codice HTTP. **Fatturazione.** Ogni risposta `200` consuma un credito API di Prova di residenza (scalato dai crediti del tuo piano o dal saldo delle ricariche). Quando il saldo dell'organizzazione non è sufficiente a coprire la chiamata, l'endpoint restituisce `403` con l'errore di credito insufficiente prima di qualsiasi elaborazione del documento. **Persistenza della sessione (`save_api_request`, default `true`).** Quando è `true`, la chiamata viene salvata come sessione di tipo API: appare nella Business Console, il documento caricato viene archiviato, il `request_id` restituito è un vero ID sessione che puoi passare a `GET /v3/session/{sessionId}/decision/` (la decisione espone inoltre `document_file` e le analisi forensi di `document_metadata`, che questa risposta omette) e viene emesso un webhook `status.updated`. Quando è `false`, nulla viene archiviato e `request_id` è un UUID di correlazione monouso che non può essere cercato in seguito. **Sandbox.** Le chiavi API sandbox ignorano qualsiasi elaborazione e fatturazione: dopo la convalida della richiesta (l'input malformato restituisce comunque `400`), l'endpoint restituisce un payload fittizio statico `Approved` (una bolletta elettrica fittizia di "Sandbox Power Co."), nessuna sessione viene salvata e non viene consumato alcun credito. **Autenticazione.** Invia la chiave API della tua applicazione nell'intestazione `x-api-key`. Credenziali mancanti o non valide restituiscono `403` (`{"detail": "You do not have permission to perform this action."}`) — questa API non restituisce mai `401`. **Limite di frequenza.** Budget di scrittura condiviso di 300 richieste/min per chiave API su tutti gli endpoint POST/PATCH/DELETE; il superamento restituisce `429`. Nota: `FUTURE_ISSUE_DATE` e `POOR_DOCUMENT_QUALITY` sono presenti nelle sessioni di workflow ma non vengono mai generati da questo endpoint autonomo — un documento con data futura non viene rifiutato automaticamente in questo caso. operationId: post_v3poa parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - document properties: document: type: string format: binary description: >- Il documento di Prova di residenza. Estensioni consentite: `tiff`, `jpg`, `jpeg`, `png`, `pdf`, `webp`. Dimensione massima di caricamento: **15 MB** (i file più grandi vengono rifiutati con `400`). I PDF multipagina sono supportati (è prevista una latenza maggiore); i PDF crittografati richiedono `document_password`. Le immagini vengono compresse automaticamente prima dell'elaborazione. document_password: type: string description: >- Password per decrittografare `document` quando è un PDF crittografato. L'invio di un PDF crittografato senza password (o con una errata) restituisce `400`. writeOnly: true expected_address: type: string description: >- Indirizzo da verificare a fronte del documento. Viene geocodificato e confrontato con l'indirizzo estratto; una mancata corrispondenza (o un indirizzo previsto che non può essere geocodificato/verificato) aggiunge `ADDRESS_MISMATCH_WITH_PROVIDED`, regolato da `poa_address_mismatch_action`. La forma geocodificata viene restituita in `expected_details_formatted_address` / `expected_details_parsed_address`. example: Av. Monseñor Tavella 1291, Salta, Argentina expected_country: type: string description: >- Paese da verificare rispetto al documento (codice ISO 3166-1, ad es. `ARG` o `AR`). Una mancata corrispondenza con il paese del documento aggiunge `POA_COUNTRY_MISMATCH_WITH_PROVIDED`, regolata da `poa_address_mismatch_action`. example: ARG expected_first_name: type: string description: >- Nome da verificare a fronte di `name_on_document` (confronto fuzzy, tiene conto della traslitterazione). Un punteggio inferiore alla soglia di corrispondenza aggiunge `NAME_MISMATCH_WITH_PROVIDED`, gestito da `poa_address_mismatch_action`. example: Sophia expected_last_name: type: string description: >- Cognome da verificare rispetto a `name_on_document`, combinato con `expected_first_name` per il punteggio di corrispondenza. example: Martinez poa_languages_allowed: type: string description: >- Elenco separato da virgole delle lingue dei documenti accettate come codici ISO 639-1 (ad es. `en,es,fr`). Se omesso o vuoto, vengono accettate **tutte le 51 lingue supportate**. Un documento in una lingua non inclusa nell'elenco aggiunge `UNSUPPORTED_DOCUMENT_LANGUAGE` (regolato da `poa_unsupported_language_action`); un codice sconosciuto nell'elenco restituisce `400` con l'insieme completo dei codici supportati. example: en,es poa_document_age_months: type: string description: >- Coppie `key:value` separate da virgole che impostano l'età massima del documento in mesi per ciascun tipo di documento — chiavi: `utility_bill`, `bank_statement`, `government_issued_document`, `other_poa_document`; valori: `1`–`120`, oppure `-1` per illimitato (nessun controllo dell'età). Valori predefiniti se omesso: `utility_bill:3,bank_statement:3,government_issued_document:12,other_poa_document:12`. Un documento più vecchio del relativo limite viene rifiutato con `POA_DOCUMENT_EXPIRED`. **Attenzione:** quando fornisci questo campo, elenca *ogni* tipo che accetti: i tipi omessi vengono considerati non accettati (`POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` informativo) e il loro controllo dell'età viene saltato. example: utility_bill:3,bank_statement:6 poa_name_mismatch_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Accettato ma **attualmente non applicato** — gli avvisi di mancata corrispondenza del nome (`NAME_MISMATCH_WITH_PROVIDED`) seguono invece `poa_address_mismatch_action`. Imposta `poa_address_mismatch_action` per controllare il comportamento di mancata corrispondenza sia del nome che dell'indirizzo. poa_document_issues_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Cosa fare in caso di problemi di integrità del file — in pratica questo endpoint genera solo `DOCUMENT_METADATA_MISMATCH`. poa_document_authenticity_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Cosa fare quando si sospetta una manipolazione del documento (`SUSPECTED_DOCUMENT_MANIPULATION`) — ad esempio se il PDF è stato modificato dopo la firma digitale, elaborato da un editor PDF noto, mostra una manipolazione del testo in sovrimpressione o presenta date EXIF incoerenti. Regola anche `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` (un campo di testo ridigitato per il quale il file non può dimostrare se sia stato modificato o meno): `DECLINE` rifiuta anche questo, `NO_ACTION` lo mantiene come avviso. poa_unsupported_language_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Cosa fare quando la lingua del documento è al di fuori di `poa_languages_allowed` (`UNSUPPORTED_DOCUMENT_LANGUAGE`). poa_address_mismatch_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Cosa fare quando i dettagli estratti non concordano con i campi `expected_*`: `ADDRESS_MISMATCH_WITH_PROVIDED`, `NAME_MISMATCH_WITH_PROVIDED` e `POA_COUNTRY_MISMATCH_WITH_PROVIDED` seguono tutti questa azione. poa_issuer_not_identified_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Cosa fare quando non è possibile identificare alcuna azienda/organizzazione emittente sul documento (`ISSUER_NOT_IDENTIFIED`). save_api_request: type: boolean default: true description: >- Quando è `true` (predefinito), rende persistente la chiamata come sessione di tipo API — visibile nella Business Console, recuperabile tramite `GET /v3/session/{sessionId}/decision/` utilizzando il `request_id` restituito, notificata tramite un webhook `status.updated`, e con il documento caricato che viene archiviato. Quando è `false`, non viene memorizzato nulla e `request_id` è un UUID temporaneo utilizzabile solo per la correlazione della risposta. example: true vendor_data: type: string description: >- Stringa opaca opzionale (il tuo ID utente interno, email, UUID...) memorizzata nella sessione persistita e restituita nella risposta. Usala per correlare le chiamate API con i tuoi record e per filtrare le sessioni in un secondo momento. example: user-123 metadata: type: object additionalProperties: true description: >- Oggetto JSON opzionale memorizzato con la sessione (quando `save_api_request=true`) e restituito nella risposta. Nelle richieste multipart, invialo come campo stringa con codifica JSON (ad es. `metadata={"flow":"onboarding"}`): viene interpretato come oggetto. example: flow: onboarding example: document: (binary JPEG/PNG/PDF of the utility bill or bank statement) expected_address: Av. Monseñor Tavella 1291, Salta, Argentina expected_country: ARG expected_first_name: Sophia expected_last_name: Martinez poa_languages_allowed: en,es save_api_request: true vendor_data: user-123 responses: '200': description: >- Documento elaborato. `poa.status` è `Approved` o `Declined`; ogni problema rilevato è dettagliato in `poa.warnings`. Un documento scaduto, non corrispondente o sospetto restituisce comunque `200` con `status: "Declined"` — esamina il corpo, non solo il codice HTTP. Quando `save_api_request=true`, `request_id` è l'ID di sessione persistito. content: application/json: examples: Approved: summary: >- Bolletta di utenza letta correttamente, nessun controllo dei dettagli previsti value: request_id: 4b523a8d-ed32-45e4-8aa8-a89eda459d88 poa: issuing_state: ARG document_type: UTILITY_BILL document_subtype: WATER_BILL document_language: es issuer: Aguas del Norte issue_date: '2026-04-10' expiration_date: null poa_address: >- AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA poa_formatted_address: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: street_1: Avenida Monseñor Tavella 1291 street_2: b city: Salta region: Salta country: AR postal_code: A4400 document_location: latitude: -24.8208682 longitude: -65.4130954 expected_details_address: null expected_details_formatted_address: null expected_details_parsed_address: null name_on_document: OESTE EMBOTELLADORA S.A. extra_fields: bank_account_number: null bank_iban: null bank_sort_code: null bank_routing_number: null bank_swift_bic: null bank_branch_name: null bank_branch_address: null document_phone_number: null additional_names: - LA EMBOTELLADORA DEL NORTE SA detected_codes: - type: QR_CODE page_number: 1 position: - - 820 - 1120 - - 1002 - 1120 - - 1002 - 1302 - - 820 - 1302 x: 820 'y': 1120 width: 182 height: 182 page_width: 1190 page_height: 1684 raw_payload: >- aHR0cHM6Ly9hZ3Vhc2RlbG5vcnRlLmNvbS9mYWN0dXJhLzk5ODgxMQ== parsed_payload: https://aguasdelnorte.com/factura/998811 - type: CODE_128 page_number: 1 position: - - 112 - 1480 - - 560 - 1480 - - 560 - 1540 - - 112 - 1540 x: 112 'y': 1480 width: 448 height: 60 page_width: 1190 page_height: 1684 raw_payload: MDA5OTg4MTEwMDA0Mg== parsed_payload: '0099881100042' status: Approved warnings: [] vendor_data: user-123 metadata: null created_at: '2026-06-12T02:29:02.439655+00:00' Declined - document too old: summary: >- Data di emissione antecedente rispetto al parametro `poa_document_age_months` consentito value: request_id: f61681b8-9422-4378-ac3e-04c6a247fb45 poa: issuing_state: ARG document_type: UTILITY_BILL document_subtype: WATER_BILL document_language: es issuer: Aguas del Norte issue_date: '2021-02-10' expiration_date: null poa_address: >- AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA poa_formatted_address: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: street_1: Avenida Monseñor Tavella 1291 street_2: b city: Salta region: Salta country: AR postal_code: A4400 document_location: latitude: -24.8208682 longitude: -65.4130954 expected_details_address: null expected_details_formatted_address: null expected_details_parsed_address: null name_on_document: OESTE EMBOTELLADORA S.A. extra_fields: bank_account_number: null bank_iban: null bank_sort_code: null bank_routing_number: null bank_swift_bic: null bank_branch_name: null bank_branch_address: null document_phone_number: null additional_names: - LA EMBOTELLADORA DEL NORTE SA status: Declined warnings: - risk: POA_DOCUMENT_EXPIRED feature: PROOF_OF_ADDRESS additional_data: expiration_reason: age_window max_age_months: 3 document_subtype: WATER_BILL document_type: UTILITY_BILL issue_date: '2021-02-10' 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. vendor_data: user-123 metadata: null created_at: '2026-06-12T02:23:02.165493+00:00' Declined - name mismatch: summary: >- `expected_first_name`/`expected_last_name` non corrispondono a `name_on_document` value: request_id: 0a7f2f9c-58f1-4b8e-b1e3-2f6f9d4f7a21 poa: issuing_state: ARG document_type: UTILITY_BILL document_subtype: WATER_BILL document_language: es issuer: Aguas del Norte issue_date: '2021-02-10' expiration_date: null poa_address: >- AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA poa_formatted_address: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: street_1: Avenida Monseñor Tavella 1291 street_2: b city: Salta region: Salta country: AR postal_code: A4400 document_location: latitude: -24.8208682 longitude: -65.4130954 expected_details_address: null expected_details_formatted_address: null expected_details_parsed_address: null name_on_document: OESTE EMBOTELLADORA S.A. extra_fields: bank_account_number: null bank_iban: null bank_sort_code: null bank_routing_number: null bank_swift_bic: null bank_branch_name: null bank_branch_address: null document_phone_number: null additional_names: - LA EMBOTELLADORA DEL NORTE SA status: Declined warnings: - risk: NAME_MISMATCH_WITH_PROVIDED feature: PROOF_OF_ADDRESS additional_data: null log_type: error short_description: Name mismatch with provided information long_description: >- The full name on the document does not match the name from the user's verified identity documents, or the full name sent by API. vendor_data: user-123 metadata: null created_at: '2026-06-12T02:27:21.330172+00:00' schema: type: object properties: request_id: type: string format: uuid description: >- ID della sessione salvata quando `save_api_request=true` (utilizzabile con `GET /v3/session/{sessionId}/decision/`); altrimenti un UUID di correlazione temporaneo. poa: type: object properties: status: type: string enum: - Approved - Declined description: >- `Approved` quando nessun avviso si traduce in un rifiuto; altrimenti `Declined`: l'elenco `warnings` ne spiega il motivo. issuing_state: type: string nullable: true description: >- Paese in cui è stato rilasciato il documento, come estratto dal documento stesso — di solito ISO 3166-1 alpha-3 (ad es. `ARG`). example: ARG document_type: type: string enum: - UTILITY_BILL - BANK_STATEMENT - GOVERNMENT_ISSUED_DOCUMENT - OTHER_POA_DOCUMENT - UNKNOWN description: >- Categoria del documento rilevata. `UNKNOWN` indica che il documento non ha potuto essere classificato come una Prova di residenza accettabile e viene rifiutata automaticamente con `INVALID_DOCUMENT_TYPE`. Mai null: gli errori di classificazione ripiegano su `UNKNOWN`. document_subtype: type: string description: >- Classificazione più dettagliata all'interno di `document_type` — ad es. `ELECTRICITY_BILL`, `WATER_BILL`, `GAS_BILL`, `INTERNET_BILL`, `PHONE_BILL` (bollette delle utenze); `ACCOUNT_STATEMENT`, `CREDIT_CARD_STATEMENT` (estratti conto bancari); `TAX_ASSESSMENT`, `RESIDENCY_CERTIFICATE` (documenti governativi). `UNKNOWN` quando non è stato possibile determinare alcun sottotipo. Mai nullo — gli errori di classificazione ricadono su `UNKNOWN`. example: WATER_BILL document_language: type: string nullable: true description: Lingua del documento rilevata (ISO 639-1). example: es issuer: type: string nullable: true description: >- Azienda o organizzazione che ha emesso il documento. `null` aggiunge `ISSUER_NOT_IDENTIFIED`. example: Aguas del Norte issue_date: type: string format: date nullable: true description: >- Data di emissione del documento (`YYYY-MM-DD`). `null` quando non è stato possibile estrarla — comporta il rifiuto con `UNABLE_TO_EXTRACT_ISSUE_DATE` su questo endpoint. example: '2021-02-10' expiration_date: type: string format: date nullable: true description: >- Data di scadenza/validità esplicita stampata sul documento, se presente. Indipendente dal controllo dell'età `poa_document_age_months`. poa_address: type: string nullable: true description: >- Indirizzo esattamente come stampato sul documento. `null` comporta il rifiuto automatico con `MISSING_ADDRESS_INFORMATION`. poa_formatted_address: type: string nullable: true description: >- Versione normalizzata e geocodificata di `poa_address`. example: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: type: object nullable: true description: >- Suddivisione geocodificata e strutturata dell'indirizzo del documento. `null` se non è stato possibile analizzare l'indirizzo. properties: street_1: type: string nullable: true example: Avenida Monseñor Tavella 1291 street_2: type: string nullable: true city: type: string nullable: true example: Salta region: type: string nullable: true example: Salta country: type: string nullable: true description: Codice paese ISO 3166-1 alpha-2. example: AR postal_code: type: string nullable: true example: A4400 document_location: type: object nullable: true properties: latitude: type: number longitude: type: number description: >- Coordinate geocodificate dell'indirizzo del documento. expected_details_address: type: string nullable: true description: Eco dello `expected_address` inviato, o `null`. expected_details_formatted_address: type: string nullable: true description: >- Versione geocodificata e normalizzata di `expected_address`; `null` quando non fornita o non geocodificabile. expected_details_parsed_address: type: object nullable: true additionalProperties: true description: >- Risultato completo della geocodifica per `expected_address` (via/città/regione/paese/codice postale più l'output grezzo del geocoder e un flag `is_verified`). `null` quando `expected_address` non è stato fornito. name_on_document: type: string nullable: true description: >- Nome del titolare principale estratto dal documento; confrontato con `expected_first_name`/`expected_last_name` se forniti. Se `null`, viene rifiutato con `POA_NAME_NOT_DETECTED` su questo endpoint. example: OESTE EMBOTELLADORA S.A. extra_fields: type: object description: >- Dati aggiuntivi specifici del documento. I campi bancari sono compilati per gli estratti conto bancari quando stampati sul documento; `null` altrimenti. properties: bank_account_number: type: string nullable: true bank_iban: type: string nullable: true bank_sort_code: type: string nullable: true bank_routing_number: type: string nullable: true bank_swift_bic: type: string nullable: true bank_branch_name: type: string nullable: true bank_branch_address: type: string nullable: true document_phone_number: type: string nullable: true description: >- Numero di telefono di contatto stampato sul documento. additional_names: type: array items: type: string description: >- Altri nominativi di intestatari rilevati sul documento (es. cointestatari del conto, nominativi precedenti del conto). warnings: type: array description: >- Vuoto in caso di approvazione senza anomalie. Ogni voce illustra un rischio rilevato; le voci con `log_type: "error"` impostano `status` su `Declined`. items: type: object properties: risk: type: string description: >- Codice di rischio leggibile dalla macchina. Sempre rifiutati: `MISSING_ADDRESS_INFORMATION`, `POA_DOCUMENT_EXPIRED`, `INVALID_DOCUMENT_TYPE`, `UNABLE_TO_VALIDATE_DOCUMENT_AGE`, oltre a `UNABLE_TO_EXTRACT_ISSUE_DATE` e `POA_NAME_NOT_DETECTED` (impostati su rifiuto per questo endpoint). Regolati dalle opzioni della richiesta: `NAME_MISMATCH_WITH_PROVIDED` / `ADDRESS_MISMATCH_WITH_PROVIDED` / `POA_COUNTRY_MISMATCH_WITH_PROVIDED` (`poa_address_mismatch_action`), `POOR_DOCUMENT_QUALITY` (mai generato da questo endpoint) / `DOCUMENT_METADATA_MISMATCH` (`poa_document_issues_action`), `SUSPECTED_DOCUMENT_MANIPULATION` e `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` (`poa_document_authenticity_action`), `UNSUPPORTED_DOCUMENT_LANGUAGE` (`poa_unsupported_language_action`), `ISSUER_NOT_IDENTIFIED` (`poa_issuer_not_identified_action`). Informativi su questo endpoint: `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`, `UNPARSABLE_OR_INVALID_ADDRESS`. example: POA_DOCUMENT_EXPIRED feature: type: string enum: - PROOF_OF_ADDRESS description: >- Funzionalità che ha generato l'avviso. Sempre `PROOF_OF_ADDRESS` su questo endpoint. additional_data: type: object nullable: true additionalProperties: true description: >- Contesto aggiuntivo per alcuni rischi — ad es. `POA_DOCUMENT_EXPIRED` include `expiration_reason` (`printed_expiration` o `age_window`), `document_type`, `document_subtype` e `issue_date`, più `expiration_date` nel percorso `printed_expiration` o `max_age_months` nel percorso `age_window`; `SUSPECTED_DOCUMENT_MANIPULATION` include `reason` e `detection_method`; `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` include `reason`, `detection_method` (`unproven_text_replacement`), `replaced_text`, `manipulated_regions` e `manipulated_blocks`. `null` per la maggior parte dei rischi. log_type: type: string enum: - error - information description: >- Gravità. Gli avvisi `error` portano `status` a `Declined`; le voci `information` sono informative e non determinano mai un rifiuto da sole. (`warning` non viene prodotto da questo endpoint — le sue opzioni accettano solo `DECLINE` o `NO_ACTION`.) short_description: type: string description: >- Riepilogo del rischio su una riga leggibile dall'utente. long_description: type: string description: Spiegazione di facile lettura del rischio. detected_codes: type: array description: >- Codici QR e codici a barre rilevati in ogni pagina elaborata del documento. Vuoto se non ne viene trovato nessuno. Un codice QR individuato ma non decodificabile ha `parsed_payload: null`. items: $ref: '#/components/schemas/DocumentAIDetectedCode' vendor_data: type: string nullable: true description: Eco del `vendor_data` inviato, o `null`. metadata: type: object nullable: true additionalProperties: true description: Eco dell'oggetto `metadata` inviato, o `null`. created_at: type: string format: date-time description: Timestamp ISO 8601 (UTC) di generazione della risposta. '400': description: >- Errore di validazione o di elaborazione. I problemi a livello di campo restituiscono l'envelope standard di DRF (un array di messaggi per ciascun campo interessato). I problemi relativi a PDF crittografati restituiscono `{"detail": ...}`. Un documento che la pipeline di estrazione non riesce a elaborare restituisce `{"error": ["Error extracting POA information"]}`. content: application/json: examples: Missing document: summary: '`document` non incluso nei dati del modulo' value: document: - No file was submitted. Unsupported file extension: summary: Estensione del file diversa da tiff/jpg/jpeg/png/pdf/webp value: document: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, pdf, webp. File too large: summary: Il caricamento supera il limite di 15 MB value: document: - File size should not exceed 15 MB Encrypted PDF: summary: PDF caricato senza la password richiesta value: detail: >- The PDF is encrypted. Please upload a decrypted PDF or a photo instead. Wrong PDF password: summary: '`document_password` non decifra il PDF' value: detail: >- The PDF password is incorrect. Please provide the correct password. Invalid language code: summary: '`poa_languages_allowed` contiene un codice non supportato' value: poa_languages_allowed: - >- Invalid language code: 'xx'. Must be one of the supported languages: ['ar', 'bn', 'hy', 'bg', 'bs', 'ca', 'cnr', 'sq', 'zh', 'hr', 'cs', 'da', 'nl', 'en', 'et', 'fi', 'fr', 'ka', 'kk', 'de', 'el', 'he', 'hi', 'hu', 'id', 'it', 'ja', 'ko', 'ky', 'lv', 'lt', 'mk', 'mn', 'ms', 'no', 'fa', 'pl', 'pt', 'ro', 'ru', 'sr', 'sk', 'sl', 'so', 'es', 'sv', 'th', 'tr', 'uk', 'uz', 'vi']. Invalid document age value: summary: >- valore di `poa_document_age_months` non compreso tra 1 e 120 / -1 value: poa_document_age_months: - >- Invalid integer value for 'utility_bill': '999'. Must be -1 (unlimited) or a positive integer between 1 and 120. Extraction failure: summary: >- Impossibile elaborare il documento tramite la pipeline di estrazione value: error: - Error extracting POA information '403': description: >- Autorizzazione negata. Restituito quando l'intestazione `x-api-key` è mancante e anche quando il saldo dell'organizzazione chiamante non è sufficiente a coprire la chiamata; una chiave errata, revocata o scaduta restituisce `401`. Una chiave mancante restituisce `403` con `{"detail": ...}`; una chiave errata, revocata o scaduta restituisce `401`. Crediti insufficienti restituiscono `403` con `{"error": ...}` prima che avvenga qualsiasi elaborazione dei documenti. content: application/json: examples: Missing or invalid API key: summary: >- Nessuna intestazione `x-api-key`, oppure la chiave non è valida/revocata value: detail: You do not have permission to perform this action. Not enough credits: summary: >- Il saldo dell'organizzazione non è sufficiente per coprire la chiamata value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- Limite di frequenza superato. Gli endpoint POST/PATCH/DELETE condividono un budget di 300 richieste di scrittura al minuto per chiave API (la creazione di transazioni e l'ingestione di eventi hanno un budget separato di 600). La risposta contiene le intestazioni `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Più di 300 richieste di scrittura nel minuto corrente value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string '503': $ref: '#/components/responses/DocumentProcessingBusy' security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/poa/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'document=@./utility-bill.pdf' \ -F 'expected_address=Av. Monseñor Tavella 1291, Salta, Argentina' \ -F 'expected_country=ARG' \ -F 'expected_first_name=Sophia' \ -F 'expected_last_name=Martinez' \ -F 'poa_languages_allowed=en,es' \ -F 'vendor_data=user-123' \ --max-time 45 - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.proof_of_address.verify( document=open("document.pdf", "rb"), expected_address="Av. Monseñor Tavella 1291, Salta, Argentina", expected_country="ARG", expected_first_name="Sophia", expected_last_name="Martinez", poa_languages_allowed="en,es", save_api_request=True, vendor_data="user-123", ) print(result) - lang: javascript label: Node.js source: |- import Didit, { fileFromPath } from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.proofOfAddress.verify({ document: await fileFromPath("document.pdf"), expected_address: "Av. Monseñor Tavella 1291, Salta, Argentina", expected_country: "ARG", expected_first_name: "Sophia", expected_last_name: "Martinez", poa_languages_allowed: "en,es", save_api_request: true, vendor_data: "user-123", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.ProofOfAddress.Verify(ctx, didit.ProofOfAddressVerifyParams{\n\tDocument: didit.FileFromPath(\"document.pdf\"),\n\tExpectedAddress: didit.String(\"Av. Monseñor Tavella 1291, Salta, Argentina\"),\n\tExpectedCountry: didit.String(\"ARG\"),\n\tExpectedFirstName: didit.String(\"Sophia\"),\n\tExpectedLastName: didit.String(\"Martinez\"),\n\tPOALanguagesAllowed: didit.String(\"en,es\"),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.nio.file.Path; import me.didit.Didit; import me.didit.types.ProofOfAddressVerifyParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.proofOfAddress().verify(ProofOfAddressVerifyParams.builder() .document(Path.of("document.pdf")) .expectedAddress("Av. Monseñor Tavella 1291, Salta, Argentina") .expectedCountry("ARG") .expectedFirstName("Sophia") .expectedLastName("Martinez") .poaLanguagesAllowed("en,es") .saveApiRequest(true) .vendorData("user-123") .build()); System.out.println(result); - lang: php label: PHP source: |- proofOfAddress->verify([ 'document' => File::fromPath('document.pdf'), 'expected_address' => 'Av. Monseñor Tavella 1291, Salta, Argentina', 'expected_country' => 'ARG', 'expected_first_name' => 'Sophia', 'expected_last_name' => 'Martinez', 'poa_languages_allowed' => 'en,es', 'save_api_request' => true, 'vendor_data' => 'user-123', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.proof_of_address.verify( document: Pathname("document.pdf"), expected_address: "Av. Monseñor Tavella 1291, Salta, Argentina", expected_country: "ARG", expected_first_name: "Sophia", expected_last_name: "Martinez", poa_languages_allowed: "en,es", save_api_request: true, vendor_data: "user-123" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.ProofOfAddress.VerifyAsync(new ProofOfAddressVerifyParams { Document = FileUpload.FromPath("document.pdf"), ExpectedAddress = "Av. Monseñor Tavella 1291, Salta, Argentina", ExpectedCountry = "ARG", ExpectedFirstName = "Sophia", ExpectedLastName = "Martinez", PoaLanguagesAllowed = "en,es", SaveApiRequest = true, VendorData = "user-123", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: DocumentAIDetectedCode: type: object required: - type - page_number - position - x - 'y' - width - height - page_width - page_height - raw_payload - parsed_payload properties: type: type: string description: >- Simbologia rilevata, ad esempio `QR_CODE`, `CODE_128`, `EAN_13`, `DATA_MATRIX` o `PDF_417`. page_number: type: integer minimum: 1 description: Numero di pagina a partire da 1. position: type: array nullable: true description: >- Poligono rilevato nelle coordinate in pixel della pagina renderizzata. `null` quando non è disponibile alcuna posizione affidabile. items: type: array minItems: 2 maxItems: 2 items: type: integer x: type: integer nullable: true description: >- Bordo sinistro del riquadro di delimitazione in pixel della pagina renderizzata. 'y': type: integer nullable: true description: >- Bordo superiore del riquadro di delimitazione in pixel della pagina renderizzata. width: type: integer nullable: true description: >- Larghezza del riquadro di delimitazione in pixel della pagina renderizzata. height: type: integer nullable: true description: >- Altezza del riquadro di delimitazione in pixel della pagina renderizzata. page_width: type: integer description: Larghezza della pagina renderizzata in pixel. page_height: type: integer description: Altezza della pagina renderizzata in pixel. raw_payload: type: string description: >- Payload non elaborato del decodificatore come stringa base64 quando disponibile; altrimenti una stringa vuota. parsed_payload: nullable: true description: >- Stringa decodificata o valore strutturato. `null` quando il codice è stato individuato ma non è stato possibile decodificarlo. responses: DocumentProcessingBusy: description: >- Al momento sono in fase di elaborazione troppi documenti, pertanto questo caricamento non è stato elaborato: non è stato memorizzato nulla e non è stato utilizzato alcun tentativo. Invia nuovamente lo stesso file dopo il numero di secondi indicato in `Retry-After`. Basa la logica su `code`, non sul testo del messaggio. headers: Retry-After: description: >- Secondi da attendere prima di inviare nuovamente la stessa richiesta. schema: type: integer example: 10 content: application/json: schema: type: object required: - detail - code properties: detail: type: string code: type: string enum: - document_processing_busy example: detail: We are busy processing documents. Please try again in a moment. code: document_processing_busy securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- La chiave API della tua applicazione, da Developers -> API keys nella Business Console. La chiave primaria ha accesso completo. Una chiave con nome può avere un ambito definito: nessuno, lettura o scrittura per risorsa, limitata ad alcuni workflow o a sessioni approvate, a un elenco di indirizzi IP e a una data di scadenza. 401 indica che la chiave è errata, revocata o scaduta; 403 indica che non è stata inviata alcuna chiave, che la chiave non ha accesso a questa risorsa o azione, oppure che la richiesta proviene da un indirizzo non incluso nel suo elenco IP; 404 su una route di sessione indica che la sessione non rientra nei workflow o negli stati previsti dalla chiave. Una chiave senza accesso ai media riceve gli URL di immagini, video e PDF come null, e una chiave senza permessi di scrittura sulle sessioni riceve link e token di sessione come null. Consulta https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.