Busta Paga - Dati Estratti¶

Totale delle voci estratte da una busta paga (cedolini stipendio privati e statali/PA).

Tipi di Documento Supportati¶

Il sistema supporta due tipi di buste paga:

Document Type	Descrizione	Settore
`busta_paga`	Busta paga settore privato	Aziende private, S.r.l., S.p.A., ditte individuali
`busta_paga_statale`	Cedolino stipendiale PA/NOIPA	Ministeri, Scuole, Università, ASL, Enti Pubblici

Nota: Il sistema utilizza un'estrazione unificata con configurazioni specifiche per ogni tipo.

Esempio Response - Busta Paga Privata¶

{
   "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":"busta_paga",
   "extracted_data":{
        "basic_info": {
          "nome_dipendente": "ROSSI MARIO GIOVANNI",
          "codice_fiscale": "RSSMRA85M15H501Z",
          "p_iva": "01234567890",
          "posizione_inail": "12345678",
          "id_cedolino": "188D9DDF",
          "posizione_inps": "9876543210",
          "datore_lavoro": "TECH SOLUTIONS S.R.L.",
          "ccnl": "Commercio e Servizi",
          "tipo_contratto": "Indeterminato",
          "mansione": "SVILUPPATORE SOFTWARE",
          "data_assunzione": "15/01/2020",
          "assunzione_convenzionale": "15/01/2020",
          "periodo_paga": "GIUGNO 2025",
          "data_cessazione": null,
          "tempo_determinato": false,
          "iban": "IT60X0542811101000000123456",
          "totale_competenze": 2850.75,
          "stipendio_netto": 1950.30,
          "totale_lordo": 2850.75,
          "data_nascita": "15/08/1985",
          "sesso": "M",
          "luogo_nascita": "Roma",
          "tfr": 237.56,
          "tfr_accumulato": 20000.00,
          "part_time": false,
          "residenza_dipendente_via": "Via Giuseppe Garibaldi 25",
          "residenza_dipendente_citta": "MILANO",
          "indirizzo_azienda": "Via Dante Alighieri 42",
          "citta_azienda": "MILANO",
          "atc_additional_info": {
              "partita_iva_verificata": "01234567890",
              "pec": "info@techsolutions.pec.it",
              "numero_dipendenti": "150"
          },
          "message": "Basic info processate con successo",
          "status_basic_info": "ok",
          "extraction_errors": null
        },
        "extra_info": {
          "status_extra_info": "ok",
          "message": "Extra info processate con successo",
          "output_deductions": [
            {
              "voce": "32100",
              "descrizione": "ritenute irpef",
              "trattenute": 450.80,
              "codice": "32100",
              "classificazione_voce": "ritenute_fiscali"
            },
            {
              "voce": "1800",
              "descrizione": "addizionale regionale",
              "trattenute": 85.50,
              "codice": "1800",
              "classificazione_voce": "addizionali"
            },
            {
              "voce": "39400",
              "descrizione": "contributi inps",
              "trattenute": 285.00,
              "codice": "39400",
              "classificazione_voce": "contributi_previdenziali"
            },
            {
              "voce": "2001",
              "descrizione": "cessione quinto stipendio",
              "trattenute": 320.50,
              "codice": "2001",
              "classificazione_voce": "cessione_quinto"
            },
            {
              "voce": "2501",
              "descrizione": "buoni pasto mensa",
              "trattenute": 78.00,
              "codice": "2501",
              "classificazione_voce": "mensa"
            }
          ],
          "output_earnings": [
            {
              "voce": "8001",
              "descrizione": "lavoro ordinario ore",
              "ore/giorni": "168,00",
              "base": "15,50",
              "competenze": 2604.00,
              "valore_unitario": 15.50,
              "codice": "8001",
              "classificazione_voce": "retribuzione_base"
            },
            {
              "voce": "8108",
              "descrizione": "festività non goduta",
              "ore/giorni": "8,00",
              "base": "15,50",
              "competenze": 124.00,
              "valore_unitario": 15.50,
              "codice": "8108",
              "classificazione_voce": "indennita"
            },
            {
              "voce": "8201",
              "descrizione": "lavoro straordinario",
              "ore/giorni": "12,00",
              "base": "19,50",
              "competenze": 234.00,
              "valore_unitario": 19.50,
              "codice": "8201",
              "classificazione_voce": "straordinario"
            },
            {
              "voce": "8301",
              "descrizione": "tredicesima mensilità",
              "competenze": 2170.83,
              "codice": "8301",
              "classificazione_voce": "mensilità_aggiuntive"
            },
            {
              "voce": "8501",
              "descrizione": "premio produzione",
              "competenze": 500.00,
              "codice": "8501",
              "classificazione_voce": "bonus"
            }
          ]
        }
   }
}

Esempio Response - Busta Paga Statale (PA/NOIPA)¶

{
   "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":"busta_paga_statale",
   "extracted_data":{
        "basic_info": {
          "nome_dipendente": "BIANCHI GIULIA",
          "codice_fiscale": "BNCGLI80D45F205X",
          "posizione_inail": null,
          "posizione_inps": "1234567890",
          "id_cedolino": "188D9DDF",
          "datore_lavoro": "MINISTERO DELL'ISTRUZIONE",
          "codice_fiscale_ente" : "80184250588", 
          "amministrazione_appartenenza": "MINISTERO DELLA GIUSTIZIA",
          "ufficio_responsabile": "RTS di GENOVA",
          "ufficio_servizio": "0203-CASA CIRCONDARIALE 'MARASSI'",
          "ccnl": "Funzione Pubblica",
          "tipo_contratto": "Indeterminato",
          "mansione": "FUNZIONARIO",
          "data_assunzione": "01/09/2015",
          "assunzione_convenzionale": null,
          "periodo_paga": "GIUGNO 2025",
          "data_cessazione": null,
          "tempo_determinato": false,
          "iban": "IT60X0542811101000000789012",
          "totale_competenze": 2650.50,
          "stipendio_netto": 1850.75,
          "totale_lordo": 2650.50,
          "data_nascita": "05/04/1980",
          "sesso": "F",
          "luogo_nascita": "Milano",
          "tfr": 220.42,
          "tfr_accumulato": 25000.00,
          "part_time": false,
          "quinto_cedibile": 23000.50,
          "residenza_dipendente_via": "Via Alessandro Manzoni 18",
          "residenza_dipendente_citta": "GENOVA",
          "indirizzo_azienda": "Via Michele Carcani 61",
          "citta_azienda": "ROMA",
          "atc_additional_info": {             
              "pec": null,
              "codice_fiscale_ente" : "80184250588"              
          },
          "message": "Basic info processate con successo",
          "status_basic_info": "ok",
          "extraction_errors": null
        },
        "extra_info": {
          "status_extra_info": "ok",
          "message": "Extra info processate con successo",
          "output_deductions": [
            {
              "voce": "32100",
              "descrizione": "ritenute irpef",
              "trattenute": 450.80,
              "codice": "32100",
              "classificazione_voce": "ritenute_fiscali"
            },
            {
              "voce": "1800",
              "descrizione": "addizionale regionale",
              "trattenute": 85.50,
              "codice": "1800",
              "classificazione_voce": "addizionali"
            },
            {
              "voce": "39400",
              "descrizione": "contributi inps",
              "trattenute": 285.00,
              "codice": "39400",
              "classificazione_voce": "contributi_previdenziali"
            },
            {
              "voce": "2001",
              "descrizione": "cessione quinto stipendio",
              "trattenute": 320.50,
              "codice": "2001",
              "classificazione_voce": "cessione_quinto"
            },
            {
              "voce": "2501",
              "descrizione": "buoni pasto mensa",
              "trattenute": 78.00,
              "codice": "2501",
              "classificazione_voce": "mensa"
            }
          ],
          "output_earnings": [
            {
              "voce": "8001",
              "descrizione": "lavoro ordinario ore",
              "ore/giorni": "168,00",
              "base": "15,50",
              "competenze": 2604.00,
              "valore_unitario": 15.50,
              "codice": "8001",
              "classificazione_voce": "retribuzione_base"
            },
            {
              "voce": "8108",
              "descrizione": "festività non goduta",
              "ore/giorni": "8,00",
              "base": "15,50",
              "competenze": 124.00,
              "valore_unitario": 15.50,
              "codice": "8108",
              "classificazione_voce": "indennita"
            },
            {
              "voce": "8201",
              "descrizione": "lavoro straordinario",
              "ore/giorni": "12,00",
              "base": "19,50",
              "competenze": 234.00,
              "valore_unitario": 19.50,
              "codice": "8201",
              "classificazione_voce": "straordinario"
            },
            {
              "voce": "8301",
              "descrizione": "tredicesima mensilità",
              "competenze": 2170.83,
              "codice": "8301",
              "classificazione_voce": "mensilità_aggiuntive"
            },
            {
              "voce": "8501",
              "descrizione": "premio produzione",
              "competenze": 500.00,
              "codice": "8501",
              "classificazione_voce": "bonus"
            }
          ]
        }
   }
}

Informazioni di Base (basic_info)¶

La sezione basic_info contiene tutti i dati anagrafici e contrattuali principali:

Dati Dipendente¶

{
  "nome_dipendente": "ROSSI MARIO GIOVANNI",
  "codice_fiscale": "RSSMRA85M15H501Z",
  "data_nascita": "15/08/1985",
  "sesso": "M",
  "luogo_nascita": "Roma",
  "residenza_dipendente_via": "Via Giuseppe Garibaldi 25",
  "residenza_dipendente_citta": "MILANO"
}

Dati Azienda (Privato)¶

{
  "datore_lavoro": "TECH SOLUTIONS S.R.L.",
  "p_iva": "01234567890",
  "indirizzo_azienda": "Via Dante Alighieri 42",
  "citta_azienda": "MILANO",
  "posizione_inail": "12345678",
  "posizione_inps": "9876543210"
}

Datore di Lavoro Persona Fisica (Privato — caso speciale)¶

Quando il datore di lavoro è una persona fisica (ditta individuale, libero professionista, datore domestico ecc.) il documento non contiene né Partita IVA né un codice fiscale aziendale numerico a 11 cifre. In questo caso il sistema esegue un fallback mirato e, se trovato e validato, restituisce i seguenti campi aggiuntivi in basic_info:

{
  "codice_fiscale_datore_persona_fisica": "BNCMRC60M15H501Z",
  "nome_datore_persona_fisica": "BIANCHI MARCO",
  "tipo_datore_lavoro": "persona_fisica"
}

Campo	Tipo	Descrizione
`codice_fiscale_datore_persona_fisica`	`string`	CF alfanumerico di 16 caratteri del datore/titolare persona fisica
`nome_datore_persona_fisica`	`string \| null`	Nome e cognome del datore se riportato nel cedolino accanto al CF
`tipo_datore_lavoro`	`string`	Sempre `"persona_fisica"` quando questi campi sono presenti

Nota: questi campi compaiono solo quando p_iva è null e non è stato trovato un CF aziendale numerico, ma è presente un CF dipendente validato. Se il fallback non trova nulla i campi non vengono inclusi nella risposta.

Dati Ente Pubblico (Statale)¶

{
  "datore_lavoro": "MINISTERO DELL'ISTRUZIONE",
  "amministrazione_appartenenza": "MINISTERO DELLA GIUSTIZIA",
  "ufficio_responsabile": "RTS di GENOVA",
  "ufficio_servizio": "0203-CASA CIRCONDARIALE 'MARASSI'",
  "indirizzo_azienda": "Via Michele Carcani 61",
  "citta_azienda": "ROMA",
  "posizione_inail": null,
  "posizione_inps": "1234567890"
}

Note PA/NOIPA:

p_iva: sempre null per enti pubblici

amministrazione_appartenenza: Amministrazione centrale di riferimento

ufficio_responsabile: Ufficio che gestisce la partita stipendiale (es. RTS)

ufficio_servizio: Sede lavorativa effettiva del dipendente

codice_fiscale_ente: Codice Fiscale dell'ente pubblico

quinto_cedibile: importo del quinto cedibile

Dati Contrattuali¶

{
  "ccnl": "Commercio e Servizi",
  "tipo_contratto": "Indeterminato",
  "mansione": "SVILUPPATORE SOFTWARE",
  "data_assunzione": "15/01/2020",
  "assunzione_convenzionale": "15/01/2020",
  "data_cessazione": null,
  "tempo_determinato": false
}

Nota: tipo_contratto può avere i possibili valori : "indeterminato",

"determinato", "apprendistato", "interinale", "stage", "indeterminato_con_prova",.

Cessazione del Rapporto e Tempo Determinato¶

data_cessazione e tempo_determinato non vengono presi dal modello di lettura: sono calcolati dal sistema con una regola deterministica, per evitare che una data letta male o copiata da un altro campo faccia risultare a termine un rapporto che non lo è.

{
  "data_cessazione": "31/12/2026",
  "tempo_determinato": true
}

Campo	Tipo	Descrizione	Esempio
`data_cessazione`	string	null	Data di fine rapporto (DD/MM/YYYY). Valorizzata solo se esplicitamente etichettata sul cedolino come cessazione, fine rapporto o scadenza contratto
`tempo_determinato`	boolean	`true` quando esiste una `data_cessazione` valida, `false` altrimenti. Sempre presente	true

Quando data_cessazione viene restituita null (e di conseguenza tempo_determinato è false):

la data non è esplicitamente etichettata come cessazione sul documento
la data non è completa (per esempio solo mese e anno)
la data coincide con data_assunzione, assunzione_convenzionale, data_nascita o periodo_paga
la data è odierna o passata

Importante per gli integratori: l'ultimo punto significa che un cedolino che riporta una cessazione già avvenuta viene restituito con data_cessazione: null e tempo_determinato: false. L'assenza di una data di fine non va quindi interpretata da sola come "rapporto ancora in corso".

Periodo e Importi¶

{
  "periodo_paga": "GIUGNO 2025",
  "iban": "IT60X0542811101000000123456",
  "totale_competenze": 2850.75,
  "stipendio_netto": 1950.30,
  "totale_lordo": 2850.75,
  "tfr": 237.56,
  "tfr_accumulato": 20000.00,
  "part_time": false
}

Nuovi Campi¶

Campo	Tipo	Descrizione
`tfr_accumulato`	`number`	Fondo TFR accumulato fino alla data del cedolino (migliaia di euro)
`part_time`	`boolean`	`true` se contratto part-time, `false` se full-time
`tempo_determinato`	`boolean`	`true` se il rapporto ha una data di cessazione valida e futura, `false` altrimenti. Vedi Cessazione del Rapporto e Tempo Determinato

Verifica Partita IVA (solo Privato)¶

{
  "atc_additional_info": {
    "partita_iva_verificata": "01234567890",
    "pec": "info@techsolutions.pec.it",
    "numero_dipendenti": "150"
  }
}

Nota: Per document_type: "busta_paga_statale", in atc_additional_info il campo P.IVA e numero_dipendenti non sono presenti perchè non è applicabile agli enti pubblici.

Status Elaborazione¶

{
  "message": "Basic info processate con successo",
  "status_basic_info": "ok",
  "extraction_errors": null
}

Campo	Tipo	Descrizione	Esempio
`status_basic_info`	string	Esito dell'estrazione: `"ok"` oppure `"partial"`	"ok"
`message`	string	Descrizione dell'esito	"Basic info processate con successo"
`extraction_errors`	array[string]	null	Blocchi di estrazione falliti. `null` quando l'esito è `"ok"`

Estrazione Parziale (status_basic_info: "partial")¶

I dati di basic_info vengono estratti da tre letture indipendenti del cedolino, una per gruppo di campi. Se una di queste fallisce, le altre vengono comunque restituite e l'esito diventa "partial".

Blocco	Campi interessati	Valore in `extraction_errors`
Anagrafica dipendente	`nome_dipendente`, `codice_fiscale`, `data_nascita`, `sesso`, `luogo_nascita`, residenza	`anagrafica_dipendente`
Azienda e contratto	`datore_lavoro`, `p_iva`, `ccnl`, `tipo_contratto`, `mansione`, date, `periodo_paga`	`dati_azienda_contratto`
Dati retributivi	`stipendio_netto`, `totale_lordo`, `totale_competenze`, `tfr`, `tfr_accumulato`	`dati_retributivi`

{
  "message": "Estrazione parziale, errori in: ['dati_retributivi']",
  "status_basic_info": "partial",
  "extraction_errors": ["dati_retributivi"]
}

Quando l'errore è dovuto a un problema tecnico, il dettaglio viene riportato fra parentesi accanto al nome del blocco:

{
  "extraction_errors": ["dati_retributivi (429 Too Many Requests)"]
}

Importante per gli integratori: in caso di estrazione parziale il webhook viene comunque inviato con "status": "DONE", perché il documento è stato elaborato. I campi del blocco fallito sono però assenti o null: se salta dati_retributivi, la risposta contiene anagrafica e datore corretti ma nessun importo. Verificare sempre extracted_data.basic_info.status_basic_info oltre allo status del webhook.

Competenze (extra_info.output_earnings)¶

Le competenze includono tutti gli importi che compongono lo stipendio lordo:

Retribuzione Base¶

{
  "voce": "8001",
  "descrizione": "lavoro ordinario ore",
  "ore/giorni": "168,00",
  "base": "15,50",
  "competenze": 2604.00,
  "valore_unitario": 15.50,
  "codice": "8001",
  "classificazione_voce": "retribuzione_base"
}

Straordinari¶

{
  "voce": "8201",
  "descrizione": "lavoro straordinario ore",
  "ore/giorni": "12,00",
  "base": "19,50",
  "competenze": 234.00,
  "valore_unitario": 19.50,
  "codice": "8201",
  "classificazione_voce": "straordinario"
}

Mensilità Aggiuntive¶

{
  "voce": "8301",
  "descrizione": "tredicesima mensilità",
  "competenze": 2170.83,
  "codice": "8301",
  "classificazione_voce": "mensilità_aggiuntive"
}

Bonus e Rimborsi¶

{
  "voce": "8501",
  "descrizione": "premio produzione",
  "competenze": 500.00,
  "codice": "8501",
  "classificazione_voce": "bonus"
},
{
  "voce": "8601",
  "descrizione": "rimborso chilometrico",
  "competenze": 125.50,
  "codice": "8601",
  "classificazione_voce": "rimborso"
}

Anticipi¶

{
  "voce": "8701",
  "descrizione": "anticipo stipendio",
  "competenze": 800.00,
  "codice": "8701",
  "classificazione_voce": "anticipo_retribuzione"
},
{
  "voce": "8702",
  "descrizione": "anticipo tfr",
  "competenze": 1500.00,
  "codice": "8702",
  "classificazione_voce": "anticipo_tfr"
}

Agevolazioni Speciali¶

{
  "voce": "8801",
  "descrizione": "permessi legge 104",
  "ore/giorni": "8,00",
  "base": "15,50",
  "competenze": 124.00,
  "valore_unitario": 15.50,
  "codice": "8801",
  "classificazione_voce": "legge104"
},
{
  "voce": "8802",
  "descrizione": "indennità maternità",
  "competenze": 980.50,
  "codice": "8802",
  "classificazione_voce": "maternita"
}

Trattenute (extra_info.output_deductions)¶

Le trattenute rappresentano tutti gli importi detratti dallo stipendio lordo:

Ritenute Fiscali¶

{
  "voce": "32100",
  "descrizione": "ritenute irpef",
  "trattenute": 450.80,
  "codice": "32100",
  "classificazione_voce": "ritenute_fiscali"
}

Addizionali¶

{
  "voce": "1800",
  "descrizione": "addizionale regionale",
  "trattenute": 85.50,
  "codice": "1800",
  "classificazione_voce": "addizionali"
}

Contributi Previdenziali¶

{
  "voce": "39400",
  "descrizione": "contributi inps",
  "trattenute": 285.00,
  "codice": "39400",
  "classificazione_voce": "contributi_previdenziali"
}

Prestiti e Cessioni¶

{
  "voce": "2001",
  "descrizione": "cessione quinto stipendio",
  "trattenute": 320.50,
  "codice": "2001",
  "classificazione_voce": "cessione_quinto"
},
{
  "voce": "2101",
  "descrizione": "prestito aziendale",
  "trattenute": 150.00,
  "codice": "2101",
  "classificazione_voce": "prestiti_aziendali"
}

Pignoramenti e Recuperi¶

{
  "voce": "2201",
  "descrizione": "pignoramento stipendio",
  "trattenute": 400.00,
  "codice": "2201",
  "classificazione_voce": "pignoramenti_sequestri"
},
{
  "voce": "2301",
  "descrizione": "recupero ferie eccedenti",
  "trattenute": 180.25,
  "codice": "2301",
  "classificazione_voce": "recuperi_rimborsi"
}

Malattia e Servizi¶

{
  "voce": "2401",
  "descrizione": "trattenuta giorni malattia",
  "trattenute": 95.30,
  "codice": "2401",
  "classificazione_voce": "malattia_trattenute"
},
{
  "voce": "2501",
  "descrizione": "buoni pasto mensa",
  "trattenute": 78.00,
  "codice": "2501",
  "classificazione_voce": "mensa"
}

Voci Varie¶

{
  "voce": "32087",
  "descrizione": "arrotondamento",
  "trattenute": 0.18,
  "codice": "32087",
  "classificazione_voce": "sconosciuto"
}

Classificazioni Voci¶

Competenze (Earnings)¶

Classificazione	Descrizione	Esempi
`retribuzione_base`	Importo base dello stipendio	Lavoro ordinario, paga base, ore normali
`straordinario`	Straordinari di vario tipo	Lavoro straordinario, ore extra, festivo
`mensilità_aggiuntive`	Tredicesima e quattordicesima	13ª mensilità, 14ª mensilità
`indennita`	Indennità di vario tipo	Indennità turno, trasferta, responsabilità
`bonus`	Bonus di vario tipo	Premio produzione, bonus obiettivi
`rimborso`	Rimborsi spese trasferte	Rimborso km, vitto, alloggio
`anticipo_retribuzione`	Anticipo stipendio	Acconto mensile, anticipo ferie
`anticipo_tfr`	Anticipo trattamento fine rapporto	Anticipo TFR, prestito aziendale TFR
`legge104`	Contributi per legge 104	Permessi legge 104, agevolazioni
`maternita`	Contributi per maternità	Indennità maternità, congedo parentale
`cassa_edile`	Accantonamenti Cassa Edile (quota a credito)	Accantonamento CE, assogg. contributi edili
`tfr_fondo_pensione`	Quota TFR/contributi a fondo pensione complementare (quota ditta)	Fondo Prevedi ditta, TFR conferito al fondo
`sconosciuto`	Voci non classificate	Altre competenze non riconosciute

Trattenute (Deductions)¶

Classificazione	Descrizione	Esempi
`cessione_quinto`	Trattenute per prestito quinto	Cessione quinto stipendio, rata prestito
`prestiti_aziendali`	Prestiti a vario titolo con azienda	Anticipo aziendale, prestito dipendenti
`delega_pagamento`	Trattenute per delega di pagamento	Delega, delega di pagamento, prestito esterno
`pignoramenti_sequestri`	Pignoramenti e sequestri	Pignoramento stipendio, decreto ingiuntivo
`recuperi_rimborsi`	Recuperi e rimborsi rateali	Recupero ferie, rimborso anticipi
`contributi_previdenziali`	Contributi INPS/INAIL	Contributi pensionistici, assistenziali
`ritenute_fiscali`	Ritenute fiscali IRPEF	IRPEF, ritenute d'acconto
`malattia_trattenute`	Trattenute per malattia	Giorni di carenza, trattenute INPS
`addizionali`	Addizionali comunali/regionali	Addizionale regionale, comunale IRPEF
`mensa`	Trattenute per mensa	Buoni pasto, servizio mensa aziendale
`cassa_edile`	Trattenute e contributi Cassa Edile	Recupero accant. CE, contributo C.Edile
`tfr_fondo_pensione`	Quota TFR destinata a fondo pensione complementare	TFR a fondo pensione, FPC, Prevedi
`sconosciuto`	Voci non classificate	Altre trattenute non riconosciute

Differenze tra Privato e Statale¶

Campi Presenti Solo nel Privato¶

Campo	Descrizione
`p_iva`	Partita IVA azienda (11 cifre)
`atc_additional_info.partita_iva_verificata`	P.IVA verificata online
`atc_additional_info.pec`	PEC aziendale
`atc_additional_info.numero_dipendenti`	Numero dipendenti
`codice_fiscale_datore_persona_fisica`	CF del datore persona fisica (solo quando assenti P.IVA e CF aziendale)
`nome_datore_persona_fisica`	Nome e cognome del datore persona fisica (condizionale)
`tipo_datore_lavoro`	`"persona_fisica"` quando il datore è una persona fisica (condizionale)

Campi Presenti Solo nello Statale¶

Campo	Descrizione
`amministrazione_appartenenza`	Nome amministrazione principale (es. Ministero)
`ufficio_responsabile`	Ufficio che gestisce la partita stipendiale (es. RTS)
`ufficio_servizio`	Sede lavorativa effettiva del dipendente

Campi Comuni¶

Tutti gli altri campi (nome_dipendente, codice_fiscale, periodo_paga, stipendio_netto, data_cessazione, tempo_determinato, ecc.) sono presenti in entrambi i tipi di documento.

Note Implementative¶

Gestione Campi Null¶

I campi null indicano dati non presenti nel documento
Verifica sempre la presenza del campo prima dell'utilizzo
data_cessazione è null per contratti attivi
data_cessazione è null anche quando la cessazione riportata sul documento è già avvenuta, non è esplicitamente etichettata, è incompleta o coincide con un'altra data del cedolino: in tutti questi casi tempo_determinato vale false
tempo_determinato è un booleano sempre presente, mai null
Per busta_paga_statale: p_iva e tutti i campi atc_additional_info sono sempre null
codice_fiscale_datore_persona_fisica, nome_datore_persona_fisica e tipo_datore_lavoro sono assenti nella risposta se non applicabili
extraction_errors è null quando l'estrazione è completa; è un array di stringhe quando status_basic_info vale "partial"

Verifica dell'Esito¶

Un webhook con "status": "DONE" indica che il documento è stato elaborato, non che tutti i campi sono stati estratti
Controllare sempre extracted_data.basic_info.status_basic_info: se vale "partial", uno dei tre blocchi di estrazione è fallito e i suoi campi sono assenti o null
extraction_errors indica quale blocco è fallito, così da sapere quali campi non sono affidabili

Precisione Numerica¶

Gli importi sono in formato decimale (es. 1234.56)
Le ore possono avere decimali (es. 16,50)
I valori unitari hanno alta precisione (es. 10.18838)

Classificazioni Automatiche¶

Il sistema classifica automaticamente ogni voce
La classificazione aiuta nell'aggregazione dei dati
Voci non riconosciute sono marcate come sconosciuto

Validazioni Automatiche¶

Codice Fiscale: validato e usato per estrarre data nascita, sesso, luogo nascita
P.IVA (solo privato): validata con algoritmo check digit e verificata online
TFR: validato per evitare confusione tra quota mensile e fondo accumulato
CF Datore Persona Fisica: estratto con fallback dedicato solo quando mancano P.IVA e CF aziendale; il candidato viene validato con lo stesso algoritmo del CF dipendente e scartato se coincide con esso
Data di cessazione: validata con una regola deterministica che accetta solo una data completa, esplicitamente etichettata, futura e diversa dalle altre date del cedolino; da questa validazione deriva il flag tempo_determinato

Busta Paga - Dati Estratti Tipi di Documento Supportati Esempio Response - Busta Paga Privata Esempio Response - Busta Paga Statale (PA/NOIPA)Informazioni di Base ( )Dati Dipendente Dati Azienda (Privato)Datore di Lavoro Persona Fisica (Privato — caso speciale)Dati Ente Pubblico (Statale)Dati Contrattuali Periodo e Importi Verifica Partita IVA (solo Privato)Status Elaborazione Competenze ( )Retribuzione Base Straordinari Mensilità Aggiuntive Bonus e Rimborsi Anticipi Agevolazioni Speciali Trattenute ( )Ritenute Fiscali Addizionali Contributi Previdenziali Prestiti e Cessioni Pignoramenti e Recuperi Malattia e Servizi Voci Varie Classificazioni Voci Competenze (Earnings)Trattenute (Deductions)Differenze tra Privato e Statale Campi Presenti Solo nel Privato Campi Presenti Solo nello Statale Campi Comuni Note Implementative Gestione Campi Null Verifica dell'Esito Precisione Numerica Classificazioni Automatiche Validazioni Automatiche