Free and open source tool chain for generating EN16931 conforming invoices (Factur-X/ZUGFeRD, UBL, CII, XRechnung) from popular spreadsheet formats or JSON.
- E-Invoice-EU
You can currently create invoices in these formats:
CII: customization idurn:cen.eu:en16931:2017Factur-X-Minimumcustomization idurn:factur-x.eu:1p0:minimumFactur-X-BasicWLcustomization idurn:factur-x.eu:1p0:basicwlFactur-X-Basic-WLis an alias forFactur-X-BasicWLFactur-X-Basiccustomization id'urn:cen.eu:en16931:2017#compliant#urn:factur-x.eu:1p0:basic'Factur-X-EN16931customization idurn:cen.eu:en16931:2017Factur-X-Comfortis an alias forFactur-X-EN16931Factur-X-Extendedcustomization idurn:cen.eu:en16931:2017#conformant#urn:factur-x.eu:1p0:extendedFactur-X-XRechungcustomization idurn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0UBL: customization customization idurn:cen.eu:en16931:2017XRECHNUNG-CII: customization idurn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0XRECHNUNG-UBL: customization idurn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0ZUGFeRD-Minimumis an alias forFactur-X-MinimumZUGFeRD-BasicWLis an alias forFactur-X-BasicWLZUGFeRD-Basic-WLis an alias forFactur-X-BasicWLZUGFeRD-Basicis an alias forFactur-X-BasicZUGFeRD-EN16931is an alias forFactur-X-EN16931ZUGFeRD-Comfortis an alias forFactur-X-EN16931ZUGFeRD-Extendedis an alias forFactur-X-ExtendedZUGFeRD-XRechungis an alias forFactur-X-XRechnung
Case does not matter, when you specify a format.
There are a lot of variants of UBL and CII in use. See https://peppol.helger.com/public/locale-en_US/menuitem-validation-ws2 for an overview. The only real difference to the vanilla UBL and CII formats generated by e-invoice-eu are a so called customization and sometimes also a profile ID. If you have to support one of these formats, all you have to do is to specify "UBL" or "CII" as the format and provide the respective values either in the invoice data or hardcode them into your mapping.
Hardcoding them into the mapping is easy:
# ...
ubl: Invoice
cbc:CustomizationID: urn:cen.eu:en16931:2017#conformant#urn:fdc:peppol.eu:2017:poacc:billing:international:aunz:3.0
cbc:ProfileID: urn:fdc:peppol.eu:2017:poacc:billing:01:1.0
# ...This would for example create an A-NZ Peppol BIS3 Invoice 1.0.11 UBL invoice. Note that you always have to specify exactly these fields, even for CII variants. The ids will be mapped into their respective CII counterparts by the service.
The formats "XRechnung-UBL" and "XRechnung-CII" are just convenience formats for Germany. The only difference to vanilla UBL and vanilla CII are the customization IDs. If you think that another format should also be added for convenience, file an issue.
It is the user's responsability to meet other requirements of that variant.
For example XRechnung-UBL requires that the otherwise optional field
/ubl:Invoice/cbc:BuyerReference (BT-10) is filled. This is something that
you have to ensure yourself in order to create a valid invoice.
Credit notes and other documents like orders are currently not supported and support for it will require more effort.
EDI is also not supported. If you know of a tool that is able to convert UBL or CII to EDI, please let us know!
The service in its current state is meant to be run in a network with limited access or behind an API gateway that prevents abuse of the service.
One simple solution is to use ngninx as a
gateway and configure rate-limiting there. You will also want to limit
the maximum request body size.
This repository is an attempt to aid small businesses, especially in France and Germany but also in other parts of the European Union to create electronic invoices conforming with EN16931 with only free and open-source software.
It is quite unlikely that you can use anything here out of the box. See it as a starter template for your own solution.
This README.md is probably incomplete. Please see the blog post
Creating Electronic Invoices with Free and Open Source
Software
for more accurate in-depth information!
You can achieve similar results with these projects:
- Factur-X extension for LibreOffice is a LibreOffice extension to generate Factur-X invoices from LibreOffice Calc published under the GPL licence with a video tutorial. It is maybe less flexible but easier to set up.
- NodeJS 20.x
- A package manager like bun, npm, yarn, pnpm, ...
$ bun installThis may warn about "husky" missing. Just run bun install again in order
to fix this.
If you do not like bun, replace it with npm, yarn, pnpm or whatever
is currently hyped.
# development
$ bun run start
# watch mode
$ bun run start:dev
# production mode
$ bun run start:prod# unit tests
$ bun run test
# e2e tests
$ bun run test:e2e
# test coverage
$ bun run test:covBy far the easiest way is to run the application in a software container.
Pull the Docker image:
$ docker pull gflohr/e-invoice-eu:latestRun the container:
$ docker run --rm -d -p 3000:3000 --name e-invoice-eu gflohr/e-invoice-eu:1.0.0If you want to debug issues, omit the option -d so that you can see the
output of the application running inside of the container.
Access the application from your host computer:
$ curl http://localhost:3000/api/format/listThe following assumes that you run the application with start:dev and the
API is exposed at http://localhost:3000.
curl http://localhost:3000/apiIt probably makes more sense to open that URL in the browser.
$ curl http://localhost:3000/api/format/listThis will return a list with format informat. For each format, the name, the customization and profile ID, the MIME type, and the syntax (UBL or CII) is returned.
The application ships with a mapping in resources/default-invoice.yaml.
You can use it with the spreadsheet data from
contrib/templates/default-invoice.ods like this:
$ curl -X POST http://localhost:3000/api/mapping/transform/UBL \
-F mapping=@contrib/mappings/default-invoice.yaml \
-F data=@contrib/templates/default-invoice.odsThis will create invoice data in the internal format from a spreadsheet. The intended target format is UBL.
The format parameter (UBL in this case) is case-insensitive!
$ curl -v -X POST \
http://localhost:3000/api/invoice/transform-and-create/UBL \
-F mapping=@contrib/mappings/default-invoice.yaml \
-F data=@contrib/templates/default-invoice.odsThis will transform the spreadsheet into the internal format and immediately
create an invoice in format UBL.
Say you want to add a PDF version invoice.pdf and two attachments
time-sheet.ods and payment-terms.pdf to the generated invoice:
$ curl -v -X POST \
http://localhost:3000/api/invoice/transform-and-create/UBL \
-F lang=de
-F mapping=@contrib/mappings/default-invoice.yaml \
-F data=@contrib/templates/default-invoice.ods \
-F pdf=@invoice.pdf \
-F embedPDF= \
-F pdfID=1234567890 \
-F pdfDescription="Invoice as PDF." \
-F "attachment=@time-sheet.ods;type=application/vnd.oasis.opendocument.spreadsheet" \
-F "attachmentID=abc-123-xyz" \
-F attachmentDescription="Detailed description of hours spent." \
-F attachment=@payment-terms.pdf \
-F attachmentDescription="Our payment terms" \The optional lang parameter specifies the language of the document. It
defaults to en. It is currently only used for the Factur-X variants where
certain canned texts are translated.
The parameter embedPDF should be passed if a PDF version of the document
should be embedded into the XML. It only makes sense if you have specified a
format that is not Factur-X. Otherwise, it gets ignored. If you have uploaded a file pdf it
is taken. Otherwise, the file is generated with LibreOffice from the data file.
The parameter pdfID defaults to the document number.
Note that for the first supplementary attachment 'time-sheet.ods, a MIME type is explicitly specified because curl` probably does not not the correct MIME
type of OpenDocument spreadsheet files.
For each supplementary attachment, an optional description and an optional
id can be specified. If the id is omitted, it defaults to the filename of
the attached file.
The invoice document data structure is documented here: https://docs.peppol.eu/poacc/billing/3.0/syntax/ubl-invoice/
If you prefer to have it all on one page, look here: https://docs.peppol.eu/poacc/billing/3.0/syntax/ubl-invoice/tree/
A gentler introduction can be found here: https://docs.peppol.eu/poacc/billing/3.0/bis/
The service e-invoice-eu will ensure that the structure of the invoices
you generate meets the requirements of the standard. That means that it
ensures the correct number of occurences and the correct order of all elements.
It is your responsability to ensure the business requirements to the invoice. Example: The software ensures that the invoice contains the tax total but it is your responsability to ensure that the tax total is the sum of the individual tax amounts.
Most of these business requirements are defined in business rules and it is possible to check these requirements. This is called validation. See the overview on validation for more details and how you can validate your invoices locally or by uploading them to an invoice portal.
You should not ignore this! When you start creating electronic invoices it is almost inevitable that they will contain errors that are detected by a validator. Such invoices will be rejected by your customers and that costs time and money on both sides.
Please see the mapping documentation!
Amounts have to be numbers >= 0 with at most two decimal places. The following JSON schema should work for this:
{
"type": "number",
"multipleOf": 0.01
}This is even documented in the JSON Schema documentation. Unfortunately, this does not work with the JavaScript implementation, see ajv-validator/ajv#652.
There are workarounds for this limitation of Ajv but I want to avoid people naïvely validating against the schema with Ajv without applying the necessary workaround. It looks simpler to require all amounts to be formatted beforehand by the software that generates the input data.
The problem for percentages is the same only that percentages can have up to four decimal digits.
For other numerical types, like quantities, we could use numbers but for consistency we use strings throughout the schema.
See SheetJS GitHub issue #1569. You can probably ignore this warning, unless you run into a problem with number formats.
You will often see references to business terms in validation error messages. You can look up to which elements they belong in the documentation file BusinessTerms.md.
Make sure that only the sheet that contains the printable invoice data has
a print range defined. You can check that with the menu entry
Format -> Print Ranges -> Edit. For all other sheets, all three options
have to be set to None.
Please report bugs at https://github.com/gflohr/e-invoice-eu/issues.
The Factur-X resp. ZUGFeRD standard requires PDF/A compliance for the PDF that the invoice is wrapped in. Please search the internet if you do not know what PDF/A means.
This library creates PDFs solely with pdf-lib
and does some pretty complicated transformations on the PDF to achieve PDF/A
compliance. This is not battle tested and may fail.
If you encounter a PDF that does not meet the PDF/A requirements, please open an issue and attach an anonymized version of the PDF. What you can do in the meantime:
- If you have GhostScript installed, convert the PDF to PDF/A with this command:
gs -dVERBOSE -dPDFA=3 -dBATCH -dNOPAUSE -sDEVICE=pdfwrite -sOutputFile=OUTPUT_FILE.pdf PDFA_def.ps INPUT_FILE.pdf - Try to create the PDF again with LibreOffice.
- If the normal settings in LibreOffice do not work, enable PDF/A support (in the General section of the PDF options).
- If you want to automate the process, you can start LibreOffice in headless mode on the commandline:
libreoffice --headless "-env:UserInstallation=file:///tmp/LibreOffice_Conversion_${USER}" --convert-to 'pdf:writer_pdf_Export:{"SelectPdfVersion":{"type":"long","value":"3"}}' SOURCE_FILE.ods
On Un*x systems, libreoffice should be in your $PATH. On MacOS, you will
find it under /Applications/LibreOffice.app/Contents/MacOS/soffice. On
MS Windows, it is probably somewhere like C:\\Program Files\\LibreOffice\\libreoffice.exe (corrections are welcome).
This is free software available under the terms of the WTFPL.