Skip to main content

e-Invoicing API

System Preparation​

Configuration​

For issuing e-invoicing messages the configuration of base data (company, location and e-invoicing) is required. Details on maintaining the configuration can be found in the chapter API - Base data/company header data and Cfg - Configuration

warning

It is important to fill in the "ContactElectronicMail" field in the configuration so that in case of an error the creator of the e-invoice receives an email notification.

Application Programming Interface (API)​

This chapter shows the extensions to the existing ESR specification.

First of all you have to trigger the electronic delivery of a transaction document. To do so please specify Document Delivery ESR.DD, e.g.: DD="IT". Secondly, you must also specify the recipient of the Document Delivery (DDto).

info

In the Document Delivery (DDto) field, the delimiter ; can be used to add additional information.

AttributeDescriptionExample
ESR.DDSystem with which the e-invoice is transmitted. Only the country code needs to be specified. A special system can also be specified."DE"
"IT"
"IT-FatturaPA"
ESR.DDtoUnique Recipient of the e-invoice. see table below.
Country (DD)NameDescriptionExample for DDto
DELeitweg ID (B2G)The Leitweg ID is an identifier of an electronic invoice for the unique addressing of public contracting authorities in Germany"0204:991-33333TEST-33"
DEE-Mail (B2B)E-Mail adress of the receiver"j.doe@efsta.eu"
ITCodice Destinatario (B2B)The Codice Destinatario is used for sending tax documents in XML format to the Exchange System."VSRLPXY"
ITCodice Fiscale (B2B)Codice Fiscale is a code used for tax and administrative purposes to uniquely identify Italian citizens."TMBLRT66T19A944Z"
ITPEC Destinario (B2B)For PEC Destinario, an email address can be specified in addition to the Codice Destinatario or Codice Fiscale"TMBLRT66T19A944Z;j.doe@efsta.eu"

Customer data​

Different from issuing simplified invoices, electronic documents always require full identification of the customer, including additional address information for the transport system. It is recommended to provide a well-maintained customer database on POS software side, and eventually a function to enter data of walk-in customers. Details about customer data can be found at Ctm Elements.

warning

Customer data is mandatory for e-Invoice. For B2B invoices, a TaxId must always be specified.

Additional invoice information​

This information can optionally be sent with the invoice. It is in addition to the normal invoice. Details on the UBL attributes can be found at https://docs.peppol.eu/poacc/billing/3.0/syntax/ubl-invoice/tree/

AttributeDescriptionExample
ESR.UBL_DueDateDue date of payment. Only to be specified, if it differs from Terms of payment."2024-08-15"
UBL_Contact
UBL_Person
ESR.UBL_PaymentTermsTerms of the payment. Only to be specified, if it differs from the Terms of payment in the configuration."30 days net"
ESR.UBL_Delivery.DThe date on which the supply of goods or services was delivered"2024-07-08"
ESR.UBL_Delivery.AdrThe address where the delivery was made
ESR.UBL_Delivery.Adr2The address extension where the delivery was made
ESR.UBL_Delivery.CityThe city where the delivery was made
ESR.UBL_Delivery.ZipThe postcode where the delivery was made
ESR.UBL_Delivery.CountryThe country code where the delivery was made
ESR.UBL_ProfileIDhttps://docs.peppol.eu/poacc/billing/3.0/syntax/ubl-invoice/cbc-ProfileID
ESR.UBL_BuyerReferenceAn identifier assigned by the Buyer used for internal routing purposes. An invoice must have buyer reference or purchase order reference (BT-13).
ESR.UBL_OrderReference
ESR.UBL_ContractDocumentReferenceThe identification of a contract.
ESR.UBL_ProjectReferenceThe identification of the project the invoice refers to.
ESR.UBL_Supplier.NameThe Name of the supplier. Only to be specified, if it differs from the ContactName in the configuration."John Doe"
ESR.UBL_Supplier.TelephoneThe contact phone number of the supplier. Only to be specified, if it differs from the ContactTelephone in the configuration."123456789"
ESR.UBL_Supplier.ContactElectronicMailThe E-Mail address of the supplier. Only to be specified, if it differs from the ContactElectronicMail in the configuration."j.doe@efsta.eu"
ESR.UBL_Payee.NamThe name of the payee. Only to be specified, if it differs from the Nam field of the Customer object.
ESR.UBL_Payee.TaxIdThe VAT number of the payee. Only to be specified, if it differs from the TaxId field of the Customer object.
ESR.UBL_Payee.GLNThe GLN number of the payee.
ESR.UBL_Payee.AdrThe address of the payee. Only to be specified, if it differs from the Adr field of the Customer object.
ESR.UBL_Payee.Adr2The address extension of the payee. Only to be specified, if it differs from the Adr2 field of the Customer object.
ESR.UBL_Payee.CityThe city Name of the payee. Only to be specified, if it differs from the City field of the Customer object.
ESR.UBL_Payee.ZipThe postcode of the payee. Only to be specified, if it differs from the Zip field of the Customer object.
ESR.UBL_Payee.CtryThe country code of the payee. Only to be specified, if it differs from the Ctry field of the Customer object.
Pos.UBL_OrderLineReference
Pos.UBL_TaxExemptionReasonCodeA coded statement of the reason for why the amount is exempted from VAT.
Pos.UBL_TaxExemptionReason

Example Request​

{"Tra":
    {"ESR":
        {"DD":"IT", "DDto": "CRCCLL95S67H501V",
            "Ctm":
                {"Nam":"The Buyercompany Inc", "Zip":"15000", "City":"Metropolis",
                "TaxId":"IT123456789"},
            "PosA":[
                {"PN":"1", "IN":"4712", "Dsc":"Bike", "TaxG":"A", "Amt":"499.00"},
                {"_":"Mod", "PN":"1", "Dsc":"Discount", "Amt":"-10.00"},
                {"PN":"2", "Dsc":"helmet", "TaxG":"A", "Amt":"39.90"}],
            "PayA":[
                {"Dsc":"creditcard", "PayG":"creditcard", "Amt":"528.90"}
            ]
        }
    }
}

Workflow​

The workflow for the /register REST request follows the usual POS rules, except that additional formal checks on the data supplied are performed. In case of an invalid XML result, the request is rejected with <Result RC="BAD" ErrorCode="xxx"/> (http status code 406) giving the code of the validation rule that failed. Fix eventual errors during development to avoid problems in production environment. Since the validation of the data (recipient) takes place online, the request can take up to 5 seconds longer than a normal transaction.

If the EFR is offline when you create an e-invoice, validation will be skipped and the e-invoice will be temporarily stored on the EFR. As soon as the EFR service is back online, the e-invoice will be sent. In this case, a validation error may occur after the e-invoice has been created and the e-invoice cannot be delivered.

General eInvoicing Workflow Detailed eInvoicing Workflow

Error Handling​

The formal rules of an e-Invoice exceed the data required for a normal receipt and have to stand automatic check routines, that are performed before fiscalization and delivery (e.g. .xsd validation). In case of severe error HTTP StatusCode 406, RC="BAD" is delivered by EFR.

To find out more details about a failed transaction see directory /EFR/rn/def/log/{yyyymmddhhmmss}.log, where request and XML data is stored. Explanation for errors can be found in the internet, use "UBL" and the error code for searching.

In case of a temporary delivery failure (internet outage), the delivery will be retried 24 hours, after that the document is forwarded to EFSTA cloud for further treatment in the Portal.

If the document cannot be delivered because of an error of the receiver, the forwarding is done immediately.