A Journey Implementing Digital Invoices

2020 07 01 head

Our company has the ambition to digitize all our workflows since our inception. We proudly state we never bought a printer or a fax machine. Analog machines should become obsolete in the digital age.

Companies should be more environment-aware and save some trees. See our blog on A Journey to Be a Digital Company.

Switzerland finally introduced a digital payment slip. It uses a QR code and still assumes you need to print it.

The European Union is more innovative and mandates that invoices to government parties must be digital. Our company exchanges contracts and invoices with partners and customers using the standardized and well-known PDF format.

It is time to explore extensions to support the new legal requirements in Switzerland and in Europe.

We show open source-based solutions, and the tradeoffs we had to accept. Beware our solutions are based on the Java stack.

Swiss QR Code

The Swiss QR-bill standard is based on a 2D barcode and associated human-readable text mirroring the data encoded in the barcode. The barcode approach assumes the buyer will print the invoice. The interested parties have to scan the barcode to digitize the invoice information. This approach clearly breaks digitalization efforts.

Our approach is to add the barcode to the PDF invoice document. The workflow can open the digitally received document and parse programmatically the image of the barcode. The generation of the invoice and associated barcode is fully digital.

This approach works well only if the issuer fills the so-called SWICO field of the QR code with needed information. For example, the due date of the invoice and the enumeration of different VAT tax percentages and corresponding VAT taxes are only stored in this field. In other words, the standard does not foresee that the due date of the invoice should be a mandatory field. Stated bluntly, the committee in charge of the standard realized they missed and stuck all missing elements in the so-called SWICO field. It is clear that it is impossible to define a digital payment workflow without information on such a due date, and the VAT percentages and amounts.

The library Swiss QR Bill is a mature and a simple solution to read and to write legal Swiss QR codes. The library is under MIT license and is available for Java and .NET stacks. The code is under active development. The main developer is responsive to suggestions and trouble reports.


The ZUGFeRD is a German initiative to promote digital invoices in Germany and in Europe. The ZUGFeRD approach is to store the invoice data as an XML part in the PDF document of the invoice. The standard is also called Factur-X in France. It is compatible with the European B2G invoices standard, namely EN16931. It can also be used for B2B invoices.

XML is not really a human-readable format. A JSON-based approach would have been more friendly. The advantage is that the standard contains all relevant information for an invoice and streamlines the digital processing of invoices. You can define a workflow extracting and parsing the XML payload from all received invoices, and feeding the information to your ERP system for further processing.

The library Mustang ZUGFerD is a mature and usable solution to read and write digital ZUGFeRD invoices. The library is under Apache 2.0 license. The current version 2.1 of the standard is fully supported. ZUGFeRD additionally can transform a PDF/A-1 into a PDF/A-3 format.

Other similar libraries are also available, but the ones we found have quite restrictive licenses.

PDF Aspects

The PDF format is universally known. Special variants such as PDF/A1 and PDF/A3 are defined for archiving purposes.

The Apache foundation hosts the library PDFBox. It provides all low-level functions to create, read and edit PDF documents. The library is naturally under Apache 2.0 license.

But no open source products are available for high-level functions. In particular, support for the creation of archive formats is non-existent. The famous iText library provides all these features, but sadly is no more open source.

Ghostscript provides command line support to transform a PDF document in a PDF/A version.

The online service pdftron provides free PDF translation to the archive format. The Scribus application supports archive format export. The drawback is that these approaches are they require manual steps [1].

The Mustang library supports the transformation of a PDF/A1 to a PDF/A3 document. [2]


We decided to extend our open source library to create digital invoices. The extensions support the Swiss QR Code and the ZUGFeRD 2.1 standards. All the information is stored in one PDF document. This document is sent electronically to the customer.

Our current approach is

  1. Generate AsciiDoc Invoice from our invoice model (Java source code)

  2. Generate the PDF output format of Invoice using AsciiDocPDF

    1. Add Swiss QR code as last page in the PDF invoice document

    2. Add ZUGFeRD XML payload in the PDF invoice document

Currently, we do not generate PDF/A1 documents as required in the ZUGFeRD standard. PDFBox could provide the tool box to generate in this format, but it would be quite an endeavor. An extension to PDFBox with similar functionality to iText would ideally become available in the future. Otherwise, we have to write the missing code; in particular, the embedding of fonts, pictures and files into the PDF document.

We selected the AsciiDoc format to provide a simple approach to custom templates for invoices. We avoided proprietary solutions based on Microsoft Office templates.

Feel free to use our library and examples. They are released under Apache 2.0 license.


The source code for the invoice component is available as a Java package. More information is available under tangly open source components.

The generator code for the Swiss QR bill and ZUGFeRD data is available as Java package. The developer was very supportive to improve the component. For example, it is now possible to write unit tests using in-memory file systems.

The Facture-X component also supports unit tests using in-memory file systems.

Not all Java developers have realized that the Java class File should be deprecated. java.io.File instances always access the default file system.

java.nio.Path instances contain the file system it should use and support in-memory file systems. Use java.nio.Files to create input streams, output streams, buffered readers, or buffered writers using path instances.

The investment to create the generators and test them against regular invoices of tangly llc was around four man-days.

You can find more information about how to digitize your company in a blog describing our journey to a digital company. We are quite proud of not having any Microsoft Office our Outlook tools. Our whole toolchain is based on open source solutions and performs flawlessly since the foundation of our company.

1. OnlyOffice also support PDF/A creation. They provide a free local installation package for Linux, macOS, and Windows
2. LibreOffice can open and manipulate PDF files. You can open a PDF file and export it as PDF from LibreOffice. The application supports exporting to PDF/A version 1b, 2b and 3b. It also supports PDF/UA.