Documenti d'Identità - Dati Estratti¶

Elenco delle voci complete che è possibile estrarre automaticamente dai documenti d'identità.

Tipologie Supportate¶

L'API riconosce e processa le seguenti categorie di documento:

carta_identita - Carta d'Identità italiana
passaporto - Passaporto italiano/europeo
patente - Patente di guida italiana
tessera_sanitaria - Tessera Sanitaria/CNS
permesso_di_soggiorno - Permesso di soggiorno per stranieri
sconosciuto - Documento non identificato con certezza

Ogni risposta contiene il corpo 'extracted_data' contenente i dettagli della categoria del documento

Carta d'Identità (carta_identita)¶

Esempio Response completa¶

{
  "event": "document.processed",
  "created_at": "2025-09-09T21:06:58.313134+00:00",
  "document_id": "d6ccd504-48c2-4283-a954-bb0dcf0bf522",
  "application_id": "35d31ac5-f604-4e14-ac4b-69323113c334",
  "applicant_reference": "USER-001",
  "status": "DONE",
  "document_type": "documento_identita",
  "extracted_data": {
    "status": "ok",
    "categoria": "carta_identita",
    "numero_documento": "CA15253NN",
    "cognome": "LOVECCHIO",
    "nome": "UMBERTO MARIO",
    "data_nascita": "29.07.1991",
    "luogo_nascita": "CATANZARO (CZ)",
    "sesso": "M",
    "statura": "180",
    "cittadinanza": "ITA",
    "data_emissione": "19.07.2022",
    "data_scadenza": "29/07/2032",
    "documento_scaduto": false,
    "ente_rilascio": "COMUNE DI / MUNICIPALITY CATANZARO",
    "indirizzo_residenza": "VIALE DEI BIZANTINI, N. 1 CATANZARO (CZ)",
    "codice_fiscale": "LVCMRT91L29C352H",
    "atto_nascita": "14.18 pt 5A-1991 079023"
  }
}

Campi Carta d'Identità¶

Campo	Tipo	Obbligatorio	Descrizione	Esempio
`numero_documento`	string	Sì	Numero della carta d'identità	"CA9876543"
`cognome`	string	null	No	Cognome del titolare
`nome`	string	null	No	Nome del titolare
`data_nascita`	string	null	No	Data di nascita (DD/MM/YYYY)
`luogo_nascita`	string	null	No	Luogo di nascita con provincia
`sesso`	string	null	No	Sesso (M/F)
`statura`	string	null	No	Statura in centimetri
`cittadinanza`	string	null	No	Cittadinanza
`data_emissione`	string	null	No	Data emissione (DD/MM/YYYY)
`data_scadenza`	string	null	No	Data scadenza, normalizzata a DD/MM/YYYY
`documento_scaduto`	boolean	Sì	`true` se la scadenza è odierna o passata	false
`ente_rilascio`	string	null	No	Ente che ha rilasciato
`indirizzo_residenza`	string	null	No	Indirizzo completo residenza
`codice_fiscale`	string	null	No	Codice Fiscale
`atto_nascita`	string	null	No	Estremi atto di nascita

Passaporto (passaporto)¶

Esempio Response completa¶

{
  "event": "document.processed",
  "created_at": "2025-09-09T21:06:58.313134+00:00",
  "document_id": "d6ccd504-48c2-4283-a954-bb0dcf0bf522",
  "application_id": "35d31ac5-f604-4e14-ac4b-69323113c334",
  "applicant_reference": "USER-001",
  "status": "DONE",
  "document_type": "documento_identita",
  "extracted_data": {
    "categoria" : "passaporto",
    "tipo": "P",
    "codice_paese": "ITA",
    "numero_passaporto": "YA8765432",
    "cognome": "ROSSI",
    "nome": "MARIA GIULIA",
    "cittadinanza": "ITALIANA",
    "data_nascita": "08/12/1985",
    "sesso": "F",
    "luogo_nascita": "ROMA",
    "data_emissione": "12/04/2020",
    "data_scadenza": "12/04/2030",
    "documento_scaduto": false,
    "autorita_rilascio": "Questura di Roma"
  }
}

Campi Passaporto¶

Campo	Tipo	Descrizione	Esempio
`tipo`	string	null	Tipo di passaporto
`codice_paese`	string	null	Codice paese ISO 3166-1 alpha-3
`numero_passaporto`	string	null	Numero del passaporto
`cognome`	string	null	Cognome del titolare
`nome`	string	null	Nome del titolare
`cittadinanza`	string	null	Cittadinanza
`data_nascita`	string	null	Data di nascita (DD/MM/YYYY)
`sesso`	string	null	Sesso (M/F)
`luogo_nascita`	string	null	Luogo di nascita
`data_emissione`	string	null	Data emissione (DD/MM/YYYY)
`data_scadenza`	string	null	Data scadenza, normalizzata a DD/MM/YYYY
`documento_scaduto`	boolean	`true` se la scadenza è odierna o passata	false
`autorita_rilascio`	string	null	Autorità di rilascio

Patente di Guida (patente)¶

Esempio Response completa¶

{
  "event": "document.processed",
  "created_at": "2025-09-09T21:06:58.313134+00:00",
  "document_id": "d6ccd504-48c2-4283-a954-bb0dcf0bf522",
  "application_id": "35d31ac5-f604-4e14-ac4b-69323113c334",
  "applicant_reference": "USER-001",
  "status": "DONE",
  "document_type": "documento_identita",
  "extracted_data": {
    "categoria" : "patente",
    "numero_patente": "U1X987654Y",
    "cognome": "BIANCHI",
    "nome": "MARCO ANTONIO",
    "data_nascita": "15/07/1982",
    "luogo_nascita": "NAPOLI",
    "sesso": "M",
    "data_emissione": "20/03/2019",
    "data_scadenza": "15/07/2029",
    "documento_scaduto": false,
    "ufficio_rilascio": "MCTC Napoli",
    "categorie_abilitate": ["B", "A2", "BE"],
    "codice_fiscale": "BNCMRC82L15F839P"
  }
}

Campi Patente¶

Campo	Tipo	Descrizione	Esempio
`numero_patente`	string	null	Numero della patente
`cognome`	string	null	Cognome titolare (Campo 1)
`nome`	string	null	Nome titolare (Campo 2)
`data_nascita`	string	null	Data nascita (Campo 3 - DD/MM/YYYY)
`luogo_nascita`	string	null	Luogo nascita (Campo 3)
`sesso`	string	null	Sesso (M/F)
`data_emissione`	string	null	Data emissione (Campo 4a - DD/MM/YYYY)
`data_scadenza`	string	null	Data scadenza (Campo 4b), normalizzata a DD/MM/YYYY
`documento_scaduto`	boolean	`true` se la scadenza è odierna o passata	false
`ufficio_rilascio`	string	null	Ufficio rilascio (Campo 4c)
`categorie_abilitate`	array	null	Categorie veicoli (Campo 9)
`codice_fiscale`	string	null	Codice Fiscale

Categorie Patente Comuni¶

A1, A2, A - Motocicli
B, BE - Autovetture e rimorchi
C1, C, CE - Autocarri
D1, D, DE - Autobus

Tessera Sanitaria (tessera_sanitaria)¶

Esempio Response completa¶

{
  "event": "document.processed",
  "created_at": "2025-09-09T21:06:58.313134+00:00",
  "document_id": "d6ccd504-48c2-4283-a954-bb0dcf0bf522",
  "application_id": "35d31ac5-f604-4e14-ac4b-69323113c334",
  "applicant_reference": "USER-001",
  "status": "DONE",
  "document_type": "documento_identita",
  "extracted_data": {
    "categoria" : "tessera_sanitaria",
    "codice_fiscale": "VRDLRA88D45H501T",
    "cognome": "VERDI",
    "nome": "LAURA",
    "data_nascita": "05/04/1988",
    "luogo_nascita": "MILANO (MI)",
    "sesso": "F",
    "data_scadenza": "04/2028",
    "documento_scaduto": false
  }
}

Campi Tessera Sanitaria¶

Campo	Tipo	Descrizione	Esempio
`codice_fiscale`	string	null	Codice Fiscale
`cognome`	string	null	Cognome del titolare
`nome`	string	null	Nome del titolare
`data_nascita`	string	null	Data di nascita (DD/MM/YYYY)
`luogo_nascita`	string	null	Luogo di nascita
`sesso`	string	null	Sesso (M/F)
`data_scadenza`	string	null	Data scadenza (MM/YYYY o DD/MM/YYYY)
`documento_scaduto`	boolean	`true` se la scadenza è odierna o passata	false

Nota: la tessera sanitaria è l'unico documento per cui è ammesso il formato MM/YYYY. In quel caso la scadenza si considera a fine mese: 04/2028 risulta scaduta dal 1° maggio 2028.

Permesso di Soggiorno (permesso_di_soggiorno)¶

Esempio Response completa¶

{
  "event": "document.processed",
  "created_at": "2025-09-09T21:06:58.313134+00:00",
  "document_id": "d6ccd504-48c2-4283-a954-bb0dcf0bf522",
  "application_id": "35d31ac5-f604-4e14-ac4b-69323113c334",
  "applicant_reference": "USER-001",
  "status": "DONE",
  "document_type": "documento_identita",
  "extracted_data": {
    "categoria" : "permesso_di_soggiorno",
    "numero_documento": "PS1234567",
    "cognome": "PETROV",
    "nome": "ALEKSANDR",
    "data_nascita": "10/09/1988",
    "luogo_nascita": "SOFIA (BULGARIA)",
    "sesso": "M",
    "cittadinanza": "BULGARA",
    "data_emissione": "15/06/2023",
    "data_scadenza": "15/06/2028",
    "documento_scaduto": false,
    "ente_rilascio": "Questura di Milano",
    "codice_fiscale": "PTRLKS88P10Z100X",
    "tipo_permesso": "lavoro subordinato"
  }
}

Campi Permesso di Soggiorno¶

Campo	Tipo	Obbligatorio	Descrizione	Esempio
`numero_documento`	string	Sì	Numero permesso di soggiorno	"PS1234567"
`cognome`	string	null	No	Cognome del titolare
`nome`	string	null	No	Nome del titolare
`data_nascita`	string	null	No	Data di nascita (DD/MM/YYYY)
`luogo_nascita`	string	null	No	Luogo di nascita
`sesso`	string	null	No	Sesso (M/F)
`cittadinanza`	string	null	No	Cittadinanza
`data_emissione`	string	Sì	Data emissione (DD/MM/YYYY)	"15/06/2023"
`data_scadenza`	string	Sì	Data scadenza, normalizzata a DD/MM/YYYY	"15/06/2028"
`documento_scaduto`	boolean	Sì	`true` se la scadenza è odierna o passata	false
`ente_rilascio`	string	null	No	Ente di rilascio
`codice_fiscale`	string	Sì	Codice Fiscale	"PTRLKS88P10Z100X"
`tipo_permesso`	string	null	No	Tipo di permesso

Tipi Permesso Comuni¶

lavoro subordinato - Lavoro dipendente
lavoro autonomo - Lavoro indipendente
studio - Permesso per studenti
famiglia - Ricongiungimento familiare
protezione internazionale - Asilo/protezione
dimora - Lungo soggiornanti UE

Validità del Documento (documento_scaduto)¶

Tutti i documenti d'identità riportano due campi che descrivono la validità temporale: data_scadenza, normalizzata, e documento_scaduto, calcolato.

Il flag non viene letto dal documento né dedotto dal modello: è calcolato confrontando la scadenza con la data odierna.

Condizione	`data_scadenza`	`documento_scaduto`
Scadenza futura	conservata e normalizzata	`false`
Scadenza odierna	conservata e normalizzata	`true`
Scadenza passata	conservata e normalizzata	`true`
Scadenza non interpretabile	`null`	`false`
Scadenza assente sul documento	`null`	`false`

{
  "data_scadenza": "29/07/2020",
  "documento_scaduto": true
}

Normalizzazione della Data¶

data_scadenza viene riscritta nel formato DD/MM/YYYY qualunque sia il formato stampato sul documento. Sono riconosciuti DD/MM/YYYY, DD.MM.YYYY, DD-MM-YYYY e YYYY-MM-DD.

Una carta d'identità che stampa 29.07.2032 viene quindi restituita con "data_scadenza": "29/07/2032".

Attenzione: la normalizzazione riguarda solo data_scadenza. Gli altri campi data (data_nascita, data_emissione) sono restituiti nel formato letto sul documento, che può quindi usare i punti. Nello stesso documento si possono trovare "data_nascita": "29.07.1991" e "data_scadenza": "29/07/2032".

Date Non Interpretabili¶

Un formato non riconosciuto — per esempio 10 GEN 2030 — azzera data_scadenza e produce documento_scaduto: false. Un documento_scaduto a false non è quindi di per sé una prova di validità: va sempre letto insieme a data_scadenza, e una scadenza null significa "non determinabile", non "senza scadenza".

Documenti Senza Scadenza¶

I due campi vengono aggiunti alla risposta di ogni documento d'identità, compresi quelli della categoria sconosciuto e i documenti che una scadenza non la prevedono. In questi casi si ottiene "data_scadenza": null e "documento_scaduto": false, che va letto come "nessuna scadenza rilevata".

Classificazione Automatica¶

L'API classifica automaticamente il tipo di documento analizzando:

Layout e struttura del documento
Campi specifici presenti
Formati dei numeri identificativi
Elementi grafici caratteristici

Affidabilità Classificazione¶

Tipo Documento	Affidabilità	Note
`carta_identita`	Alta	Layout standardizzato
`passaporto`	Alta	Formato internazionale
`patente`	Media	Variazioni layout europeo
`tessera_sanitaria`	Alta	Campi CF distintivi
`permesso_di_soggiorno`	Media	Formati variabili

Note Implementative¶

Gestione Campi Null¶

Solo alcuni campi sono obbligatori per tipo documento
I campi null indicano spesso informazioni non leggibili
documento_scaduto è un booleano sempre presente, mai null
data_scadenza è null quando la scadenza è assente o non interpretabile

Formati Data¶

Standard: DD/MM/YYYY (es. "15/03/2025")
Tessera Sanitaria: MM/YYYY possibile (es. "03/2025")
Patente: Alcuni documenti usano DD.MM.YYYY
data_scadenza viene sempre riportata a DD/MM/YYYY, anche quando il documento usa i punti; gli altri campi data conservano il formato letto

Validazione Codice Fiscale¶

Presente nella maggior parte dei documenti italiani
Utilizzare per validazione incrociata dei dati
Può essere sul retro di alcuni documenti

Categorie Patente¶

Array di stringhe per categorie multiple
Controllare scadenze specifiche per categoria
Alcune categorie hanno limitazioni età

Scadenza Documenti¶

Verificare sempre validità temporale
Documenti scaduti potrebbero essere rifiutati
Tessera sanitaria ha scadenze quinquennali
Il campo documento_scaduto fornisce l'esito già calcolato: un documento che scade oggi è considerato scaduto
Il calcolo avviene al momento dell'elaborazione: un documento valido alla data di estrazione può essere scaduto quando la risposta viene riletta in seguito

Cittadinanza Straniera¶

Permessi soggiorno per cittadini non UE
Verificare validità e tipo autorizzazione
Possibili restrizioni geografiche/lavorative

Codici Paese¶

Passaporti usano codici ISO 3166-1 alpha-3
ITA = Italia, FRA = Francia, DEU = Germania, etc.
Verificare codici per documenti stranieri

Documenti d'Identità - Dati Estratti Tipologie Supportate Carta d'Identità ( )Esempio Response completa Campi Carta d'Identità Passaporto ( )Esempio Response completa Campi Passaporto Patente di Guida ( )Esempio Response completa Campi Patente Categorie Patente Comuni Tessera Sanitaria ( )Esempio Response completa Campi Tessera Sanitaria Permesso di Soggiorno ( )Esempio Response completa Campi Permesso di Soggiorno Tipi Permesso Comuni Validità del Documento ( )Normalizzazione della Data Date Non Interpretabili Documenti Senza Scadenza Classificazione Automatica Affidabilità Classificazione Note Implementative Gestione Campi Null Formati Data Validazione Codice Fiscale Categorie Patente Scadenza Documenti Cittadinanza Straniera Codici Paese