Content identity

As a hybrid data format, ZUGFeRD integrates structured invoice data in XML format into a PDF document (PDF/A-3). This means that the invoice is always sent in the form of a PDF document, which represents the visual component of the invoice.

At the same time, an identical multiple copy of the same invoice (XML) is also sent within the PDF, so that electronic processing of the invoice using the structured invoice data - after implementation in the company-specific software system - is possible without any problems.

PDF and XML must comply with the requirements of § 14 paragraph 4 of the German Value Added Tax Act (UStG) in order to display multiple copies of the same invoice with identical content.

As the tax authorities have not defined any specific verification obligations or control measures for this procedure, it is recommended that the sender and the invoicing party introduce their verification mechanisms to ensure the content identity of the two invoices.

In addition to the legal regulations, the principles for the proper keeping and storage of books, records, and documents in electronic form and the data access (GoBD), most recently dated November 28, 2019, must also be observed. (Source https://www.ferd-net.de/en/standards/zugferd/factur-x )

To summarise, it's a PDF containing an XML file. You can open it with Adobe Acrobat Reader and read it with Lobster Integration.

Main settings: Preparser

Here you can use the ZUGFeRD PreParser for preprocessing by selecting it in the Main settings under Extensions → Check preparsing.

This will extract the contained XML with the name ZUGFeRD-invoice.xml, zugferd-invoice.xml or factur-x.xml without any further configuration.

Click here for documentation: ZUGFeRD (Preparser)

Then, the XML is given to the profile as an input file.

Phase 3: Structure and Mapping

Phase 3 creates the foundation for the ZUGFeRD XML message. The structure for the desired conformance level, including the necessary namespaces, is created here.

For ZUGFeRD, the structure is generated from multiple XSDs. It is important that you always use the structure for the required ZUGFeRD version and conformance level.

All available ZUGFeRD information, including all XSDs for the current ZUGFeRD version 2.3 (as of 24 September) can be found here: https://www.ferd-net.de/en/downloads/publications

Case study - Use XML templates (recommended)

Namespaces are also included. So, after importing the template, all that's left to do in the target is the mapping. To use an XML structural template, click on Menu → Load template → XML on the target side.

A new window will open in which you can then select the desired ZUGFeRD type.

Choose the template you want to use. This will create the whole tree and set up the namespaces. Then, you can continue with the mapping.

You can also load the structures from the menu on the source side. The document type in the base data must be set to XML, and the path is the same (Menu → Load Template → XML).

To use the source structure correctly, you need to create matchcodes. Lobster Integration can automatically create these for XML structures.

To do this, open the Menu on the source side and select Recreate matchcodes. A window will then appear to confirm this and show you which record type was created.

Case study - Manual structure import via XSD

So, if you need ZUGFeRD 2.1 EXTENDED, download the 2.3 package and select the appropriate schema. The schemas are backward compatible.

In the case of ZUGFeRD 2.1 EXTENDED, use ZUGFeRD 2.3 EXTENDED. The schema consists of 4 XSDs:

1. Factur-X_1.0.07_EXTENDED.xsd (Main XSD file)

2. Factur-X_1.0.07_EXTENDED_urn_un_unece_uncefact_data_standard_QualifiedDataType_100.xsd

3. Factur-X_1.0.07_EXTENDED_urn_un_unece_uncefact_data_standard_ReusableAggregateBusinessInformationEntity_100.xsd

4. Factur-X_1.0.07_EXTENDED_urn_un_unece_uncefact_data_standard_UnqualifiedDataType_100.xsd

The main XSD file references the sub XSDs. Place the 3 sub-XSDs in the root directory of your Lobster Integration.

Now create the target structure from the file analysis using the target structure menu (Menu → Create structure → from file analysis) by dragging the main XSD onto the analysis and selecting XSD/DTD Schema as the type.

Enter CrossIndustryInvoice as the XML Root element name and click Apply.

Note: If you do not know the root name of an XSD, you can enter data in the field. Lobster Integration will then search for the root name. The prerequisite is that there is only one root name in the XSD.

Since the structure for ZUGFeRD 2.3 Extended represents the maximum expression, the target tree will be very large. For recursive structures, such as the ZUGFeRD structure, Lobster Integration does not consider all levels by default, which means that field names containing Skipped_to_much_content... are created.

Lobster Integration provides parameters in the XSD parser to prevent this behavior.

These parameters are maxDuplicatedElementCount and maxRecursionDepth.

For ZUGFeRD 2.3 EXTENDED, set maxDuplicatedElementCount to 800 and maxRecursionDepth to 100.

Then click Apply.

Conveniently, the document type XML and the root element are automatically entered in phase 2, so you don't have to worry about them.

More about XML Schemas: XML Schemas - XSD/DTD Files

Once you have done everything correctly, a structure is created, and you can start mapping.
The ZUGFeRD package also includes descriptions to help you find the right locations for your data.

Namespaces

ZUGFeRD XML uses namespaces, which must be declared in the root element with the prefix xmlns and a suffix, e.g., xmlns:rsm="urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100".

Namespaces are created either as fields or in the namespace administration. Both methods are described below. Please use only one of them.

Namespaces specified there are always entered in the root element of the XML, exactly as we need them for ZUGFeRD.

In addition, the namespaces are automatically displayed in the XML Namespaces attribute in the drop-down menu, where they can be selected.

If you change the name of a namespace in the namespace manager, the change is immediately reflected in the structure, so no nodes or fields need to be adjusted.

Mapping

So, we've talked a lot about XML, but you're probably wondering when the PDF invoice will become important. - Right now.

Once the mapping is complete, you should also consider where the PDF invoice comes from.

Ideally, an upstream system has already created it and placed it in a directory. Determine this path using your own logic and store it in a variable that we will need in one of the next phases.

Note: Please note that this is a directory within Lobster Integration and not a network drive. In principle, you can enter a network drive here, but you will only be able to access shares that are shared with the user Lobster Integration is running as.

The PDF can also be generated by Lobster Integration if this cannot be done by another system.

More information about this can be found here: ZUGFerdPDF

Phase 5: Integration Unit

There are two ways to create a ZUGFeRD:

1. ZUGFeRD IU

2. The XMLNoTemplateUnit in combination with the ZUGFeRDPDF PostExecuter

Our recommendation is the second way with the XMLNoTemplateUnit in combination with the ZUGFeRD PostExecuter.

The advantages are obvious:

1. There is no need to create a template.

2. All XML features (attributes, namespaces, structures) are created in the target structure, are visible to everyone, and are easy to debug. See also: Match Codes, Unique Names, Reserved Names (XML)

3. The XML can also be easily accessed in other responses.

Based on the recommendation, use the XMLNoTemplateUnit as usual.

Depending on whether you need the XML in other responses (e.g., for the archive) or not, the ZUGFeRD PostExecuter can be used directly under the IU in the Check postparsing area.

In this case, the result of the IU would always be the ZUGFeRD, and the XML could only be read via this.

It is therefore recommended that the ZUGFeRD is only created in the appropriate response path.

Phase 6: Create ZUGFeRD

Of course, any type of response can be used.

The response (or responses) that the ZUGFeRD is to output as a result is given to the PostExecuter ZUGFeRD PostExecuter in the Content settings.

Here you need the path to the PDF invoice. This should be completely from a variable. The conformance level and the ZUGFeRD version are also expected in the configuration.

As of ZUGFeRD 2, additional attachments can optionally be packed into the PDF.

Let's say we wrote the path to the PDF invoice in phase 3 in the variable var__path_to_PDF, we need the EXTENDED conformance level, we create a ZUGFeRD version 2, and we don't want any more data with attachments.

The configuration will look like this:

@var__path_to_PDF@:EXTENDED:2

Also set the Content settings to Output from IU and the encoding to UTF-8.

The result is a ZUGFeRD PDF with embedded XML.

But now you may be wondering which ZUGFeRD version and conformance level is required when. - Good question!

The answer is quite simple: Your partner will tell you which ZUGFeRD version and which conformance level to send.

But what if your partner has only sent you a sample XML?

Don't worry, it's easy. You can work out what version of ZUGFeRD it is using the points below.

1. The name of the XML
   ZUGFeRD 1: ZUGFeRD-invoice.xml and zugferd-invoice.xml.
   ZUGFeRD 2: factur-x.xml.

2. The root element
   ZUGFeRD 1: CrossIndustryDocument
   ZUGFeRD 2: CrossIndustryInvoice

So we've identified the version, but what's the conformance level?

This is conveniently contained in a valid ZUGFeRD message in the data. Look for the <ram:ID> tag. There you will find a string containing the specific conformance level.

In this example we can see that the conformance level is BASIC.

With this information, the ZUGFeRD configuration can be performed successfully in any case.

Phase 6: Read ZUGFeRD

In parallel to the ZUGFeRD PreParser, which reads an XML from a ZUGFeRD, there is also a PostExecuter that can do this: ZUGFeRDExtractXML

This can be used, for example, if only the PDF part is to be analysed in phase 3 to decide what to do with XML and PDF.

There may be a response that archives the whole ZUGFeRD, one that sends the XML to a processing profile and one that archives only the XML.

The PostExecuter should not be used in phase 5.

PDF/A-3

ZUGFeRD is based on the PDF/A-3 standard. Lobster Integration tries to convert the linked PDF invoice into a PDF/A-3 when creating the data. For this to succeed, the PDF must be created correctly.

Contrary to the documentation, a PDF-A can also be used, as the metadata is usually already in the correct form.

EN16931 XRECHNUNG

ZUGFeRD 2.2 in the XRECHNUNG conformity level is accepted by the German authorities as the invoice format for e-invoices under EN16931.

However, only the XML part without PDF is expected. Please also note the requirements of the respective authorities and partners.

The process for creating the XML is exactly the same as for the other types, except that the XML is not packed into a PDF at the end.

As the ZUGFeRD XML templates with conformance levels EN16931 and EXTENDED comply with ISO EN16931, they can be used for mappings that need to support the CII format.

Troubleshooting

1. Invalid PDF/A3 or XML

   If a validator objects to the XML or PDF, several things need to be checked.
   
   If the XML is objected to, check that the structures are correct, that all namespaces are correctly declared and mapped, and that the correct formats and codes are present in the appropriate places according to the ZUGFeRD descriptions.

   If the PDF itself is being criticized, it must be checked at the point where it is created. Lobster Integration could not make a valid PDF/A-3 from the existing PDF.

   This may be due to faulty PDF metadata. This can happen, for example, if several different applications have been used to create the PDF.

   We are working to ensure that these external influences no longer affect the creation of valid PDF/A-3.However, if you have a problem with a PDF, please ask your partner if they would accept ZUGFeRD.