How to write EN16931 XML

[Jochen Stärk]

Hi,

I realize 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.

ZUGFeRD(=ZF) equals Factur-X(=FX), except that
ZF is issued by the german FeRD and FX is issued by the french FNFE and the
funny fact that the version number of ZF is 2 while the one of FX is 1.

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.

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. Sample

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 one, mine, 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 my 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 a guy called 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 my personal favorite, 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>).

Have fun,

Jochen

-- 
mit freundlichen Grüßen
Jochen Stärk

www.usegroup.de
Huswertstraße 14
60435 Frankfurt

Tel: (069)569940-20
Fax: (069)569940-19
Mobil: (0177)4512645