Peppol support (eInvoicing) in Lino¶

Lino supports receiving and sending digital invoices via the Peppol network as required by companies in Belgium from January 2026.

This document explains basic Peppol concepts. See also the User Guide. For implementation details, see peppol : Peppol support (eInvoicing).

This page contains code snippets (lines starting with >>>), which are being tested during our development workflow. The following snippet initializes the demo project used throughout this page.

>>> from lino_book.projects.cosi1.startup import *

Generating Peppol XML files ¶

Lino has two database models that can become a Peppol document: VatProductInvoice and VatAccountInvoice. The former is typically used for sales and the latter for purchase. Both models inherit from lino.modlib.jinja.XMLMaker.

>>> for m in rt.models_by_base(jinja.XMLMaker):
...     if m.xml_file_template:
...         print(full_model_name(m), m.xml_file_template, m.xml_validator_file)
...
trading.VatProductInvoice vat/peppol-ubl.xml .../lino_xl/lib/vat/XSD/PEPPOL-EN16931-UBL.sch
vat.VatAccountInvoice vat/peppol-ubl.xml .../lino_xl/lib/vat/XSD/PEPPOL-EN16931-UBL.sch

In order to create the XML of a Peppol document, Lino uses a single template vat/peppol-ubl.xml.

Lino supports the UBL BIS 3.0 format for both inbound and outbound documents. Peppol differentiates between invoice and creditnote.

Lino does not validate Peppol documents (see Schematron validation for details) because that’s done by the Peppol network. During development it can be useful to manually validate an XML file

https://www.ubl.be/validator
https://ecosio.com/en/peppol-and-xml-document-validator (Select “OpenPeppol UBL invoice”)

The parties of an invoice ¶

Seller : the partner who sells. Also called supplier, provider. See cac:AccountingSupplierParty
Buyer : the partner who buys. Also called invoicee, recipient, customer. See cac:AccountingCustomerParty
Payee : the partner who receives the payment. Shall be used when the Payee is different from the Seller. Lino currently doesn’t use this element. See cac:PayeeParty.
Tax representative : the legal person who represents the seller at the tax office. Lino currently doesn’t use this element. See cac:TaxRepresentativeParty.

Both the seller and the buyer of an invoice contain a single mandatory element cac:Party, which contains a mandatory element cbc:EndpointID, which identifies the party’s electronic address.

This cbc:EndpointID element contains the identification number as a textual value, and must have an attribute schemeID, which refers to the Electronic Address Scheme (EAS) to use when looking up the identification number of a party.

In other places we need a element cbc:CompanyID,

Electronic Address Scheme ¶

One of the challenges of Peppol was how to identify your business partners across national borders. Peppol suggests a standard for international identification of legal persons.

Peppol does this in two steps: first you specify one of the recognized official registries of identification codes. Peppol knows a few hundred of them. These are called “Electronic Address Schemes” or . Let’s call them EAS.

EAS¶

Abbreviation for “Electronic Address Scheme”. A recognized official registry of identification codes.

Some documents call them “Participant Identifier Schemes”: example)

Some examples of EAS codes:

9925 : Belgium VAT number
0208 : Belgium Company number
9931 : Estonian VAT number

It seems that EAS 9925 is a subset of EAS 0208: every party subject to VAT in Belgium also as a company number, which is the same as its VAT number. Hence normal companies should be in both registers, while companies like insurances and some non-profit organizations (who are not subject to VAT and hence have no VAT number) will be only in EAS 0208.

The commondata.peppolcodes module defines a dict COUNTRY2SCHEME, which maps country codes to the EAS number of the VAT office of that country. There are nations with other identification schemes than the VAT office, but COUNTRY2SCHEME does not contain them. The Lino Peppol plugin uses this when generating a Peppol XML file for outbound documents.

>>> from commondata.peppolcodes import COUNTRY2SCHEME

>>> pprint(COUNTRY2SCHEME)
{'AD': '9922',
 'AL': '9923',
 'AT': '9914',
 'BA': '9924',
 'BE': '9925',
 'BG': '9926',
 'CH': '9927',
 'CY': '9928',
 'CZ': '9929',
 'DE': '9930',
 'EE': '9931',
 'ES': '9920',
 'FI': '0213',
 'FR': '9957',
 'GB': '9932',
 'GR': '9933',
 'HR': '9934',
 'HU': '9910',
 'IE': '9935',
 'IT': '9906',
 'LI': '9936',
 'LT': '9937',
 'LU': '9938',
 'LV': '9939',
 'MC': '9940',
 'ME': '9941',
 'MK': '9942',
 'MT': '9943',
 'NL': '9944',
 'NO': '9909',
 'PL': '9945',
 'PT': '9946',
 'RO': '9947',
 'RS': '9948',
 'SE': '9955',
 'SI': '9949',
 'SK': '9950',
 'SM': '9951',
 'TR': '9952',
 'VA': '9953',
 'international': '9912'}

>>> peppol_countries = set(COUNTRY2SCHEME.keys())

The list contains some countries that are not part of the European Union (according to lino_xl.lib.vat.eu_country_codes):

>>> sorted(peppol_countries - dd.plugins.vat.eu_country_codes)
['AD', 'AL', 'BA', 'CH', 'GB', 'LI', 'MC', 'ME', 'MK', 'NO', 'RS', 'SM', 'TR', 'VA', 'international']

Denmark is currently not in our list because it doesn’t have a registry scheme that ends with “VAT”.

>>> dd.plugins.vat.eu_country_codes - peppol_countries
{'DK'}

The VAT category ¶

The <cac:ClassifiedTaxCategory> element contains “a group of business terms providing information about the VAT applicable for the goods and services invoiced on the invoice or the invoice line.”

<cbc:ID> : The VAT category code for the invoiced item.
<cbc:Percent> : The applied VAT rate. A number, potentially with decimal positions
<cac:TaxScheme> : a mysterious but mandatory element. According to our references it must contain exactly one child element <cbc:ID>VAT</cbc:ID>, where the word “VAT” seems to mean that the seller is identified using their VAT identifier. We don’t know whether it may contain other values.

A good introduction into why we have all these categories and rates is here: VAT Rates in Europe 2024

VAT category¶: An alphabetic code defined as part of Peppol in the UNCL5305 code list.

You might think that this is a reliable definition because it mentions a “code list” called “UNCL5305”, That sounds impressive, doesn’t it. But to make things more fun, the Internet currently knows are at least two code lists called “UNCL5305”:

It seems that for Ibanity we must use the latter one. This list specifies the allowed VAT categories:

AE	Vat Reverse Charge	VAT is levied from the buyer.
E	Exempt from Tax	Taxes are not applicable.
S	Standard rate	The standard rate is applicable.
Z	Zero rated goods	The goods are at a zero rate.
G	Free export item	VAT not charged
O	Outside scope	Services outside scope of tax
K	VAT exempt for EEA	VAT exempt due to an intra-community supply of goods and services in the European Economic Area

I don’t know what G and O are used for, because none of our customers has ever asked for this.

Lino has two functions to be used in the vat/peppol-ubl.xml template:

VatItemBase.get_peppol_vat_category() returns the VAT category of a voucher item by interpreting the VAT regime and VAT class. This is used for the <cac:ClassifiedTaxCategory> element.
linox_xl.lib.VatVoucher.get_vat_subtotals() returns an iterator of 4-tuples (categ, rate, total_base, total_vat). These are used for the <cac:TaxSubtotal> elements of the document.

>>> dd.plugins.vat.declaration_plugin
'lino_xl.lib.bevat'

>>> rows = []
>>> coll = collections.OrderedDict()
>>> for obj in trading.InvoiceItem.objects.all():
...     k = (obj.vat_class, obj.voucher.vat_regime, obj.get_peppol_vat_category())
...     if k not in coll:
...         coll[k] = obj
>>> for k, obj in coll.items():
...     vat_class, vat_regime, pc = k
...     rows.append([vat_class.name, vat_regime.name, pc, obj])
>>> headers = ["Class", "Regime", "Cat.", "Line"]
>>> print(rstgen.table(headers, rows))
========== ========== ====== ===============
 Class      Regime     Cat.   Line
---------- ---------- ------ ---------------
 services   subject    S      SLS 1/2014#1
 services   intracom   AE     SLS 2/2014#1
 reduced    subject    S      SLS 6/2014#1
 exempt     subject    Z      SLS 6/2014#2
 reduced    intracom   AE     SLS 11/2014#2
 exempt     intracom   AE     SLS 12/2014#1
 services   normal     S      SLS 14/2014#1
 reduced    normal     S      SLS 17/2014#1
 exempt     normal     Z      SLS 17/2014#2
========== ========== ====== ===============

The following snippet is to test the lino_xl.lib.trading.VatProductInvoice.vat_subtotals property.

>>> obj = trading.VatProductInvoice.objects.get(pk=111)
>>> print(f"{obj} {obj.total_base} {obj.total_vat} {obj.total_incl}")
SLS 6/2014 1110.16 203.87 1314.03
>>> round(1110.16 + 203.87, 2)
1314.03
>>> headers = ['Cat', "Rate", "Base", "VAT"]
>>> rows = []
>>> for cat, rule, total_base, total_vat in obj.vat_subtotals:
...     rows.append([cat, rule.rate, total_base, total_vat])
>>> print(rstgen.table(headers, rows))
===== ====== ======== ========
 Cat   Rate   Base     VAT
----- ------ -------- --------
 S     0.12   299.00   35.88
 Z     0      11.20    0.00
 S     0.21   799.96   167.99
===== ====== ======== ========

>>> round(299 + 11.20 + 799.96, 2)
1110.16
>>> round(35.88 + 0 + 167.99, 2)
203.87

Amounts ¶

Vocabulary:

Line net amount: Invoiced quantity * Unit Gross Price
Allowances : discount or similar amount to subtract from the net amount
Charges : some fee, tax (other than VAT) or similar amount to add to the net amount
Line extension amount : Net amount + Charges - Allowances.

An invoice must have exactly one cac:LegalMonetaryTotal element, which provides the monetary totals for the invoice. It can have the following children (each child at most once):

cbc:LineExtensionAmount: Sum of all invoice line amounts in the invoice, net of tax and settlement discounts, but inclusive of any applicable rounding amount.
cbc:TaxExclusiveAmount: total amount of the invoice without VAT.
cbc:TaxInclusiveAmount: total amount of the invoice with VAT.
cbc:AllowanceTotalAmount
cbc:ChargeTotalAmount: Sum of all charges in the invoice.
cbc:PrepaidAmount: Sum of amounts that have been paid in advance.
cbc:PayableRoundingAmount Amount to be added to the invoice total to round the amount to be paid.
‘cbc:PayableAmount <https://docs.peppol.eu/poacc/billing/3.0/syntax/ubl-invoice/cac-LegalMonetaryTotal/cbc-PayableAmount/>`__: outstanding amount that is requested to be paid

Amounts must be rounded to maximum 2 decimals. Each amount element has a mandatory attribute currencyID.

Some error messages and how we fix them ¶

Error message: A buyer reference or purchase order reference MUST be provided.

The specs about cbc:BuyerReference say indeed that “An invoice must have buyer reference or purchase order reference (BT-13).”

🡒 When your_ref is empty, Lino writes “not specified”.