Vai al contenuto principale
POST
Python
Invia un documento e l’elenco dei campi da leggere al suo interno. Didit esegue il modello di estrazione predefinito sul file, restituisce ogni campo con il proprio tipo (text, number oppure date nel formato YYYY-MM-DD), rileva e decodifica i codici QR e a barre supportati, controlla il file per individuare eventuali manipolazioni e, facoltativamente, confronta il nome presente sul documento con la persona o l’azienda che ti aspetti. Usalo per prova dei fondi, buste paga, estratti conto bancari, documenti fiscali, fatture o qualsiasi documento che non segue un modello fisso. Questa è la versione server-to-server del passaggio Document AI ospitato. La richiesta è multipart/form-data: il file va nel campo document, mentre le definizioni dei campi vanno nel campo fields come una singola stringa con un array JSON.

Definire i campi da estrarre

fields è un array JSON di 1-30 elementi, inviato come una singola stringa. Ogni elemento ha una key (lettere minuscole, cifre e underscore, univoca all’interno della richiesta), un name leggibile, una instruction che indica al modello cosa cercare, un type (text, number oppure date) e due flag: required e is_full_name.
In una richiesta multipart, l’intero array è un unico valore del form:
La risposta riporta i fields normalizzati e restituisce extracted_data indicizzato in base ai tuoi valori key, con null per tutto ciò che il modello non è riuscito a trovare. name, instruction e type sono facoltativi per ogni elemento (type ha come valore predefinito text); key è obbligatoria. Se invii fields come chiavi di form in stile parentesi (fields[0][key]=...) oppure come qualsiasi formato diverso da un array JSON, ricevi 400 prima che l’estrazione venga avviata, quindi nulla viene fatturato.

Codici QR e codici a barre

Ogni risposta riuscita include document_ai.detected_codes. Ogni elemento contiene: L’array copre tutte le pagine elaborate di un PDF ed è vuoto quando non viene trovato alcun codice supportato. Didit non indovina mai un payload: i codici QR danneggiati possono essere restituiti con la loro posizione e parsed_payload: null, mentre gli errori nel rilevamento dei codici non fanno fallire la richiesta Document AI.

Confronto dei nomi

Contrassegna al massimo un campo con is_full_name: true e invia il nome della persona o dell’azienda a cui ti aspetti che appartenga il documento: Invia un gruppo oppure l’altro, non entrambi. Quando un nome viene estratto e ne è presente uno atteso, la risposta include name_match_score (da 0 a 100) e name_on_document. Un punteggio inferiore a document_ai_name_match_score_threshold (predefinito 80) genera l’avviso DOCUMENT_AI_NAME_MISMATCH e applica document_ai_name_mismatch_action. Se nessun campo è contrassegnato come is_full_name, Didit usa come ripiego il primo campo di testo la cui chiave sembra un nome (name, holder, full_name, account_holder); contrassegna esplicitamente il campo quando vuoi controllare quale valore viene confrontato. Quando non si trova alcun valore di nome sul documento, oppure non viene inviato alcun nome atteso, il controllo sul nome viene saltato e name_match_score è null.

Rischi e azioni

Ogni rischio qui sotto corrisponde a un parametro di azione che puoi impostare per richiesta: DECLINE, REVIEW oppure NO_ACTION. L’azione più restrittiva tra quelle attivate determina document_ai.status (Declined > In Review > Approved), e ogni rischio attivato è elencato in document_ai.warnings. I valori predefiniti corrispondono a quelli del passaggio del workflow ospitato; consulta Regole e avvisi di Document AI per sapere come viene rilevato ciascun rischio.

File, salvataggio e fatturazione

  • File accettati: PDF (sono supportati più pagine), JPG, JPEG, PNG, TIFF, WebP oppure un ZIP contenente il documento, fino a 30 MB. I PDF cifrati restituiscono 400; carica un PDF decifrato oppure una foto.
  • save_api_request (predefinito true): la richiesta, i campi estratti e i codici rilevati compaiono nella Business Console sotto Controlli Manuali, dove il tuo team può verificarli. Impostalo su false per non salvarli.
  • vendor_data e metadata vengono restituiti invariati nella risposta, così puoi collegare il risultato ai tuoi record.
  • Prezzo: $0.20 per documento, fatturato quando il documento viene elaborato e viene restituito uno stato. Si applica lo sconto del tuo piano. Consulta Prezzi.
Devi far caricare il documento direttamente all’utente, raccogliere fino a 3 documenti in un unico flusso, tradurre automaticamente la schermata di caricamento oppure incrociare i campi estratti con i dati di un documento d’identità o di un questionario? Usa invece il passaggio del workflow Document AI ospitato.

Autorizzazioni

x-api-key
string
header
obbligatorio

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.

Corpo

multipart/form-data
document
file
obbligatorio

Il documento da leggere. Estensioni consentite: tiff, jpg, jpeg, png, pdf, webp, zip. Dimensione massima di caricamento: 30 MB (i file più grandi vengono rifiutati con un 400). I PDF multipagina sono supportati (prevedere una latenza maggiore); i PDF crittografati vengono rifiutati con un 400. Le immagini vengono compresse automaticamente prima dell'elaborazione.

fields
string
obbligatorio

Una stringa contenente un array codificato in JSON con 1–30 definizioni di campo (massimo 16 KB). Ogni elemento: key (obbligatorio, ^[a-z0-9_]{1,64}$, univoco — la chiave restituita in extracted_data), name (≤100 caratteri, mostrato nei messaggi), instruction (≤500 caratteri, ciò che il modello deve leggere), type (text predefinito | number | date), required (booleano, predefinito false), is_full_name (booleano, predefinito false, al massimo uno per richiesta). Gli array di form in stile parentesi quadre, JSON non valido, chiavi duplicate o più di un is_full_name restituiscono 400 prima di qualsiasi elaborazione o fatturazione.

Esempio:

"[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]"

expected_first_name
string

Nome da verificare rispetto al campo del nome del documento (confronto fuzzy, tiene conto della traslitterazione). Da utilizzare insieme a expected_last_name; non può essere combinato con expected_company_name.

Esempio:

"Sophia"

expected_last_name
string

Cognome da verificare rispetto al campo del nome del documento, combinato con expected_first_name per name_match_score.

Esempio:

"Martinez"

expected_company_name
string

Ragione sociale da verificare rispetto al campo del nome del documento (per documenti aziendali). Non può essere combinata con expected_first_name / expected_last_name (nessun valore di esempio intenzionalmente: l'esempio di richiesta generato utilizza i campi della persona fisica; sostituiscili con questo quando verifichi un documento aziendale).

expected_company_country
string

Codice paese opzionale ISO 3166-1 alpha-2 (due lettere ASCII, ad es. FR) che regola la normalizzazione del nome dell'azienda per expected_company_name. Utilizzato solo con expected_company_name.

document_ai_name_match_score_threshold
integer
predefinito:80

Valore minimo di name_match_score (0–100) affinché il nome sia considerato corrispondente. Un punteggio inferiore aggiunge DOCUMENT_AI_NAME_MISMATCH, regolato da document_ai_name_mismatch_action.

Intervallo richiesto: 0 <= x <= 100
Esempio:

80

document_ai_unreadable_document_action
enum<string>
predefinito:REVIEW

Cosa fare quando non è stato possibile leggere alcun campo dal documento (DOCUMENT_AI_UNREADABLE_DOCUMENT).

Opzioni disponibili:
DECLINE,
REVIEW,
NO_ACTION
document_ai_missing_required_fields_action
enum<string>
predefinito:REVIEW

Cosa fare quando non è stato possibile leggere almeno un campo required (DOCUMENT_AI_MISSING_REQUIRED_FIELDS; additional_data.missing_fields li elenca).

Opzioni disponibili:
DECLINE,
REVIEW,
NO_ACTION
document_ai_document_tampering_action
enum<string>
predefinito:DECLINE

Cosa fare quando l'analisi forense di PDF/EXIF sospetta una manipolazione — modificato dopo la firma digitale, editor PDF noto, manipolazione del testo in sovrimpressione, riesportazione sospetta, anomalie dell'immagine (DOCUMENT_AI_SUSPECTED_MANIPULATION).

Opzioni disponibili:
DECLINE,
REVIEW,
NO_ACTION
document_ai_name_mismatch_action
enum<string>
predefinito:NO_ACTION

Cosa fare quando name_match_score è inferiore alla soglia (DOCUMENT_AI_NAME_MISMATCH).

Opzioni disponibili:
DECLINE,
REVIEW,
NO_ACTION
document_ai_unsupported_file_action
enum<string>
predefinito:REVIEW

Cosa fare quando il caricamento è vuoto o non è un file elaborabile (DOCUMENT_AI_UNSUPPORTED_FILE).

Opzioni disponibili:
DECLINE,
REVIEW,
NO_ACTION
save_api_request
boolean
predefinito:true

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, con il documento caricato, i valori estratti, le definizioni dei campi e lo snapshot di corrispondenza dei nomi archiviati. Quando è false, non viene memorizzato nulla e request_id è un UUID temporaneo utilizzabile solo per la correlazione della risposta; la chiamata viene comunque fatturata.

Esempio:

true

vendor_data
string

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.

Esempio:

"user-123"

metadata
object

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.

Esempio:

Risposta

Documento elaborato. document_ai.status è Approved, Declined o In Review; ogni problema rilevato è dettagliato in document_ai.warnings. Un documento problematico restituisce comunque 200 — esamina il corpo, non solo il codice HTTP. Quando save_api_request=true, request_id è l'ID di sessione persistito.

request_id
string<uuid>

ID della sessione salvata quando save_api_request=true (utilizzabile con GET /v3/session/{sessionId}/decision/); altrimenti un UUID di correlazione temporaneo.

document_ai
object
vendor_data
string | null

Eco del vendor_data inviato, o null.

metadata
object | null

Eco dell'oggetto metadata inviato, o null.

created_at
string<date-time>

Quando la richiesta è stata elaborata (UTC, ISO 8601).

Ultima modifica il 7 novembre 2026