Certificazione unica¶

Totale delle voci estratte da una Certificazione Unica (CU), nelle due varianti gestite dal sistema:

CU INPS per pensionati — rilasciata dall'INPS, certifica i redditi da pensione percepiti nell'anno fiscale precedente e le ritenute IRPEF operate.
CU per lavoratori dipendenti — rilasciata dal datore di lavoro (sostituto d'imposta), certifica i redditi da lavoro dipendente, le ritenute, i dati previdenziali INPS e il TFR.

Entrambe le varianti condividono lo stesso document_type e la stessa struttura base della response. Il campo extracted_data.categoria indica quale variante è stata riconosciuta e quindi quali sezioni di extracted_data sono valorizzate.

Descrizione del Documento¶

La Certificazione Unica (CU) è il documento annuale con cui il sostituto d'imposta certifica i redditi corrisposti nell'anno fiscale precedente e le ritenute operate. È l'evoluzione del vecchio CUD e viene utilizzata per la dichiarazione dei redditi (730 / Redditi PF).

Document Type	`categoria`	Descrizione	Sostituto d'imposta
`certificazione_unica`	`certificazione_unica_pensionati`	Certificazione Unica INPS per pensionati	INPS (Istituto Nazionale Previdenza Sociale)
`certificazione_unica`	`certificazione_unica_dipendenti`	Certificazione Unica per lavoratori dipendenti del settore privato	Datore di lavoro (azienda)

Riconoscimento della Categoria¶

Il sistema determina il valore di categoria analizzando il documento:

Indicatore	`certificazione_unica_pensionati`	`certificazione_unica_dipendenti`
Sostituto d'imposta	INPS (CF `80078750587`)	Azienda privata
Codice prestazione INPS (15 cifre)	Presente	Assente
Redditi valorizzati nei Dati fiscali	Punto 3 (redditi di pensione)	Punti 1–2 (redditi di lavoro dipendente)
Sezioni TFR e dati previdenziali	Assenti	Presenti

Nota: i numeri di "punto" citati in questa documentazione fanno riferimento al modello CU 2026 (periodo d'imposta 2025). L'Agenzia delle Entrate può rinumerare i campi nei modelli successivi: la mappatura va verificata ad ogni nuovo modello.

Campi Comuni¶

Questi campi sono presenti in extracted_data per entrambe le categorie.

Metadati di Elaborazione¶

{
  "categoria": "certificazione_unica_dipendenti",
  "status": "ok",
  "anno_certificazione": 2026,
  "anno_fiscale": 2025
}

Campo	Tipo	Descrizione	Valori possibili
`categoria`	`string`	Categoria del documento estratto; discrimina la variante di CU	`"certificazione_unica_pensionati"` / `"certificazione_unica_dipendenti"`
`status`	`string`	Stato dell'elaborazione	`"ok"` / `"error"`
`anno_certificazione`	`integer`	Anno del modello CU (intestazione, es. "CU 2026")	Es. `2026`
`anno_fiscale`	`integer`	Periodo d'imposta certificato	Es. `2025` (= `anno_certificazione - 1`)

Informazioni Anagrafiche¶

La sezione anagrafica contiene i dati identificativi del percettore (pensionato o dipendente):

{
  "codice_fiscale": "RSSMRA65H15F205X",
  "nome": "ROSSI MARIO",
  "data_nascita": "15/06/1965",
  "comune_nascita": "MILANO",
  "provincia_nascita": "MI"
}

Campo	Tipo	Descrizione	Origine (pensionato)	Origine (dipendente)	Validazione
`codice_fiscale`	`string`	Codice fiscale del percettore (16 caratteri)	Sezione anagrafica	Dati anagrafici, punto 1	Validazione e correzione automatica OCR
`nome`	`string`	Cognome e nome completo del percettore	Sezione "Denominazione"	Dati anagrafici, punti 2–3 (cognome + nome)	Testo in maiuscolo
`data_nascita`	`string`	Data di nascita nel formato GG/MM/AAAA	Sezione anagrafica	Dati anagrafici, punto 5	Derivata anche dal CF se disponibile
`comune_nascita`	`string`	Comune di nascita	Sezione anagrafica	Dati anagrafici, punto 6	Testo libero
`provincia_nascita`	`string`	Sigla provincia di nascita (2 caratteri)	Sezione anagrafica	Dati anagrafici, punto 7	Es. "MI", "RM", "NA"

Parte 1 — CU INPS per Pensionati¶

Esempio Response Completa (Pensionato)¶

{
   "event":"document.processed",
   "created_at":"2025-09-01T15:37:36.467736+00:00",
   "document_id":"0cd0ca0f-7a02-4deb-b2a8-445f694af865",
   "application_id":"c3a058c3-2243-4f83-92ce-d6e4fd3e89ae",
   "status":"DONE",
   "applicant_reference": "USER-001",
   "document_type":"certificazione_unica",
   "extracted_data":{
        "categoria": "certificazione_unica_pensionati",
        "status": "ok",
        "anno_certificazione": 2025,
        "anno_fiscale": 2024,
        "codice_fiscale": "RSSMRA65H15F205X",
        "nome": "ROSSI MARIO",
        "data_nascita": "15/06/1965",
        "comune_nascita": "MILANO",
        "provincia_nascita": "MI",
        "codice_prestazione": "001500009184109",
        "decorrenza_inizio": "01/01/2020",
        "pensione_lorda": 18500.50,
        "ritenute_irpef": 3250.75,
        "codice_pensione_descrizione": "001 - VO",
        "codice_sede_descrizione": "5000 - Modena",
        "numero_pensione": "09184109",
        "invalidita": false
   }
}

Struttura dei Dati Estratti (Pensionato)¶

Informazioni sulla Pensione¶

Dati relativi alla prestazione pensionistica e ai redditi percepiti:

{
  "codice_prestazione": "001500009184109",
  "decorrenza_inizio": "01/01/2020",
  "pensione_lorda": 18500.50,
  "ritenute_irpef": 3250.75
}

Campo	Tipo	Descrizione	Formato
`codice_prestazione`	`string`	Codice univoco INPS della pensione (15 cifre)	Numerico senza spazi
`decorrenza_inizio`	`string`	Data di inizio della pensione	GG/MM/AAAA o MM/AAAA
`pensione_lorda`	`float`	Reddito totale lordo da pensione nell'anno fiscale	Importo positivo con 2 decimali
`ritenute_irpef`	`float`	Totale ritenute IRPEF operate nell'anno	Importo positivo con 2 decimali

Dettaglio Codice Prestazione¶

Il codice prestazione è un identificatore di 15 cifre composto da:

001 5000 09184109

│ │ └─ Numero pensione (8 cifre)

│ └────── Codice sede INPS (4 cifre)

└────────── Codice tipo pensione (3 cifre)

Esempi di codici prestazione validi:

001500009184109 - Pensione di vecchiaia, sede Modena
002700012345678 - Pensione di invalidità, sede Roma
219880110987654 - Pensione IOCPI (Invalidità Ordinaria CPI), sede Torino

Nota: Il sistema accetta sia formato continuo (001500009184109) che con spazio (001 500009184109) e li normalizza automaticamente.

Dati Arricchiti (Derivati)¶

Il sistema arricchisce automaticamente i dati analizzando il codice_prestazione:

{
  "codice_pensione_descrizione": "001 - VO",
  "codice_sede_descrizione": "5000 - Modena",
  "numero_pensione": "09184109",
  "invalidita": false
}

Campo	Tipo	Descrizione	Derivato da
`codice_pensione_descrizione`	`string`	Tipo di pensione con codice e sigla	Prime 3 cifre del codice prestazione
`codice_sede_descrizione`	`string`	Sede INPS erogante con codice e nome città	Cifre 4-7 del codice prestazione
`numero_pensione`	`string`	Numero identificativo univoco della pensione	Cifre 8-15 del codice prestazione
`invalidita`	`boolean`	`true` se è pensione di invalidità, `false` altrimenti	Derivato dalla categoria (prefisso "I")

Classificazione Tipi di Pensione¶

Il sistema riconosce oltre 80 tipologie di pensioni INPS. Di seguito le principali:

Pensioni Ordinarie¶

Codice	Sigla	Descrizione	Invalidità
`001`	VO	Vecchiaia Ordinaria	No
`002`	IO	Invalidità Ordinaria	Sì
`003`	SO	Superstiti Ordinaria	No
`004`	VOS	Vecchiaia Ordinaria Speciale	No
`005`	IOS	Invalidità Ordinaria Speciale	Sì
`006`	SOS	Superstiti Ordinaria Speciale	No

Pensioni Privilegiate¶

Codice	Sigla	Descrizione	Invalidità
`007`	VOP	Vecchiaia Ordinaria Privilegiata	No
`008`	IOP	Invalidità Ordinaria Privilegiata	Sì
`009`	SOP	Superstiti Ordinaria Privilegiata	No

Pensioni Speciali¶

Codice	Sigla	Descrizione	Invalidità
`010`	VOSPED	Vecchiaia Ordinaria Speciale Edili	No
`011`	IOSPED	Invalidità Ordinaria Speciale Edili	Sì
`012`	SOSPED	Superstiti Ordinaria Speciale Edili	No
`013`	VOMIN	Vecchiaia Ordinaria Minatori	No
`014`	SOMIN	Superstiti Ordinaria Minatori	No

Pensioni Settori Speciali¶

Codice	Sigla	Descrizione	Invalidità
`018`	VOART	Vecchiaia Ordinaria Artigiani	No
`019`	IOART	Invalidità Ordinaria Artigiani	Sì
`020`	SOART	Superstiti Ordinaria Artigiani	No
`021`	VOCOM	Vecchiaia Ordinaria Commercianti	No
`022`	IOCOM	Invalidità Ordinaria Commercianti	Sì
`023`	SOCOM	Superstiti Ordinaria Commercianti	No

Pensioni Casse Professionali¶

Codice	Sigla	Descrizione	Invalidità
`213`	VOCTPS	Vecchiaia Ordinaria CTP (Cassa Professionisti)	No
`214`	IOCTPS	Invalidità Ordinaria CTP	Sì
`215`	SOCTPS	Superstiti Ordinaria CTP	No
`219`	VOCPI	Vecchiaia Ordinaria CPI (Cassa Previdenza Ingegneri)	No
`220`	IOCPI	Invalidità Ordinaria CPI	Sì
`221`	SOCPI	Superstiti Ordinaria CPI	No
`222`	VOCPS	Vecchiaia Ordinaria CPS (Cassa Previdenza Sanitari)	No
`223`	IOCPS	Invalidità Ordinaria CPS	Sì
`224`	SOCPS	Superstiti Ordinaria CPS	No

Prestazioni Assistenziali¶

Codice	Sigla	Descrizione	Invalidità
`043`	INDCOM	Indennità Commercianti	No
`044`	INDCV	Indennità Coltivatori Diretti	No
`077`	PS	Pensione Sociale	No
`078`	AS	Assegno Sociale	No
`094`	PI	Pensione Invalidità Civile	Sì

Altre Prestazioni¶

Codice	Sigla	Descrizione	Invalidità
`024`	SPT	Supplemento Pensione	No
`037`	PM	Pensione Minima	No
`040`	PMS	Pensione Minima Superstiti	No
`801`	DIR	Diretta (Generica)	No
`802`	INV	Invalidità (Generica)	Sì

Regola Invalidità: Tutti i codici con prefisso I (es. IO, IOS, IOP, IOART, IOCPI) rappresentano pensioni di invalidità e impostano automaticamente invalidita: true.

Sedi INPS Principali¶

Il sistema riconosce oltre 200 sedi INPS. Ecco le principali:

Grandi Città¶

Codice	Città
`7000`	Roma
`4900`	Milano
`5100`	Napoli
`8100`	Torino
`5500`	Palermo
`3400`	Genova
`1300`	Bologna
`3000`	Firenze
`0900`	Bari
`2100`	Catania

Sedi Roma (Multipli Uffici)¶

Codice	Sede
`7000`	Roma (sede centrale)
`7001`	Roma EUR
`7002`	Roma Monteverde
`7003`	Roma Ostia Lido
`7004`	Roma Montesacro
`7005`	Roma Centro
`7009`	Roma Casilino Prenestino
`7010`	Roma Tuscolano
`7012`	Roma Aurelio
`7013`	Roma Tiburtino
`7014`	Roma Flaminio

Sedi Milano (Multipli Uffici)¶

Codice	Sede
`4900`	Milano (sede centrale)
`4901`	Milano Monza
`4902`	Milano Nord
`4903`	Milano Missori
`4904`	Milano Fiori
`4905`	Milano Corvetto
`4908`	Milano Legnano
`4909`	Milano Seregno (C.O.)

Sedi Napoli (Multipli Uffici)¶

Codice	Sede
`5100`	Napoli (sede centrale)
`5102`	Napoli Nola
`5103`	Napoli Arzano
`5104`	Napoli Soccavo
`5105`	Napoli Vomero
`5106`	Napoli Pozzuoli

Parte 2 — CU per Lavoratori Dipendenti¶

Esempio Response Completa (Dipendente)¶

{
   "event":"document.processed",
   "created_at":"2026-04-10T09:12:44.118203+00:00",
   "document_id":"5f1e8c2a-9b47-4d1e-8a3c-2d7f0b6e9c11",
   "application_id":"c3a058c3-2243-4f83-92ce-d6e4fd3e89ae",
   "status":"DONE",
   "applicant_reference": "USER-002",
   "document_type":"certificazione_unica",
   "extracted_data":{
        "categoria": "certificazione_unica_dipendenti",
        "status": "ok",
        "anno_certificazione": 2026,
        "anno_fiscale": 2025,
        "codice_fiscale": "BNCLGU80A01H501Z",
        "nome": "BIANCHI LUIGI",
        "data_nascita": "01/01/1980",
        "comune_nascita": "ROMA",
        "provincia_nascita": "RM",
        "datore_codice_fiscale": "01234567890",
        "datore_denominazione": "ACME S.R.L.",
        "reddito_tempo_indeterminato": 32450.00,
        "reddito_tempo_determinato": 0.00,
        "giorni_lavoro": 365,
        "data_inizio_rapporto": "01/03/2015",
        "data_cessazione_rapporto": null,
        "in_forza_31_dicembre": true,
        "ritenute_irpef": 6842.15,
        "addizionale_regionale": 561.40,
        "addizionale_comunale_acconto": 87.60,
        "addizionale_comunale_saldo": 204.40,
        "addizionale_comunale_acconto_anno_successivo": 87.60,
        "inps_matricola_azienda": "7012345678",
        "inps_imponibile_previdenziale": 34000.00,
        "inps_contributi_lavoratore": 3124.60,
        "tfr_maturato_fino_2000": 0.00,
        "tfr_maturato_dal_2001": 18750.40,
        "tfr_fondo_pensione_fino_2000": 0.00,
        "tfr_fondo_pensione_2001_2006": 0.00,
        "tfr_fondo_pensione_dal_2007": 5200.00,
        "tfr_erogato_anno": 0.00,
        "tfr_erogato_anni_precedenti": 0.00,
        "redditi_conguagliati": [],
        "reddito_lordo_totale": 32450.00,
        "tipo_contratto": "indeterminato",
        "rapporto_attivo": true,
        "anzianita_anni": 10.8,
        "tfr_in_azienda_totale": 18750.40,
        "tfr_fondo_pensione_totale": 5200.00
   }
}

Struttura dei Dati Estratti (Dipendente)¶

La colonna Punto CU indica la casella del modello CU 2026 da cui il dato è estratto.

Datore di Lavoro (Sostituto d'Imposta)¶

Dati identificativi dell'azienda che ha rilasciato la certificazione:

{
  "datore_codice_fiscale": "01234567890",
  "datore_denominazione": "ACME S.R.L."
}

Campo	Tipo	Descrizione	Punto CU
`datore_codice_fiscale`	`string`	Codice fiscale / Partita IVA del datore di lavoro (11 cifre per società, 16 caratteri per persona fisica)	Sezione sostituto d'imposta, punto 1
`datore_denominazione`	`string`	Ragione sociale o cognome e nome del datore di lavoro	Sezione sostituto d'imposta, punto 2

Redditi e Periodo di Lavoro¶

Dati fiscali relativi ai redditi da lavoro dipendente e alla durata del rapporto:

{
  "reddito_tempo_indeterminato": 32450.00,
  "reddito_tempo_determinato": 0.00,
  "giorni_lavoro": 365,
  "data_inizio_rapporto": "01/03/2015",
  "data_cessazione_rapporto": null,
  "in_forza_31_dicembre": true
}

Campo	Tipo	Descrizione	Punto CU
`reddito_tempo_indeterminato`	`float`	Redditi di lavoro dipendente e assimilati con contratto a tempo indeterminato	1
`reddito_tempo_determinato`	`float`	Redditi di lavoro dipendente e assimilati con contratto a tempo determinato	2
`giorni_lavoro`	`integer`	Numero di giorni per i quali spettano le detrazioni (lavoro dipendente), max 365	6
`data_inizio_rapporto`	`string`	Data di inizio del rapporto di lavoro, formato GG/MM/AAAA	8
`data_cessazione_rapporto`	`string`	Data di cessazione del rapporto, formato GG/MM/AAAA; `null` se il rapporto è ancora in essere	9
`in_forza_31_dicembre`	`boolean`	`true` se la casella "In forza al 31/12" è barrata, `false` altrimenti	10

Nota: nel caso di più rapporti di lavoro nello stesso anno con lo stesso datore, la CU riporta i dati aggregati. Il sistema estrae i valori come esposti nel documento, senza ripartizione.

Ritenute e Addizionali¶

{
  "ritenute_irpef": 6842.15,
  "addizionale_regionale": 561.40,
  "addizionale_comunale_acconto": 87.60,
  "addizionale_comunale_saldo": 204.40,
  "addizionale_comunale_acconto_anno_successivo": 87.60
}

Campo	Tipo	Descrizione	Punto CU
`ritenute_irpef`	`float`	Totale ritenute IRPEF operate nell'anno	21
`addizionale_regionale`	`float`	Addizionale regionale all'IRPEF trattenuta	22
`addizionale_comunale_acconto`	`float`	Acconto addizionale comunale all'IRPEF trattenuto nell'anno fiscale	26
`addizionale_comunale_saldo`	`float`	Saldo addizionale comunale all'IRPEF trattenuto nell'anno fiscale	27
`addizionale_comunale_acconto_anno_successivo`	`float`	Acconto addizionale comunale all'IRPEF per l'anno successivo	29

Dati Previdenziali INPS¶

Sezione "Dati previdenziali ed assistenziali INPS — Lavoratori subordinati":

{
  "inps_matricola_azienda": "7012345678",
  "inps_imponibile_previdenziale": 34000.00,
  "inps_contributi_lavoratore": 3124.60
}

Campo	Tipo	Descrizione	Punto CU
`inps_matricola_azienda`	`string`	Matricola INPS dell'azienda (10 cifre)	Sezione INPS, punto 1
`inps_imponibile_previdenziale`	`float`	Imponibile ai fini previdenziali	Sezione INPS, punto 4
`inps_contributi_lavoratore`	`float`	Contributi previdenziali a carico del lavoratore trattenuti nell'anno	Sezione INPS, punto 6

Trattamento di Fine Rapporto (TFR)¶

Sezione "Trattamento di fine rapporto, indennità equipollenti, altre indennità e prestazioni in forma di capitale". Il TFR è suddiviso tra quota rimasta in azienda e quota versata a forme pensionistiche complementari (fondi pensione):

{
  "tfr_maturato_fino_2000": 0.00,
  "tfr_maturato_dal_2001": 18750.40,
  "tfr_fondo_pensione_fino_2000": 0.00,
  "tfr_fondo_pensione_2001_2006": 0.00,
  "tfr_fondo_pensione_dal_2007": 5200.00,
  "tfr_erogato_anno": 0.00,
  "tfr_erogato_anni_precedenti": 0.00
}

Campo	Tipo	Descrizione	Punto CU
`tfr_maturato_fino_2000`	`float`	TFR maturato fino al 31/12/2000 e rimasto in azienda	809
`tfr_maturato_dal_2001`	`float`	TFR maturato dal 01/01/2001 e rimasto in azienda	810
`tfr_fondo_pensione_fino_2000`	`float`	TFR maturato fino al 31/12/2000 e versato a fondo pensione	811
`tfr_fondo_pensione_2001_2006`	`float`	TFR maturato dal 01/01/2001 al 31/12/2006 e versato a fondo pensione	812
`tfr_fondo_pensione_dal_2007`	`float`	TFR maturato dal 01/01/2007 e versato a fondo pensione	813
`tfr_erogato_anno`	`float`	Indennità, acconti, anticipazioni e somme TFR erogate nell'anno	801
`tfr_erogato_anni_precedenti`	`float`	Acconti e anticipazioni TFR erogate in anni precedenti	802

Nota: per le operazioni di cessione del quinto, il TFR rilevante come garanzia è quello rimasto in azienda (punti 809–810). Le quote versate ai fondi pensione (811–813) non sono nella disponibilità del datore di lavoro.

Redditi Conguagliati da Altri Soggetti¶

Sezione "Dati relativi ai conguagli" (punti 531 e seguenti). Presente quando il datore ha conguagliato redditi erogati da altri sostituti d'imposta nello stesso anno (es. precedente datore di lavoro, indennità INPS):

{
  "redditi_conguagliati": [
    {
      "codice_fiscale_erogante": "09876543210",
      "importo": 4120.00
    }
  ]
}

Campo	Tipo	Descrizione	Punto CU
`redditi_conguagliati`	`array`	Elenco dei redditi erogati da altri soggetti e conguagliati dal datore. Array vuoto `[]` se la sezione non è compilata	531 e seguenti
`redditi_conguagliati[].codice_fiscale_erogante`	`string`	Codice fiscale del soggetto che ha erogato il reddito	Sezione conguagli
`redditi_conguagliati[].importo`	`float`	Importo del reddito conguagliato	Sezione conguagli

Dati Arricchiti (Derivati)¶

Il sistema calcola automaticamente alcuni campi di sintesi a partire dai dati estratti:

{
  "reddito_lordo_totale": 32450.00,
  "tipo_contratto": "indeterminato",
  "rapporto_attivo": true,
  "anzianita_anni": 10.8,
  "tfr_in_azienda_totale": 18750.40,
  "tfr_fondo_pensione_totale": 5200.00
}

Campo	Tipo	Descrizione	Derivato da
`reddito_lordo_totale`	`float`	Reddito lordo complessivo da lavoro dipendente	`reddito_tempo_indeterminato` + `reddito_tempo_determinato`
`tipo_contratto`	`string`	`"indeterminato"`, `"determinato"` o `"misto"` (entrambi i punti 1 e 2 valorizzati)	Punti 1 e 2
`rapporto_attivo`	`boolean`	`true` se il rapporto risulta in essere a fine anno	`in_forza_31_dicembre == true` e `data_cessazione_rapporto == null`
`anzianita_anni`	`float`	Anzianità di servizio in anni (1 decimale), calcolata al 31/12 dell'anno fiscale o alla data di cessazione	`data_inizio_rapporto`, `data_cessazione_rapporto`, `anno_fiscale`
`tfr_in_azienda_totale`	`float`	TFR complessivo accantonato presso il datore di lavoro	Punti 809 + 810
`tfr_fondo_pensione_totale`	`float`	TFR complessivo versato a forme pensionistiche complementari	Punti 811 + 812 + 813

Validazioni Automatiche¶

Le validazioni si applicano ad entrambe le categorie, salvo dove indicato.

Codice Fiscale¶

Il sistema applica validazioni e correzioni automatiche per errori tipici di OCR:

Conversione tra caratteri simili nelle posizioni corrette (es. 0 ↔ O, 1 ↔ I, 5 ↔ S, 8 ↔ B, 2 ↔ Z)
Validazione contro il pattern ufficiale italiano: 6 lettere + 2 cifre + 1 lettera + 2 cifre + 1 lettera + 3 cifre + 1 lettera

Esempio correzione:

Input OCR errato: R05SMR8651115F2O5X
Output corretto: RSSMRA65H15F205X

Codice fiscale del datore di lavoro (datore_codice_fiscale, solo dipendenti): accettato sia nel formato numerico a 11 cifre (società, con validazione del check digit della Partita IVA) sia nel formato alfanumerico a 16 caratteri (ditta individuale / persona fisica), con le stesse correzioni OCR.

Codice Prestazione (solo pensionati)¶

Validazione lunghezza: Esattamente 15 cifre numeriche dopo rimozione spazi

Formati accettati:

Continuo: 001500009184109
Con spazio: 001 500009184109
Normalizzazione: Tutti gli spazi vengono rimossi

Validazione prefisso: Le prime 3 cifre devono corrispondere a un codice pensione valido (vedere tabella classificazioni)

Nota: Codici prestazione con prefisso non riconosciuto vengono comunque estratti ma con codice_pensione_descrizione: "XXX - Categoria sconosciuta"

Importi¶

Regole di validazione:

Conversione automatica in valori assoluti (positivi)
Formato: float con 2 decimali
Separatore decimale: punto (.)
Nessun simbolo di valuta (€ rimosso)
Caselle non compilate nel modello CU → 0.00 (non null), per consentire somme e confronti senza controlli aggiuntivi

Esempio trasformazioni:

Input: "18.500,50 €" → Output: 18500.50
Input: "-3.250,75" → Output: 3250.75
Input: "1250.00" → Output: 1250.00
Input: casella vuota → Output: 0.00

Date¶

Formato di output: GG/MM/AAAA
decorrenza_inizio (pensionati) può essere anche MM/AAAA se il documento riporta solo mese e anno
Le date vengono validate come date di calendario reali (es. 31/02/2020 viene rifiutata e il campo impostato a null)
data_cessazione_rapporto (dipendenti) è null se la casella non è compilata

Caselle Barrate¶

I campi booleani derivati da caselle del modello (es. in_forza_31_dicembre) valgono true solo se la casella risulta chiaramente barrata (X); in tutti gli altri casi valgono false.

Gestione Campi Null¶

Campi opzionali possono essere null se non presenti nel documento:

{
  "decorrenza_inizio": null,
  "provincia_nascita": null,
  "comune_nascita": null,
  "data_cessazione_rapporto": null
}

Best Practice: Verifica sempre la presenza del campo prima dell'utilizzo in logica applicativa. Gli importi, al contrario, non sono mai null: una casella vuota produce 0.00.

Campi Obbligatori¶

Se uno dei seguenti campi non viene estratto, l'elaborazione fallisce con status: "error":

Categoria	Campi obbligatori
Entrambe	`codice_fiscale`, `nome`, `anno_fiscale`
`certificazione_unica_pensionati`	`codice_prestazione`, `pensione_lorda`
`certificazione_unica_dipendenti`	`datore_codice_fiscale`, almeno uno tra `reddito_tempo_indeterminato` e `reddito_tempo_determinato` diverso da zero

Confronto con Altri Documenti¶

CU vs Busta Paga¶

Caratteristica	Certificazione Unica	Busta Paga
Frequenza	Annuale (una per anno fiscale)	Mensile
Emittente	INPS (pensionati) o datore di lavoro (dipendenti)	Azienda privata o PA
Contenuto	Reddito annuale + ritenute totali	Dettaglio mensile competenze/trattenute
Uso principale	Dichiarazione redditi (730/Redditi PF)	Verifica stipendio mensile
Dettaglio voci	Totali aggregati	Voci singole dettagliate
TFR	Accantonato al 31/12 (solo dipendenti)	Quota maturata nel mese
Codice identificativo	Codice prestazione (pensionati) / matricola INPS azienda (dipendenti)	Matricola aziendale del dipendente

CU INPS (Pensionati) vs CU Dipendenti¶

Caratteristica	CU INPS (`certificazione_unica_pensionati`)	CU Dipendenti (`certificazione_unica_dipendenti`)
Sostituto d'imposta	INPS	Datore di lavoro
Codice identificativo	Codice prestazione (15 cifre)	CF datore + matricola INPS azienda
Redditi	Solo pensioni (punto 3)	Lavoro dipendente a tempo indeterminato / determinato (punti 1–2)
Periodo di lavoro	Decorrenza pensione	Data inizio / cessazione rapporto, in forza al 31/12
Contributi	Non presenti (già versati)	Imponibile e contributi INPS a carico lavoratore
TFR	Non presente	Quota in azienda e quota a fondo pensione
Conguagli	Non presenti	Redditi conguagliati da altri soggetti
Campi derivati	Tipo pensione, sede, invalidità	Tipo contratto, anzianità, totali TFR

Domande Frequenti (FAQ)¶

Generali¶

Q: Come distinguo una CU di un pensionato da quella di un dipendente? A: Controlla il campo categoria:

"certificazione_unica_pensionati" → CU INPS, sono valorizzati i campi della Parte 1
"certificazione_unica_dipendenti" → CU del datore di lavoro, sono valorizzati i campi della Parte 2

I campi comuni (metadati e anagrafica) sono sempre presenti.

Q: Perché il mio codice fiscale è stato modificato? A: Il sistema applica correzioni automatiche per errori tipici di OCR (es. 0/O, 1/I). Il CF viene validato contro il pattern ufficiale italiano.

Q: Quante pagine può avere una CU? A: La CU INPS ha generalmente 1-2 pagine; la CU dipendenti può arrivare a 4-6 pagine (comprese le sezioni annotazioni e previdenziali). Il sistema processa tutte le pagine del PDF.

Q: Gli importi includono già le detrazioni? A: No. I redditi (pensione_lorda, reddito_tempo_indeterminato, ecc.) sono lordi e le ritenute sono le sole imposte trattenute. Per un netto approssimativo: netto ≈ reddito lordo - ritenute_irpef - addizionali.

Q: I numeri di "punto" sono stabili nel tempo? A: No. Fanno riferimento al modello CU 2026. L'Agenzia delle Entrate può rinumerare le caselle nei modelli successivi; i nomi dei campi in extracted_data restano invece stabili.

Pensionati¶

Q: Il codice prestazione è sempre presente? A: Sì, è un campo obbligatorio per la categoria certificazione_unica_pensionati. Se non viene estratto, l'elaborazione fallisce con status: "error".

Q: Cosa succede se il codice prestazione non è riconosciuto? A: Il codice viene comunque estratto, ma i campi derivati mostrano:

codice_pensione_descrizione: "XXX - Categoria sconosciuta"
codice_sede_descrizione: "YYYY - Sede sconosciuta"
invalidita: null

Q: Come posso distinguere una pensione di vecchiaia da una di invalidità? A: Controlla il campo invalidita:

true → Pensione di invalidità
false → Altro tipo di pensione (vecchiaia, superstiti, ecc.)

Q: La data di decorrenza può essere null? A: Sì, se non è presente nel documento CU. È un campo opzionale.

Q: I codici sede includono anche uffici periferici? A: Sì, il sistema riconosce oltre 215 sedi INPS inclusi uffici distrettuali e periferici (es. "Roma EUR", "Milano Nord", ecc.).

Dipendenti¶

Q: Come capisco se il rapporto di lavoro è ancora attivo? A: Usa il campo derivato rapporto_attivo, che combina in_forza_31_dicembre e data_cessazione_rapporto. Se vuoi il dato grezzo, data_cessazione_rapporto è null quando il rapporto non è cessato.

Q: Qual è la differenza tra tfr_maturato_* e tfr_fondo_pensione_*? A: tfr_maturato_fino_2000 e tfr_maturato_dal_2001 (punti 809–810) sono le quote rimaste accantonate in azienda. tfr_fondo_pensione_* (punti 811–813) sono le quote destinate a forme pensionistiche complementari. Per i totali usa tfr_in_azienda_totale e tfr_fondo_pensione_totale.

Q: Il dipendente ha cambiato lavoro durante l'anno: cosa trovo nella CU? A: La CU del datore attuale può riportare i redditi del precedente datore nella sezione conguagli (redditi_conguagliati). I punti 1–2 contengono invece solo i redditi erogati dal datore che ha rilasciato la CU.

Q: giorni_lavoro può essere inferiore a 365? A: Sì, se il rapporto è iniziato o cessato in corso d'anno, oppure in presenza di periodi non coperti da detrazioni. Usalo insieme a data_inizio_rapporto e data_cessazione_rapporto per interpretare il reddito annuo.

Q: tipo_contratto è "misto": cosa significa? A: Sia il punto 1 (tempo indeterminato) che il punto 2 (tempo determinato) sono valorizzati: tipicamente il lavoratore è stato trasformato da determinato a indeterminato in corso d'anno con lo stesso datore.

Q: redditi_conguagliati è un array vuoto: è un errore? A: No. Significa che la sezione conguagli (punti 531 e seguenti) non è compilata: il datore non ha conguagliato redditi erogati da altri soggetti.

Certificazione unica Descrizione del Documento Riconoscimento della Categoria Campi Comuni Metadati di Elaborazione Informazioni Anagrafiche Esempio Response Completa (Pensionato)Struttura dei Dati Estratti (Pensionato)Informazioni sulla Pensione Dati Arricchiti (Derivati)Classificazione Tipi di Pensione Pensioni Ordinarie Pensioni Privilegiate Pensioni Speciali Pensioni Settori Speciali Pensioni Casse Professionali Prestazioni Assistenziali Altre Prestazioni Sedi INPS Principali Grandi Città Sedi Roma (Multipli Uffici)Sedi Milano (Multipli Uffici)Sedi Napoli (Multipli Uffici)Esempio Response Completa (Dipendente)Struttura dei Dati Estratti (Dipendente)Datore di Lavoro (Sostituto d'Imposta)Redditi e Periodo di Lavoro Ritenute e Addizionali Dati Previdenziali INPS Trattamento di Fine Rapporto (TFR)Redditi Conguagliati da Altri Soggetti Dati Arricchiti (Derivati)Codice Fiscale Codice Prestazione (solo pensionati)Importi Date Caselle Barrate Gestione Campi Null Campi Obbligatori CU vs Busta Paga CU INPS (Pensionati) vs CU Dipendenti Generali Pensionati Dipendenti