Skip to main content

E-Invoice XML customization

While creating an e-invoice you could need to have more control over the XML that is generated through our APIs. On this page, we'll explain how to set up the e-invoice advanced attributes.

📜  The Official XML Structure​

The Official e-invoice XML structure is directly defined by the Italian Public Administration, and can be found here. This structure is subject to changes over time, and that's why we decided to manage some of these fields in a different way.

If you want to know which additional attributes we support you can also read this page. The Fatture in Cloud Web App lets you define these fields through dedicated components, so you can also check it to discover which attributes we support; we'll show you how to do it in the following sections.

🍡  The ei_raw flavours​

If you already are familiar with creating e-invoices from our Web App, you already know that you can set advanced attributes in three different entities:

  • E-invoice body
  • Items list
  • Payments list

While using our Create Issued Document and Modify Issued Document API methods, the fields provided by our model don't let you define all the fields available through our Web App: these advanced fields can instead be managed using the ei_raw params.

Strings everywhere!

Keep in mind that every field in ei_raw is always managed as a String! This means, for example, that even numbers must be inserted in String format (eg. "NumItem": "5")

📃  E-invoice body​

In our Web Interface, you can add your custom XML fields here:

Main body - Add Additional Attributes

In our API, that section corresponds to the data.ei_raw field. Let's try to set up one of these attributes.

For this example, we'll suppose to need to manage the NumItem field (2.1.5.4).

This is the structure declared by the Official Structure:

XML Tag NameXML Tag IDOccurrences
FatturaElettronicaBody2root
DatiGenerali2.1<1,1>
DatiRicezione2.1.5<0,N>
NumItem2.1.5.4<0,1>

This is the final XML that we want to obtain:

<FatturaElettronicaBody>
  <DatiGenerali>
    <DatiRicezione>
      <NumItem>5</NumItem>
    </DatiRicezione>
  </DatiGenerali>
</FatturaElettronicaBody>

The ei_raw field uses JSON instead of XML but uses a similar structure.

While mapping the XML structure to our JSON, you have to keep in mind a few things:

  • The FatturaElettronicaBody tag is the root of our ei_raw field, and we accept only one instance of that in our e-invoices
  • For the root subfields, you need to check if the field is mandatory and its occurrences (check the Obbligatorietà e occorrenze field in the official structure); if the field can have more than one occurrence then it must be represented as a JSON list. For example, DatiRicezione is <0, N>: it means that it isn't mandatory and that it must be represented as a JSON list.

Mapping the XML shown above to our ei_raw JSON format we will obtain the following result:

"ei_raw": {
  "FatturaElettronicaBody": {
    "DatiGenerali": {
      "DatiRicezione": [
        {
          "NumItem": "5"
        }
      ]
    }
  }
}

And here you can see how to set the ei_raw field with our SDKs:

IssuedDocument invoice = new IssuedDocument(
    type: IssuedDocumentType.Invoice,
    eiRaw: new {
        FatturaElettronicaBody = new {
            DatiGenerali = new {
                DatiRicezione = new [] {
                    new {
                        NumItem = "5"
                    }
                }
            }
        }
    }
);

🍜  Items list​

In our web interface, you can define advanced attributes for each of the inserted items:

Items list - Add advanced attributes

This section is mapped in our API methods in the data.items_list.ei_raw field. This field's behavior is similar to what was explained in the previous section, but in this case, the root tag is DettaglioLinee (2.2.1); this means that this is the first tag that we must represent in the item (you must ignore the parent nodes) and that there can be only one root tag per item.

In the following example, we suppose that we need to set the TipoDato field (2.2.1.16.2); the following table contains the Official XML Structure for the field:

XML Tag NameXML Tag IDOccurrences
FatturaElettronicaBody2
DatiBeniServizi2.2
DettaglioLinee2.2.1root
AltriDatiGestionali2.2.1.16<0,N>
TipoDato2.2.1.16.2<1,1>

This is the final XML that we want to obtain:

<FatturaElettronicaBody>
  <DatiBeniServizi>
    <DettaglioLinee>
      <AltriDatiGestionali>
        <TipoDato>TIPO_DATO</TipoDato>
      </AltriDatiGestionali>
    </DettaglioLinee>
  </DatiBeniServizi>
</FatturaElettronicaBody>

While mapping this XML to our JSON, we have to keep in mind two things:

  • The root is the DettaglioLinee tag, so its parents must be omitted;
  • As explained before, AltriDatiGestionali can appear more than once, so it must be represented as a JSON list.

The resulting JSON will be the following one:

"ei_raw": {
  "DettaglioLinee": {
    "AltriDatiGestionali": [
      {
        "TipoDato": "TIPO_DATO"
      }
    ]
  }
}

And here you can see how to set the ei_raw field with our SDKs:

IssuedDocument invoice = new IssuedDocument(
    itemsList: new List < IssuedDocumentItemsListItem > {
        new IssuedDocumentItemsListItem(
            productId: 4,
            eiRaw: new {
                DettaglioLinee = new {
                    AltriDatiGestionali = new [] {
                        new {
                            TipoDato = "TIPO DATO"
                        }
                    }
                }
            }
        )
    }
);

💸  Payments list​

In our web interface, you can define advanced attributes for each of the inserted payments:

Payments list - Add advanced attributes

This section is mapped in our API methods in the data.payments_list.ei_raw field. This field's behavior is similar to what was explained in the previous section, but in this case, the root tag is DettaglioPagamento (2.4.2); this means that this is the first tag that we must represent in the item (you must ignore the parent nodes) and that there can be only one root tag per item.

In the following example, we suppose that we need to set the CAB field (2.4.2.15); the following table contains the Official XML Structure for the field:

XML Tag NameXML Tag IDOccurrences
FatturaElettronicaBody2
DatiPagamento2.4
DettaglioPagamento2.4.2root
CAB2.4.2.15<0,1>

This is the final XML that we want to obtain:

<FatturaElettronicaBody>
  <DatiPagamento>
    <DettaglioPagamento>
      <CAB>CAB</CAB>
    </DettaglioPagamento>
  </DatiPagamento>
</FatturaElettronicaBody>

While mapping this XML to our JSON, we have to omit the root's parent tags, as already explained above.

The resulting JSON will be the following one:

"ei_raw": {
  "DettaglioPagamento": {
    "CAB": "CAB"
  }
}

And here you can see how to set the ei_raw field with our SDKs:

IssuedDocument invoice = new IssuedDocument(
    paymentsList: new List < IssuedDocumentPaymentsListItem > {
        new IssuedDocumentPaymentsListItem(
            amount: 122,
            eiRaw: new {
                DettaglioPagamento = new {
                    CAB = "CAB"
                }
            }
        )
    }
);