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 section 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/standards/what-is-zugferd/what-is-zugferd.html )

In short, it is a PDF that contains an XML that can be viewed with e.g. Adobe Acrobat Reader and read by Lobster Integration.

Main settings: Preparser

Here you can use the preparser ZUGFeRD 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.

Phase 3: Structure and mapping

Phase 3 lays 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/standards/zugferd-2.3/zugferd-2.3.html

Case study

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 three sub-XSDs in the root directory of your Integration Server.

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.

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

More about XML schemas in section 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.

If you look at a ZUGFeRD sample XML, you will notice the prefixes before the XML tags. As well as the elements that are prefixed with xmlns:, which could also be considered attributes.

These are namespaces that assign a unique address to individual XML elements. You can read more about namespaces here: https://en.wikipedia.org/wiki/Namespace

These are not automatically created, but can be defined using fields with a special syntax.

A field for a namespace definition is always given the name of the namespace and the suffix _nsdef.

So let's stay with the ZUGFeRD 2.3 EXTENDED example. The following namespaces are required there:

So here we have five namespaces that need to be declared. So create the fields as follows and give them the URI as a fixed value:

The declared namespaces must now be made known to the nodes and fields to give the tags the appropriate prefix.

The XML namespace attribute is available in the node and field properties for this purpose. Enter the namespace to be used as a suffix for the XML element.

If a child structure is to have the same namespace, the namespace can be inherited by the child nodes and fields using the context menu.

To do this, right-click on the relevant node to open the context menu and select Hand down XML namespaces.

Go through the whole structure to assign the namespaces to the elements, exactly as in the examples in the package.

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

Note: Make sure that this is a directory within the installation directory of the Integration Server and not a network drive.

The PDF can also be generated with the PDFCreator if this cannot be done by another system.

Phase 5: Integration Unit

There are two ways to create a ZUGFeRD:

1. ZUGFeRD IU.

2. The XMLNoTemplateUnit in combination with the postexecuter ZUGFerdPDF.

Our recommendation is the second option. 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 section Match codes, unique/reserved names for 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 Integration Unit in the Check postparsing area.

In this case the result of the Integration Unit 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.

Phase 6: Create ZUGFeRD

Of course, any type of Response can be used.

The Response (or Responses) that is to output the ZUGFeRD as a result, contains the postexecuter ZUGFerdPDF in the Content settings.

Here you need the path to the PDF invoice. This should come 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:

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?

Again, no problem. The ZUGFeRD version can be determined from the XML using the following points.

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

We now know the version, but what about 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 done 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 the XML and the PDF.

For example, 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.

Deviating names of the XML

It can also happen that a partner sends you a ZUGFeRD (or at least claims to) and the XML cannot be read by the ZUGFeRD preparser or the ZUGFeRDExtractXML postexecuter, because there is no XML with the names described above in the metadata.

However, if you look at the PDF with Adobe Acrobat, the supposedly correct name is there.

If this is the case, it is not a valid ZUGFeRD invoice. The XML part can still be read, but not with the ZUGFeRD bord tools.

In this case use the preparser ExtractFileFromPDF.

However, you should point out to your partner that this is not a valid ZUGFeRD.

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.

Troubleshooting

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 criticised, it must be checked at the point where the PDF is created. Lobster Integration was not able to create 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 the ZUGFeRD.