UBL XML to FatturaPA Mapping Reference
This document describes how UBL XML (Universal Business Language) invoice fields are mapped to the Italian FatturaPA XML invoice format.
DatiTrasmissione
| FatturaPA Field | UBL XML | Req. | Default | Condition | Description |
|---|---|---|---|---|---|
| fatturaElettronicaHeader.datiTrasmissione.formatoTrasmissione | No | FPR12 | private recipient transmission format | ||
| fatturaElettronicaHeader.datiTrasmissione.codiceDestinatario | AccountingCustomerParty > Party > EndpointID[@schemeID="0205" and string-length(normalize-space(.))=7 and translate(normalize-space(.), "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789", "")=""] XPathcac:AccountingCustomerParty/cac:Party/cbc:EndpointID[@schemeID="0205" and string-length(normalize-space(.))=7 and translate(normalize-space(.), "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789", "")=""] | No | EndpointID scheme 0205 is a 7 character private SDI code | valid seven-character SDI code from EndpointID scheme 0205. Converted to uppercase |
CedentePrestatore
| FatturaPA Field | UBL XML | Req. | Default | Condition | Description |
|---|---|---|---|---|---|
| fatturaElettronicaHeader.cedentePrestatore.datiAnagrafici.idFiscaleIva.idPaese | AccountingSupplierParty > Party > PartyTaxScheme[TaxScheme > ID="VAT"] > CompanyID XPathcac:AccountingSupplierParty/cac:Party/cac:PartyTaxScheme[cac:TaxScheme/cbc:ID="VAT"]/cbc:CompanyID | Yes | supplier VAT country prefix. Extracted via regex /^([A-Z]{2}).+$/ | ||
| fatturaElettronicaHeader.cedentePrestatore.datiAnagrafici.idFiscaleIva.idCodice | AccountingSupplierParty > Party > PartyTaxScheme[TaxScheme > ID="VAT"] > CompanyID XPathcac:AccountingSupplierParty/cac:Party/cac:PartyTaxScheme[cac:TaxScheme/cbc:ID="VAT"]/cbc:CompanyID | Yes | supplier VAT identifier without country prefix. Extracted via regex /^[A-Z]{2}(.+)$/ | ||
| fatturaElettronicaHeader.cedentePrestatore.datiAnagrafici.anagrafica.denominazione | AccountingSupplierParty > Party > PartyLegalEntity > RegistrationName XPathcac:AccountingSupplierParty/cac:Party/cac:PartyLegalEntity/cbc:RegistrationName | No | seller declares a legal registration name | supplier legal registration name | |
| fatturaElettronicaHeader.cedentePrestatore.datiAnagrafici.regimeFiscale | No | business-registry | business registry provides RegimeFiscale | tenant tax regime from the business registry. Computed: businessRegistry.taxRegime | |
| fatturaElettronicaHeader.cedentePrestatore.sede.indirizzo | AccountingSupplierParty > Party > PostalAddress > StreetName XPathcac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:StreetName | Yes | supplier street | ||
| fatturaElettronicaHeader.cedentePrestatore.sede.cAP | AccountingSupplierParty > Party > PostalAddress > PostalZone XPathcac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:PostalZone | Yes | supplier postal code | ||
| fatturaElettronicaHeader.cedentePrestatore.sede.comune | AccountingSupplierParty > Party > PostalAddress > CityName XPathcac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:CityName | Yes | supplier municipality | ||
| fatturaElettronicaHeader.cedentePrestatore.sede.provincia | AccountingSupplierParty > Party > PostalAddress > CountrySubentity[string-length(normalize-space(.))=2 and translate(normalize-space(.), "ABCDEFGHIJKLMNOPQRSTUVWXYZ", "")=""] XPathcac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:CountrySubentity[string-length(normalize-space(.))=2 and translate(normalize-space(.), "ABCDEFGHIJKLMNOPQRSTUVWXYZ", "")=""] | No | supplier province when explicitly present | ||
| fatturaElettronicaHeader.cedentePrestatore.sede.nazione | AccountingSupplierParty > Party > PostalAddress > Country > IdentificationCode XPathcac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cac:Country/cbc:IdentificationCode | Yes | supplier country |
CessionarioCommittente
| FatturaPA Field | UBL XML | Req. | Default | Condition | Description |
|---|---|---|---|---|---|
| fatturaElettronicaHeader.cessionarioCommittente.datiAnagrafici.idFiscaleIva.idPaese | AccountingCustomerParty > Party > PartyTaxScheme[TaxScheme > ID="VAT"] > CompanyID XPathcac:AccountingCustomerParty/cac:Party/cac:PartyTaxScheme[cac:TaxScheme/cbc:ID="VAT"]/cbc:CompanyID | No | buyer has an explicit VAT identifier | buyer VAT country prefix. Extracted via regex /^([A-Z]{2}).+$/ | |
| fatturaElettronicaHeader.cessionarioCommittente.datiAnagrafici.idFiscaleIva.idCodice | AccountingCustomerParty > Party > PartyTaxScheme[TaxScheme > ID="VAT"] > CompanyID XPathcac:AccountingCustomerParty/cac:Party/cac:PartyTaxScheme[cac:TaxScheme/cbc:ID="VAT"]/cbc:CompanyID | Yes | buyer has an explicit VAT identifier | buyer VAT identifier. Extracted via regex /^[A-Z]{2}(.+)$/ | |
| fatturaElettronicaHeader.cessionarioCommittente.datiAnagrafici.codiceFiscale | AccountingCustomerParty > Party > PartyIdentification[ID > @schemeID="IT:CF" or ID > @schemeID="CF"] > ID XPathcac:AccountingCustomerParty/cac:Party/cac:PartyIdentification[cbc:ID/@schemeID="IT:CF" or cbc:ID/@schemeID="CF"]/cbc:ID | No | buyer has an explicit Italian fiscal code | explicit buyer fiscal code | |
| fatturaElettronicaHeader.cessionarioCommittente.datiAnagrafici.anagrafica.denominazione | AccountingCustomerParty > Party > PartyLegalEntity > RegistrationName XPathcac:AccountingCustomerParty/cac:Party/cac:PartyLegalEntity/cbc:RegistrationName | No | buyer declares a legal registration name | buyer legal registration name | |
| fatturaElettronicaHeader.cessionarioCommittente.sede.indirizzo | AccountingCustomerParty > Party > PostalAddress > StreetName XPathcac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cbc:StreetName | Yes | buyer street | ||
| fatturaElettronicaHeader.cessionarioCommittente.sede.cAP | AccountingCustomerParty > Party > PostalAddress > PostalZone[string-length(normalize-space(.))=5 and translate(normalize-space(.), "0123456789", "")=""] XPathcac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cbc:PostalZone[string-length(normalize-space(.))=5 and translate(normalize-space(.), "0123456789", "")=""] | Yes | buyer country is Italy | valid five digit domestic postal code | |
| fatturaElettronicaHeader.cessionarioCommittente.sede.comune | AccountingCustomerParty > Party > PostalAddress > CityName XPathcac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cbc:CityName | Yes | buyer municipality | ||
| fatturaElettronicaHeader.cessionarioCommittente.sede.provincia | AccountingCustomerParty > Party > PostalAddress > CountrySubentity[string-length(normalize-space(.))=2 and translate(normalize-space(.), "ABCDEFGHIJKLMNOPQRSTUVWXYZ", "")=""] XPathcac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cbc:CountrySubentity[string-length(normalize-space(.))=2 and translate(normalize-space(.), "ABCDEFGHIJKLMNOPQRSTUVWXYZ", "")=""] | No | buyer province when explicitly present | ||
| fatturaElettronicaHeader.cessionarioCommittente.sede.nazione | AccountingCustomerParty > Party > PostalAddress > Country > IdentificationCode XPathcac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cac:Country/cbc:IdentificationCode | Yes | buyer country |
DatiGeneraliDocumento
| FatturaPA Field | UBL XML | Req. | Default | Condition | Description |
|---|---|---|---|---|---|
| fatturaElettronicaBody[0].datiGenerali.datiGeneraliDocumento.tipoDocumento | cbc:InvoiceTypeCode | Yes | supported UBL invoice type. Map: 380 → TD01STRICT | ||
| fatturaElettronicaBody[0].datiGenerali.datiGeneraliDocumento.divisa | cbc:DocumentCurrencyCode | Yes | invoice currency | ||
| fatturaElettronicaBody[0].datiGenerali.datiGeneraliDocumento.data | cbc:IssueDate | Yes | issue date. Formatted as date (Y-m-d) | ||
| fatturaElettronicaBody[0].datiGenerali.datiGeneraliDocumento.numero | cbc:ID | Yes | invoice identifier |
DatiOrdineAcquisto
| FatturaPA Field | UBL XML | Req. | Default | Condition | Description |
|---|---|---|---|---|---|
| fatturaElettronicaBody[0].datiGenerali.datiOrdineAcquisto[0].idDocumento | OrderReference > ID XPathcac:OrderReference/cbc:ID | No | purchase order identifier |
DatiTrasporto
| FatturaPA Field | UBL XML | Req. | Default | Condition | Description |
|---|---|---|---|---|---|
| fatturaElettronicaBody[0].datiGenerali.datiTrasporto.indirizzoResa.indirizzo | Delivery > DeliveryLocation > Address > StreetName XPathcac:Delivery/cac:DeliveryLocation/cac:Address/cbc:StreetName | Yes | invoice contains a delivery address node | delivery street | |
| fatturaElettronicaBody[0].datiGenerali.datiTrasporto.indirizzoResa.cAP | Delivery > DeliveryLocation > Address > PostalZone XPathcac:Delivery/cac:DeliveryLocation/cac:Address/cbc:PostalZone | Yes | invoice contains a delivery address node delivery address is in Italy | domestic delivery postal code | |
| fatturaElettronicaBody[0].datiGenerali.datiTrasporto.indirizzoResa.comune | Delivery > DeliveryLocation > Address > CityName XPathcac:Delivery/cac:DeliveryLocation/cac:Address/cbc:CityName | Yes | invoice contains a delivery address node | delivery municipality | |
| fatturaElettronicaBody[0].datiGenerali.datiTrasporto.indirizzoResa.provincia | Delivery > DeliveryLocation > Address > CountrySubentity[string-length(normalize-space(.))=2 and translate(normalize-space(.), "ABCDEFGHIJKLMNOPQRSTUVWXYZ", "")=""] XPathcac:Delivery/cac:DeliveryLocation/cac:Address/cbc:CountrySubentity[string-length(normalize-space(.))=2 and translate(normalize-space(.), "ABCDEFGHIJKLMNOPQRSTUVWXYZ", "")=""] | No | invoice contains a delivery address node | delivery province | |
| fatturaElettronicaBody[0].datiGenerali.datiTrasporto.indirizzoResa.nazione | Delivery > DeliveryLocation > Address > Country > IdentificationCode XPathcac:Delivery/cac:DeliveryLocation/cac:Address/cac:Country/cbc:IdentificationCode | Yes | invoice contains a delivery address node | delivery country |
DettaglioLinee
| FatturaPA Field | UBL XML | Req. | Default | Condition | Description |
|---|---|---|---|---|---|
| fatturaElettronicaBody[0].datiBeniServizi.dettaglioLinee | cac:InvoiceLine | Yes | UBL invoice lines. Grouped by cbc:ID |
fatturaElettronicaBody[0].datiBeniServizi.dettaglioLinee
| FatturaPA Field | UBL XML | Req. | Default | Condition | Description |
|---|---|---|---|---|---|
| numeroLinea | cbc:ID | Yes | source line identifier | ||
| descrizione | (Item > Description | Item > Name)[1] XPath(cac:Item/cbc:Description | cac:Item/cbc:Name)[1] | Yes | source description, falling back to item name | ||
| unitaMisura | InvoicedQuantity > @unitCode XPathcbc:InvoicedQuantity/@unitCode | No | UN/ECE unit code | ||
| quantita | cbc:InvoicedQuantity | Yes | invoiced quantity. Transform: numberFormat | ||
| prezzoUnitario | Price > PriceAmount XPathcac:Price/cbc:PriceAmount | Yes | the UBL price base is strictly positive | price amount divided by BaseQuantity. Computed: floatval(source) / floatval(xpath(row, 'cac:Price/cbc:BaseQuantity')). Transform: numberFormat | |
| prezzoTotale | cbc:LineExtensionAmount | Yes | source line net amount. Transform: numberFormat | ||
| aliquotaIVA | Item > ClassifiedTaxCategory > Percent XPathcac:Item/cac:ClassifiedTaxCategory/cbc:Percent | Yes | source line VAT percentage. Transform: numberFormat | ||
| natura | Item > AdditionalItemProperty[Name="Natura"] > Value[contains("|N1|N2.1|N2.2|N3.1|N3.2|N3.3|N3.4|N3.5|N3.6|N4|N5|N6.1|N6.2|N6.3|N6.4|N6.5|N6.6|N6.7|N6.8|N6.9|N7|", concat("|", normalize-space(.), "|"))] XPathcac:Item/cac:AdditionalItemProperty[cbc:Name="Natura"]/cbc:Value[contains("|N1|N2.1|N2.2|N3.1|N3.2|N3.3|N3.4|N3.5|N3.6|N4|N5|N6.1|N6.2|N6.3|N6.4|N6.5|N6.6|N6.7|N6.8|N6.9|N7|", concat("|", normalize-space(.), "|"))] | No | line VAT rate is zero line contains an explicit FatturaPA Natura | explicit FatturaPA Natura |
DatiRiepilogo
| FatturaPA Field | UBL XML | Req. | Default | Condition | Description |
|---|---|---|---|---|---|
| fatturaElettronicaBody[0].datiBeniServizi.datiRiepilogo | No | mapped-lines | invoice contains at least one source line | summaries calculated from mapped lines. Computed: getValue(output, 'fatturaElettronicaBody[0].datiBeniServizi.dettaglioLinee'). Transform: calculateInvoiceItDatiRiepilogo | |
| fatturaElettronicaBody[0].datiGenerali.datiGeneraliDocumento.importoTotaleDocumento | No | mapped-summaries | invoice contains at least one source line | total calculated from VAT summaries. Computed: getValue(output, 'fatturaElettronicaBody[0].datiBeniServizi.datiRiepilogo'). Transform: calculateInvoiceItTotalAmount |
DatiPagamento
| FatturaPA Field | UBL XML | Req. | Default | Condition | Description |
|---|---|---|---|---|---|
| fatturaElettronicaBody[0].datiPagamento[0].condizioniPagamento | PaymentTerms > Note XPathcac:PaymentTerms/cbc:Note | No | payment terms explicitly use TP01, TP02 or TP03 | explicit FatturaPA payment condition. Map: TP01 → TP01TP02 → TP02TP03 → TP03STRICT | |
| fatturaElettronicaBody[0].datiPagamento[0].dettaglioPagamento[0].modalitaPagamento | PaymentMeans > PaymentMeansCode XPathcac:PaymentMeans/cbc:PaymentMeansCode | Yes | payment terms explicitly use TP01, TP02 or TP03 | deterministic UNCL4461 mapping. Map: 10 → MP0130 → MP0542 → MP0549 → MP1658 → MP0559 → MP19STRICT | |
| fatturaElettronicaBody[0].datiPagamento[0].dettaglioPagamento[0].dataScadenzaPagamento | cbc:DueDate | No | payment terms explicitly use TP01, TP02 or TP03 | due date. Formatted as date (Y-m-d) | |
| fatturaElettronicaBody[0].datiPagamento[0].dettaglioPagamento[0].importoPagamento | LegalMonetaryTotal > PayableAmount XPathcac:LegalMonetaryTotal/cbc:PayableAmount | Yes | payment terms explicitly use TP01, TP02 or TP03 | payable amount. Transform: numberFormat | |
| fatturaElettronicaBody[0].datiPagamento[0].dettaglioPagamento[0].iban | PaymentMeans > PayeeFinancialAccount > ID XPathcac:PaymentMeans/cac:PayeeFinancialAccount/cbc:ID | No | payment terms explicitly use TP01, TP02 or TP03 | payee account identifier | |
| fatturaElettronicaBody[0].datiPagamento[0].dettaglioPagamento[0].codicePagamento | PaymentMeans > PaymentID XPathcac:PaymentMeans/cbc:PaymentID | No | payment terms explicitly use TP01, TP02 or TP03 | payment reference |
Allegati
| FatturaPA Field | UBL XML | Req. | Default | Condition | Description |
|---|---|---|---|---|---|
| fatturaElettronicaBody[0].allegati | AdditionalDocumentReference[Attachment > EmbeddedDocumentBinaryObject] XPathcac:AdditionalDocumentReference[cac:Attachment/cbc:EmbeddedDocumentBinaryObject] | No | embedded UBL document references. Grouped by cbc:ID |
fatturaElettronicaBody[0].allegati
| FatturaPA Field | UBL XML | Req. | Default | Condition | Description |
|---|---|---|---|---|---|
| nomeAttachment | Attachment > EmbeddedDocumentBinaryObject > @filename XPathcac:Attachment/cbc:EmbeddedDocumentBinaryObject/@filename | No | embedded filename | ||
| formatoAttachment | Attachment > EmbeddedDocumentBinaryObject > @filename XPathcac:Attachment/cbc:EmbeddedDocumentBinaryObject/@filename | No | uppercase filename extension. Extracted via regex /\.([^.]+)$/. Converted to uppercase | ||
| attachment | Attachment > EmbeddedDocumentBinaryObject XPathcac:Attachment/cbc:EmbeddedDocumentBinaryObject | Yes | base64 document payload. Transform: base64Decode |