Infothek

How to write EN16931 (=ZF2) XML

I realized that I might as well summarize all suggestions how to write EN16931 XML: 

EN16931 XML is available as UBL and UN/CEFACT.
This text targets UN/CEFACT XML in order to be used within a PDF file as ZUGFeRD 2/Factur-X.

1. Schema:

The EN16931 schema file for UN/CEFACT is the "SCRDM uncoupled" from 2016 ("16B") version
available from https://www.unece.org/cefact/xml_schemas/ .
The schema file which comes with the ZUGFeRD "info packet" should be pretty much equivalent.

In some languages like Java or .net it is common to generate classes from schema files.Although this approach (how it could be done in java) is possble I personally consider this a big overhead and usually recommend just using string buffers in particular if you only write.

2. CIUS

The standard (EN16931) specifies so called CIUS, roughly a kind of completeness level.
Since they have attributes which really make sense, like BuyerReference, we'll use the XRechnung CIUS. If you can't provide BuyerReference, i.e. an order number, you can later ignore the warnings in the XRechnung validator.

ZUGFeRD/Factur-X also specify completeness levels which they call profile, we'll just use the one called EN16931.

3. Getting started/samples

If you migrate from ZF1 please be aware of the list of changes and as a first start you might as well try and help developing the according experimental XSLT transformation which can be tested with the mustangproject command line.

Fundamentally, I know only one public example of a XRechnung.
Another example worth mentioning in this case would be the XML content of the Mustangproject sample.

The reason why the second example fails the XRechnung validator is interesting:

4. Validators

You can download the official XRechnung validator using something like

mkdir xr
cd xr
wget https://github.com/itplr-kosit/validator/releases/download/v1.0.2/validationtool-1.0.2-full.zip
wget https://github.com/itplr-kosit/validator-configuration-xrechnung/releases/download/release-2018-12-19/validator-configuration-xrechnung_1.2.0_2018-12-19.zip
unzip validationtool-1.0.2-full.zip
unzip validator-configuration-xrechnung_1.2.0_2018-12-19.zip
mkdir test/instances

then copy your test files into test/instances and you can get your XRechnung report HTMLs into test/reports
using

java -jar validationtool-1.0.2-standalone.jar -s scenarios.xml -o test/reports -h test/instances/*.xml

Now the EN16931 ZF profile requests the RAM:ID element to be exactly
urn:cen.eu:en16931:2017 while XRechnung requires urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_1.2 .

So feel free to add #compliant#urn:xoev-de:kosit:standard:xrechnung_1.2 to the Mustangproject sample in order to have the XRechnung validator pick it up. It should not complain about anything else.

Or do the contrary and remove the fragment from the XRechnung and throw it through an open-source ZUGFeRD Validator.

The output of

wget https://github.com/ZUGFeRD/ZUV/releases/download/v0.8.0/ZUV-0.8.0.jar

java -jar ZUV-0.8.0.jar -x <your file here>

should not contain the word "invalid".

Please note that the schema file may tell you which elements you can use.
But it may not be sufficient to check your XML, the schematron files are something completely different: a schematron uses XPath and can compare and calculate.
E.g. a schematron can check if the invoice date is not before the delivery date as required by the specs or if the total amount matches the sum of the items.
The validators will also run against schematron and you are on the safe side only if both schema and schematron validates.

5. Rules

Feel free to tailor the samples to your needs and run them through the validators to check if they "still work". However, if you are in question how many decimals you may use, or how the calculation works at all, please note that that is covered in the first part of the standard, EN16931-1.

And after some debate (further details in german) on very high levels, it has been agreed that the CEN should publish at least one edition of that first part of that standard free of charge.
The CEN consists of the member institutions, in Germany the DIN, and you can download the english, french and german text of the EN16931 standard for free e.g. at the DINs publishing house, called Beuth.

6. Codelists

This gives you almost everything what you need. But you might sell articles not by piece but e.g. in five packs. Or you don't have a german VAT ID. Or you want to identify organizations differently, send an invoice to Malaysia etc..

In that case you would need to use different identifying attributes, read "codes" in that files.

I recently learned (from Daniel Vinz, thanks) that the CEF has a very handy summary of all "codelists"
that you can use in EN16931, where e.g. the unit codes from the famous UN/CEFACT Rec 20 are listed. Some are from 21, though. Apart from the five pack (P5) you will find "piece" (XPP), litre (LTR), kilogramm (KGM), hour (HUR), lump sum (LS) and of course British thermal unit per square foot hour (N50),  volt square inch per pound-force (H22), nanosievert per second (P68) and as well as parsec, C63.

7. PDF

Since ZF2, the PDF part is technically no longer required, just very much recommended.
There are free command line tools like Mustangproject, which can combine your XML file with
a proper PDF like this:

java -jar mustang-1.7.2.jar -c --source <your pdf/a-1> --source-xml <xml file> --out <your pdf a/3>

Feel free to validate the resulting PDF file embedding a XML file using e.g. VeraPDF, or have
ZUV do that for you (by using -z <PDF file> instead of -x <XML file>).