ZUGFeRD Creator: setup and mapping

Step 1

Server and keys

The „Preferences“ tab contains three entries: the address of your own web server on which the PHP component resides, an API key for the AI suggestion, which is optional, and the license key. Below are two container fields in which the generated ZUGFeRD PDF and the UBL file are placed.

The graphic on the right of the picture shows the path: from the invoice in the invoicing solution, via the mapping to EN 16931, to a PDF/A-3 with embedded XML.

Step 2

The mapping

The „Zuordnung“ tab is the central page. At the top right there is one tab per document type, here „Rechnung“ and „Gutschrift“, plus „+ Belegart“.

On the left are the settings of the document type: name, type code (380 for the invoice, 381 for the credit note), the table occurrence of the document, the layout, the field with the document number, the container field with the printed invoice, the target container fields and the details for the line items.

On the right is the actual mapping, divided into five sections with counters: Beleg 15/17, Verkäufer 9/10, Käufer 7/7, Zahlung 4/5, Positionen 8/9. Each line is a value of the e-invoice, with its number from the standard (BT-1, BT-2, BT-5 and so on) and a short explanation. Next to it is the input field: it holds a field of your own solution, a FileMaker formula or a fixed value. The small marker behind it says what it is:

Mandatory fields are marked, as are the entries that are mandatory only for the XRechnung, such as routing ID, contact person, telephone and email of the issuer.

The preview

On the far right is the „Vorschau“ column. If you enter a document number below and press „Vorschau“, you see the real value of this document in each line, before the first invoice is created. The result appears at the bottom left, in the picture „Vorschau für RE602127: 48 Werte, 7 leer.“ This way you can see whether the mapping holds before the first test.

Step 3

The AI suggestion

Instead of filling in the mapping by hand, you press „KI-Vorschlag“ below. The software sends the names and types of the fields to your own server, which asks a language model. For each value, a suggestion with a reason comes back.

The picture shows the „Verkäufer“ section. On the right, each line shows the source and the confidence, „KI · hoch“ or „KI · mittel“, and below it the reason in plain text, for example „USt-IdNr. des Ausstellers“ or „kein Landcodefeld beim Verkäufer, deutsche Firma“. If the AI finds nothing, it says there in red „KI · niedrig · nichts gefunden“.

Anything that differs from the saved state gets the marker „GEÄNDERT“ or „NEU“. The old value appears next to it with a strikethrough, and a small „zurück“ button restores it. At the bottom is the summary, in the picture „29 von der KI, 14 über den Namen, 5 offen, prüfen und speichern.“

Important: Only field and table names are transmitted, no invoice data. The API key belongs to the customer, the function is optional.

Step 4

Further document types

Each document type has its own tab and its own mapping. The credit note carries type code 381, and for it „Bezug auf Rechnung“ (BT-25) is filled, the reference to the original invoice.

A new document type is created via „+ Belegart“: enter the name and table occurrence on the left. As you type, the software suggests all table occurrences of the connected solution. The same help is available in every mapping field for the field names.

Step 5

Saving and transferring

With „Export“, the entire mapping can be displayed and copied as JSON, and read back in with „Import“. This lets you back up a finished setup or transfer it to another installation.

Step 6

Testing

At the top left are „Test PDF“ and „Test UBL“ with a field for the document number. Both create the file exactly as the invoicing solution will do later. The result is placed in the container fields from step 1: on the left the finished ZUGFeRD PDF, which looks like the familiar invoice and carries the XML inside, on the right the UBL file of the XRechnung.

Step 7

Integration into your own solution

In your own solution, a single button is enough, calling a script with three entries: document type, document number and format. The finished file comes back.

1. No field of your own solution has to be changed.
2. No auxiliary fields, no layouts with fields.
3. What changes, changes in the mapping, not in the invoicing solution.

The other direction

Reading incoming invoices

The Creator writes e-invoices. Incoming invoices are read by the ZUGFeRD Reader, which uses the same server component and is part of the ZUGFeRD Suite. It accepts what is in use on the market: ZUGFeRD and Factur-X as PDF/A-3 with embedded XML, XRechnung as UBL, invoice and credit note, and plain CII XML. The server detects for itself what it receives.

The result is a readable view of the document, plus the validation: mandatory fields complete, totals add up, and for ZUGFeRD the schema as well. For UBL no schema is included in the package, so mandatory fields and calculation rules are checked there. A credit note with type code 381 goes through in the same way, referring to the original invoice. If the same document is read in a second time, the Reader reports “Already received”.

What happens to the document after that is up to your solution. The Reader files it in the inbox, validates it and provides a JSON. At that point a script takes over, in which your ERP turns it into an incoming document, an approval or a handover to another system.

It is set up like the Creator, with the address of your own server and the licence key. Two test buttons show right after installation whether the connection works.

Standard compliance

Formats and validation

The software is developed and tested against the official validation rules, the CEN-Schematron of EN 16931 and the validation rules of the XRechnung. In operation, the server checks the mandatory fields and calculates the totals.

Data storage

Where the data is stored

The PHP component runs on the customer’s server, in house or with their own hoster. No cloud, no telemetry, no activation over the network. The license key is checked on the customer’s server, without any outside connection. Invoice data does not leave the customer’s premises.

Requirements

What you need

Deadlines

When it applies

1. Since 2025, every company must be able to receive e-invoices.
2. From 1 January 2027, companies with a previous-year turnover of more than 800,000 euros must issue e-invoices.
3. From 1 January 2028, this applies to everyone.