Struttura dati

In questa sezione è presente la struttura dati del modulo Fatturazione. Sono presenti le entità, le relazioni e i tipi di dati utilizzati.

---

🗂️ Diagrammi ER

Fatture

Il modello inv_invoices rappresenta la fattura, ed è l'oggetto principale del modulo.

A ogni fattura è associato il modello inv_sdi_driver_identifiers, che contiene le specifiche per identificare la fattura sul Sistema di Interscambio (SDI), il suo stato e i metadati del driver utilizzato per comunicare con il SDI.

---

🧬 DTOs

Fatture

InvEntityDto

DTO che rappresenta una fattura.

Field

PHP Type

Note

id

int

number

string

amount

int

date

string

fattura_elettronica

InvFatturaElettronicaDto

nullable

---

Fattura elettronica

Questi DTO sono utilizzati per la generazione della fattura elettronica. La struttura di tutti i DTO collegati è conforme al formato XML richiesto per l'invio al SDI.

InvFatturaElettronicaDto

Rappresentazione DTO di una fattura elettronica conforme al formato XML richiesto per l'invio al SDI.

Field

PHP Type

Note

fattura_elettronica_header

InvFatturaElettronicaHeaderDto

fattura_elettronica_body

InvFatturaElettronicaBodyDto

InvFatturaElettronicaHeaderDto

Header della fattura elettronica. Contiene informazioni generali sulla fattura, come i dati della trasmissione, il fornitore il cliente ed altri attori.

Field

PHP Type

Note

InvFatturaElettronicaBodyDto

Body della fattura elettronica. Contiene i dettagli della fattura, come i prodotti, i servizi, i prezzi, etc.

Field

PHP Type

Note

dati_generali

InvDatiGeneraliDto

dati_beni_servizi

InvDatiBeniServiziDto

dati_veicoli

InvDatiVeicoliDto

nullable

dati_pagamento

Collection<InvDatiPagamentoDto>

nullable

allegati

Collection<InvAllegatiDto>

nullable

InvDatiGeneraliDto

DTO che rappresenta i dati identificativi della fattura.

Field

PHP Type

Note

dati_generali_documento

InvDatiGeneraliDocumentoDto

dati_ordine_acquisto

Collection<InvDatiOrdineAcquistoDto>

nullable

dati_contratto

Collection<InvDatiContrattoDto>

nullable

dati_convenzione

Collection<InvDatiConvenzioneDto>

nullable

dati_ricezione

Collection<InvDatiRicezioneDto>

nullable

dati_fatture_collegate

Collection<InvDatiFattureCollegateDto>

nullable

dati_sal

Collection<InvDatiSALDto>

nullable

dati_ddt

Collection<InvDatiDDTDto>

nullable

dati_trasporto

InvDatiTrasportoDto

nullable

dati_fattura_principale

InvFatturaPrincipaleDto

nullable

InvDatiGeneraliDocumentoDto

DTO che rappresenta i dati generali del documento.

Field

PHP Type

Note

tipo_documento

string

Tipologia di documento (4 caratteri)

divisa

string

Divisa utilizzata nel documento (3 caratteri)

data

string

Data del documento (formato YYYY-MM-DD)

numero

string

Numero del documento (min 1, max 20 caratteri)

dati_ritenuta

InvDatiRitenutaDto

nullable - Dati della ritenuta

dati_bollo

InvDatiBolloDto

nullable - Dati del bollo

dati_cassa_previdenziale

Collection<InvDatiCassaPrevidenzialeDto>

nullable - Dati della cassa previdenziale

sconto_maggiorazione

Collection<InvScontoMaggiorazioneDto>

nullable - Sconti o maggiorazioni

importo_totale_documento

string

nullable - Importo totale del documento (formato decimale con 2 cifre decimali, min 4 max 15 caratteri)

arrotondamento

string

nullable - Arrotondamento (formato decimale con 2 cifre decimali, min 4 max 15 caratteri)

causale

Collection<string>

nullable - Array di causali (max 200 caratteri per causale)

art73

string

nullable - Articolo 73 (2 caratteri - semplicemente 'SI' se applicabile)

InvDatiRitenutaDto

DTO che rappresenta i dati della ritenuta applicata.

Field

PHP Type

Note

tipo_ritenuta

string

Tipologia di ritenuta (4 caratteri)

importo_ritenuta

string

Importo della ritenuta (formato decimale con 2 cifre decimali, min 4 max 15 caratteri)

aliquota_ritenuta

string

Aliquota della ritenuta (formato da 0.00 a 100.00, min 4 max 6 caratteri)

causale_pagamento

string

Causale del pagamento (min 1, max 2 caratteri)

InvDatiBolloDto

DTO che rappresenta i dati del bollo applicato al documento.

Field

PHP Type

Note

bollo_virtuale

string

Indicazione se il bollo è virtuale (2 caratteri)

importo_bollo

string

Importo del bollo (formato decimale con 2 cifre decimali, min 4 max 15 caratteri)

InvDatiCassaPrevidenzialeDto

DTO che rappresenta i dati della cassa previdenziale.

Field

PHP Type

Note

tipo_cassa

string

Tipologia di cassa previdenziale (4 caratteri)

al_cassa

string

Aliquota della cassa (formato da 0.00 a 100.00, min 4 max 6 caratteri)

importo_contributo_cassa

string

Importo del contributo cassa (formato decimale con 2 cifre decimali, min 4 max 15 caratteri)

imponibile_cassa

string

nullable - Imponibile della cassa (formato decimale con 2 cifre decimali, min 4 max 15 caratteri)

aliquota_iva

string

nullable - Aliquota IVA applicata alla cassa (formato da 0.00 a 100.00, min 4 max 6 caratteri)

ritenuta

string

nullable - Indicazione se soggetta a ritenuta (2 caratteri)

natura

string

nullable - Natura IVA della cassa (min 2, max 4 caratteri)

riferimento_amministrazione

string

nullable - Riferimento amministrazione (min 1, max 20 caratteri)

InvDatiOrdineAcquistoDto

DTO che rappresenta i dati dell'ordine di acquisto.

Field

PHP Type

Note

riferimento_numero_linea

Collection<int>

nullable - Riferimenti ai numeri linea del documento (max 4 cifre per elemento)

id_documento

string

Identificativo del documento (min 1, max 20 caratteri)

data

string

nullable - Data del documento (formato YYYY-MM-DD)

num_item

string

nullable - Numero item (min 1, max 20 caratteri)

codice_commessa_convenzione

string

nullable - Codice commessa o convenzione (min 1, max 100 caratteri)

codice_cup

string

nullable - Codice CUP (max 15 caratteri)

codice_cig

string

nullable - Codice CIG (max 15 caratteri)

InvDatiContrattoDto

DTO che rappresenta i dati del contratto.

Field

PHP Type

Note

riferimento_numero_linea

Collection<int>

nullable - Riferimenti ai numeri linea del documento (max 4 cifre per elemento)

id_documento

string

Identificativo del documento (min 1, max 20 caratteri)

data

string

nullable - Data del documento (formato YYYY-MM-DD)

num_item

string

nullable - Numero item (min 1, max 20 caratteri)

codice_commessa_convenzione

string

nullable - Codice commessa o convenzione (min 1, max 100 caratteri)

codice_cup

string

nullable - Codice CUP (min 1, max 15 caratteri)

codice_cig

string

nullable - Codice CIG (min 1, max 15 caratteri)

InvDatiConvenzioneDto

DTO che rappresenta i dati della convenzione.

Field

PHP Type

Note

riferimento_numero_linea

Collection<int>

nullable - Riferimenti ai numeri linea del documento (max 4 cifre per elemento)

id_documento

string

Identificativo del documento (min 1, max 20 caratteri)

data

string

nullable - Data del documento (formato YYYY-MM-DD)

num_item

string

nullable - Numero item (min 1, max 20 caratteri)

codice_commessa_convenzione

string

nullable - Codice commessa o convenzione (min 1, max 100 caratteri)

codice_cup

string

nullable - Codice CUP (min 1, max 15 caratteri)

codice_cig

string

nullable - Codice CIG (min 1, max 15 caratteri)

InvDatiRicezioneDto

DTO che rappresenta i dati della ricezione.

Field

PHP Type

Note

riferimento_numero_linea

Collection<int>

nullable - Riferimenti ai numeri linea del documento (max 4 cifre per elemento)

id_documento

string

Identificativo del documento (min 1, max 20 caratteri)

data

string

nullable - Data del documento (formato YYYY-MM-DD)

num_item

string

nullable - Numero item (min 1, max 20 caratteri)

codice_commessa_convenzione

string

nullable - Codice commessa o convenzione (min 1, max 100 caratteri)

codice_cup

string

nullable - Codice CUP (min 1, max 15 caratteri)

codice_cig

string

nullable - Codice CIG (min 1, max 15 caratteri)

InvDatiFattureCollegateDto

DTO che rappresenta i dati delle fatture collegate.

Field

PHP Type

Note

riferimento_numero_linea

Collection<int>

nullable - Riferimenti ai numeri linea del documento (max 4 cifre per elemento)

id_documento

string

Identificativo del documento (min 1, max 20 caratteri)

data

string

nullable - Data del documento (formato YYYY-MM-DD)

num_item

string

nullable - Numero item (min 1, max 20 caratteri)

codice_commessa_convenzione

string

nullable - Codice commessa o convenzione (min 1, max 100 caratteri)

codice_cup

string

nullable - Codice CUP (min 1, max 15 caratteri)

codice_cig

string

nullable - Codice CIG (min 1, max 15 caratteri)

InvDatiSALDto

DTO che rappresenta i dati della SAL (Stato Avanzamento Lavori).

Field

PHP Type

Note

riferimento_fase

int

Riferimento alla fase del SAL (max 3 cifre)

InvDatiDDTDto

DTO che rappresenta i dati del Documento di Trasporto (DDT).

Field

PHP Type

Note

numero_ddt

string

Numero del documento di trasporto (min 1, max 20 caratteri)

data_ddt

string

Data del documento di trasporto (formato YYYY-MM-DD)

riferimento_numero_linea

Collection<int>

nullable - Riferimenti ai numeri linea del documento (max 4 cifre per elemento)

InvDatiTrasportoDto

DTO che rappresenta i dati del trasporto della fattura.

Field

PHP Type

Note

dati_anagrafici_vettore

InvDatiAnagraficiVettoreDto

nullable - Dati anagrafici del vettore

mezzo_trasporto

string

nullable - Descrizione del mezzo di trasporto (min 1, max 80 caratteri)

causale_trasporto

string

nullable - Causale del trasporto (min 1, max 100 caratteri)

numero_colli

int

nullable - Numero dei colli trasportati (max 4 cifre)

descrizione

string

nullable - Descrizione della merce trasportata (min 1, max 100 caratteri)

unita_misura_peso

string

nullable - Unità di misura del peso (min 1, max 10 caratteri)

peso_lordo

string

nullable - Peso lordo (formato da 0.00 a 999.99, min 4 max 7 caratteri)

peso_netto

string

nullable - Peso netto (formato da 0.00 a 999.99, min 4 max 7 caratteri)

data_ora_ritiro

string

nullable - Data e ora di ritiro (formato YYYY-MM-DDTHH:mm:ss)

data_inizio_trasporto

string

nullable - Data di inizio trasporto (formato YYYY-MM-DD)

tipo_resa

string

nullable - Tipo di resa (3 caratteri)

indirizzo_resa

InvIndirizzoResaDto

nullable - Indirizzo di resa

data_ora_consegna

string

nullable - Data e ora di consegna (formato YYYY-MM-DDTHH:mm:ss)

InvDatiAnagraficiVettoreDto

DTO che rappresenta i dati anagrafici del vettore per il trasporto.

Field

PHP Type

Note

id_fiscale_iva

InvIdFiscaleIVADto

Identificativo fiscale IVA del vettore

codice_fiscale

string

nullable - Codice fiscale del vettore (min 11, max 16 caratteri)

anagrafica

InvAnagraficaDto

Dati anagrafici del vettore

numero_licenza_guida

string

nullable - Numero della licenza di guida (min 1, max 20 caratteri)

InvIdFiscaleIVADto

DTO che rappresenta l'identificativo fiscale IVA.

Field

PHP Type

Note

id_paese

string

Codice paese (2 caratteri)

id_codice

string

Codice identificativo fiscale (min 1, max 28 caratteri)

InvAnagraficaDto

DTO che rappresenta i dati anagrafici di una persona fisica o giuridica.

Field

PHP Type

Note

denominazione

string

nullable - Denominazione sociale (min 1, max 80 caratteri)

nome

string

nullable - Nome della persona fisica (min 1, max 60 caratteri)

cognome

string

nullable - Cognome della persona fisica (min 1, max 60 caratteri)

cod_eori

string

nullable - Codice EORI (Economic Operators Registration and Identification) (min 1, max 17 caratteri)

InvIndirizzoResaDto

DTO che rappresenta l'indirizzo di resa per il trasporto.

Field

PHP Type

Note

indirizzo

string

Indirizzo di resa (min 1, max 60 caratteri)

numero_civico

string

nullable - Numero civico (min 1, max 8 caratteri)

cap

string

Codice di avviamento postale (CAP) (min 5, max 5 caratteri)

comune

string

Comune (min 1, max 60 caratteri)

provincia

string

Provincia (min 2, max 2 caratteri)

nazione

string

Nazione (min 2, max 2 caratteri)

InvFatturaPrincipaleDto

DTO che rappresenta i dati della fattura principale in caso di nota di credito o debito.

Field

PHP Type

Note

numero_fattura_principale

string

Numero della fattura principale di riferimento (min 1, max 20 caratteri)

data_fattura_principale

string

Data della fattura principale di riferimento (formato YYYY-MM-DD)

InvDatiBeniServiziDto

DTO che rappresenta i dati dei beni e servizi della fattura.

Field

PHP Type

Note

dettaglio_linee

Collection<InvDettaglioLineeDto>

dati_riepilogo

Collection<InvDatiRiepilogoDto>

InvDettaglioLineeDto

DTO che rappresenta una linea di dettaglio della fattura.

Field

PHP Type

Note

numero_linea

int

Numero di linea della fattura (max 4 cifre)

tipo_cessione_prestazione

string

nullable - codice da utilizzare in caso di sconto, etc (max 2 cifre)

codice_articolo

InvCodiceArticoloDto

nullable - tipo di codifica e codice dell'articolo

descrizione

string

descrizione del bene o servizio (max 1000 caratteri)

quantita

string

nullable - quantità del bene o servizio - formato decimale con minimo 2 e massimo 8 cifre decimali, minimo 4 massimo 21 caratteri

unita_misura

string

nullable - unità di misura del bene - min 1, max 10 caratteri

data_inizio_periodo

string

nullable - data di inizio periodo (formato YYYY-MM-DD)

data_fine_periodo

string

nullable - data di fine periodo (formato YYYY-MM-DD)

prezzo_unitario

string

prezzo unitario del bene o servizio - formato decimale con minimo 2 e massimo 8 cifre decimali, minimo 4 massimo 21 caratteri

sconto_maggiorazione

InvScontoMaggiorazioneDto

nullable - sconto o maggiorazione da applicare sul prezzo totale

prezzo_totale

string

prezzo totale del bene o servizio - formato decimale con minimo 2 e massimo 8 cifre decimali, minimo 4 massimo 21 caratteri

aliquota_iva

string

Aliquota IVA da applicare - due decimali obbligatori, max 6 cifre (da 0.00 a 100.00)

ritenuta

string

nullable - va valorizzata con 'SI' solo se soggetta a ritenuta

natura

string

nullable - codice natura iva, da 2 fino a 4 caratteri

riferimento_amministrazione

string

nullable - codice di riferimento dell'amministrazione, fino a 20 caratteri

altri_dati_gestionali

InvAltriDatiGestionaliDto

nullable - altri dati utili per identificare il bene o servizio

InvCodiceArticoloDto

DTO che rappresenta un codice articolo.

Field

PHP Type

Note

codice_tipo

string

tipo di codifica del codice articolo (max 35 caratteri)

codice_valore

string

valore del codice articolo (max 35 caratteri)

InvScontoMaggiorazioneDto

DTO che rappresenta uno sconto o una maggiorazione.

Field

PHP Type

Note

tipo

string

tipo di sconto o maggiorazione (max 2 caratteri)

percentuale

string

percentuale di sconto - due decimali obbligatori, max 6 cifre (da 0.00 a 100.00)

importo

string

importo di sconto o maggiorazione - formato decimale con minimo 2 e massimo 8 cifre decimali, minimo 4 massimo 21 caratteri

InvAltriDatiGestionaliDto

DTO che rappresenta altri dati gestionali della fattura.

Field

PHP Type

Note

tipo_dato

string

max 2 caratteri

riferimento_testo

string

nullable - max 60 caratteri

riferimento_numero

string

nullable - formato decimale con minimo 2 e massimo 8 cifre decimali, minimo 4 massimo 21 caratteri

riferimento_data

string

nullable - formato YYYY-MM-DD

InvDatiRiepilogoDto

DTO che rappresenta un dato riepilogativo della fattura.

Field

PHP Type

Note

aliquota_iva

string

min(4), max(6), numeric, regex:/^d{1,2}.d{2}$/

natura

string

nullable - max 4 caratteri

spese_accessorie

string

nullable - formato decimale con 2 cifre decimali, minimo 4 massimo 15 caratteri

arrotondamento

string

nullable - formato decimale con minimo 2 e massimo 8 cifre decimali, minimo 4 massimo 21 caratteri

imponibile_importo

string

nullable - formato decimale con 2 cifre decimali, minimo 4 massimo 15 caratteri

imposta

string

nullable - formato decimale con 2 cifre decimali, minimo 4 massimo 15 caratteri

esigibilita_iva

string

nullable, 1 carattere (solo D, I o S)

riferimento_normativo

string

nullable, max 100 caratteri

InvDatiVeicoliDto

DTO che rappresenta i dati dei veicoli della fattura (art. 38, comma 4, dlgs 331/93).

Field

PHP Type

Note

data

string

Data di riferimento per i dati del veicolo (formato YYYY-MM-DD)

totale_percorso

string

Totale del percorso effettuato dal veicolo in km (formato numerico con da 2 a 8 cifre decimali, min 4 max 15 caratteri)

InvDatiPagamentoDto

DTO che rappresenta i dati del pagamento della fattura.

Field

PHP Type

Note

condizioni_pagamento

string

Condizioni di pagamento (4 caratteri)

dettaglio_pagamento

Collection<InvDettaglioPagamentoDto>

Dettagli del pagamento

InvDettaglioPagamentoDto

DTO che rappresenta i dettagli di un singolo pagamento della fattura.

Field

PHP Type

Note

beneficiario

string

nullable - Beneficiario del pagamento (min 1, max 200 caratteri)

modalita_pagamento

string

Modalità di pagamento (4 caratteri)

data_riferimento_termini_pagamento

string

nullable - Data di riferimento per i termini di pagamento (formato YYYY-MM-DD)

giorni_termini_pagamento

int

nullable - Giorni per i termini di pagamento (max 3 cifre)

data_scadenza_pagamento

string

nullable - Data di scadenza del pagamento (formato YYYY-MM-DD)

importo_pagamento

string

Importo del pagamento (formato decimale con 2 cifre decimali, min 4 max 15 caratteri)

cod_ufficio_postale

string

nullable - Codice ufficio postale (min 1, max 20 caratteri)

cognome_quietanzante

string

nullable - Cognome del quietanzante (min 1, max 60 caratteri)

nome_quietanzante

string

nullable - Nome del quietanzante (min 1, max 60 caratteri)

cf_quietanzante

string

nullable - Codice fiscale del quietanzante (min 11, max 16 caratteri)

titolo_quietanzante

string

nullable - Titolo del quietanzante (min 2, max 10 caratteri)

istituto_finanziario

string

nullable - Nome dell'istituto finanziario (min 1, max 80 caratteri)

iban

string

nullable - Codice IBAN (min 15, max 34 caratteri)

abi

string

nullable - Codice ABI (5 caratteri)

cab

string

nullable - Codice CAB (5 caratteri)

bic

string

nullable - Codice BIC/SWIFT (min 8, max 11 caratteri)

sconto_pagamento_anticipato

string

nullable - Sconto per pagamento anticipato (formato decimale con 2 cifre decimali, min 4 max 15 caratteri)

data_limite_pagamento_anticipato

string

nullable - Data limite per pagamento anticipato (formato YYYY-MM-DD)

penalita_pagamenti_ritardati

string

nullable - Penalità per pagamenti ritardati (formato decimale con 2 cifre decimali, min 4 max 15 caratteri)

data_decorrenza_penale

string

nullable - Data di decorrenza delle penali (formato YYYY-MM-DD)

codice_pagamento

string

nullable - Codice di pagamento (min 1, max 60 caratteri)

InvAllegatiDto

DTO che rappresenta un allegato alla fattura.

Field

PHP Type

Note

nome_attachment

string

Nome del file allegato (min 1, max 60 caratteri)

algoritmo_compressione

string

nullable - Algoritmo di compressione utilizzato (max 10 caratteri)

formato_attachment

string

nullable - Formato del file allegato (max 10 caratteri)

descrizione_attachment

string

nullable - Descrizione dell'allegato (min 1, max 100 caratteri)

attachment

string

Contenuto del file allegato codificato in base64

---

SDI

Questi DTO sono utilizzati per la comunicazione con il Sistema di Interscambio (SDI).

InvResponseDto

DTO che rappresenta la risposta del SDI, comprensiva di log e di dati che aiutano a identificare la fattura e il driver utilizzato per inviarla.

Field

PHP Type

Note

invoice_id

int

uuid

string

driver

string

status

string

sdi_id

string

log

InvSdiResponseLogDto

InvSdiResponseLogDto

DTO che rappresenta il log di risposta del SDI. Qui viene anche salvata una collezione di errori che potrebbero essere presenti nella risposta del SDI.

Field

PHP Type

Note

type

string

status

string

date

string

message

string

errors

Collection<InvSdiResponseErrorDto>

InvSdiResponseErrorDto

DTO che rappresenta un errore segnalato dal SDI. Il messaggio viene utilizzato nel log di risposta del SDI.

Field

PHP Type

Note

code

string

description

string

hint

string

---

🎛️ Enums

SdiStatusEnum

string

Field

Value

Frontend Value

Note

INV

INV

Inviata

DI

DI

Da inviare

RC

RC

Ricevuta consegna

MC

MC

Mancata consegna

NS

NS

Notifica di scarto

---