ZUGFeRD - Tutorial

Last Update: 16.05.2025

Einleitung


Der nachfolgende Guide soll Sie beim Empfangen und Erstellen von ZUGFeRD-Nachrichten unterstützen. Er bildet die gängigsten Fragen und Stolperfallen ab, die bei der Arbeit mit ZUGFeRD aufkommen können. Sollten Sie trotz unseres Guides offene Fragen haben, zögern Sie nicht, ein Ticket unter support@lobster.de zu öffnen.

Nun aber viel Spaß mit unserem ZUGFeRD Guide!

Siehe auch


Abschnitt PDF - Übersicht.

Was ist ZUGFeRD?

ZUGFeRD ist ein branchenübergreifendes Datenformat für den elektronischen Rechnungsdatenaustausch, das vom Forum elektronische Rechnung Deutschland (FeRD) – mit Unterstützung des Bundesministeriums für Wirtschaft und Energie – erarbeitet wurde.

Das ZUGFeRD-Datenformat basiert auf der Richtlinie 2014/55/EU vom 16. April 2014 über die elektronische Rechnungsstellung bei öffentlichen Aufträgen und auf der am 28. Juni 2017 veröffentlichten Norm EN16931.

Zudem werden die Cross-Industry-Invoice (CII) von UN/CEFACT und die ISO-Norm 19005-3:2012 (PDF/A-3) ab ZUGFeRD 2.0 berücksichtigt.

Die Einsatzgebiete dieses hybriden Rechnungsformats sind vielfältig. Sowohl im B2B-, im B2G- und im B2C-Geschäftsverkehr kann ZUGFeRD eingesetzt werden.

Inhaltliche Identität


Als hybrides Datenformat integriert ZUGFeRD in einem PDF-Dokument (PDF/A-3) strukturierte Rechnungsdaten im XML-Format.

Das heißt, der Rechnungsversand erfolgt grundsätzlich in Form eines PDF-Dokuments, welches die Sichtkomponente der Rechnung darstellt.
Gleichzeitig wird ein inhaltlich identisches Mehrstück derselben Rechnung (XML) innerhalb des PDF mit versandt, so dass die elektronische Verarbeitung der Rechnung über die strukturierten Rechnungsdaten - nach Implementierung in das unternehmensspezifische Softwaresystem - problemlos möglich ist.

PDF und XML müssen die Vorgaben des § 14 Abs. 4 Umsatzsteuergesetz ( UStG ) berücksichtigen, um inhaltlich identische Mehrstücke derselben Rechnung darzustellen.

Da die Finanzverwaltung keine konkreten Prüfpflichten bzw. Kontrollmaßnahmen für dieses Verfahren festgelegt hat, ist dem Rechnungssender und dem Rechnungssteller zu empfehlen, eigene Prüfmechanismen zur Sicherstellung der inhaltlichen Identität der beiden Rechnungen einzuführen.

Neben den gesetzlichen Regelungen sind auch die Grundsätze zur ordnungsgemäßen Führung und Aufbewahrung von Büchern, Aufzeichnungen und Unterlagen in elektronischer Form sowie zum Datenzugriff ( GoBD ), zuletzt vom 28. November 2019, zu beachten. (Quelle https://www.ferd-net.de/standards/zugferd)


Kurzgesagt handelt es sich um ein PDF, welches ein XML enthält, dass z.B. mit dem Acrobat Reader von Adobe angesehen und von Lobster Integration ausgelesen werden kann.


images/download/attachments/177913855/ZUGFeRD_de-version-1-modificationdate-1727265111751-api-v2.png

ZUGFeRD-Verarbeitung in den verschiedenen Phasen

Basis-Daten: Preparser


Hier können Sie in der Vorverarbeitung den Preparser ZUGFeRD nutzen, indem Sie in den Basis-Daten unter Erweiterungen → Vorbearbeitung den genannten Preparser auswählen.

Dieser extrahiert ohne weitere Konfiguration das inbegriffene XML mit dem Namen ZUGFeRD-invoice.xml, zugferd-invoice.xml, factur-x.xml und xrechnung.xml.

Hier gehts zu Dokumentation: ZUGFeRD (Preparser)

Dieses XML wird dem Profil dann als Eingangsdatei zur Verfügung gestellt.

Phase 3: Strukturen erstellen und Mapping


In der Phase 3 wird der Grundstein für die ZUGFeRD XML-Nachricht gelegt. Hier wird die Struktur für das gewünschte Konformitätslevel inklusive der nötigen Namespaces erstellt.

Die Struktur wird bei ZUGFeRD aus mehreren XSDs erzeugt. Wichtig dabei ist, dass Sie immer die Struktur für die geforderte ZUGFeRD Version und Konformitätsstufe verwenden.

Alle verfügbaren ZUGFeRD Informationen inklusive aller XSDs für die aktuelle ZUGFeRD Version 2.3 (Stand September 24) sind hier verfügbar: https://www.ferd-net.de/ueber-uns/ressourcen-1/veroeffentlichungen

Natürlich erstellen Sie auch hier auf den gleichen Weg die Quellstruktur.

Praxisbeispiel - XML Vorlagen verwenden (empfohlen)


Diese Vorlagen beinhalten die vollständigen Strukturen gemäß der gewählten Konformität basierend auf ZUGFeRD 2.3.2 (Stand Dezember 24).

Ebenfalls inkludiert sind Namespaces. Somit muss nach dem Import der Vorlage im Ziel nur noch das Mapping durchgeführt werden.

Um eine XML-Strukturvorlage zu verwenden, klicken Sie auf der Zielseite auf Menü → Vorlage laden → XML. Es öffnet sich ein neues Fenster, in welchem Sie dann den gewünschten ZUGFeRD Typen wählen können.

images/download/attachments/177913855/xml-template-de-en-version-1-modificationdate-1747395559180-api-v2.png


Wählen Sie die gewünschte Vorlage aus. Es wird nun der vollständige Baum erstellt und die Namespaces werden angelegt. Weiter geht es dann mit dem Mapping.

Auf der Quellseite können Sie die Strukturen ebenfalls über das Menü laden. Die Dokumentart in den Basis Daten muss auf XML gestellt sein. Der Pfad dorthin ist der gleiche (Menü Vorlage ladenXML).

Damit die Quellstruktur korrekt verwendet werden kann, muss noch die Satzarterkennung erstellt werden. Lobster Integration kann diese bei XML-Strukturen automatisch erstellen.

Voraussetzung dafür ist, dass in der Phase 2 Namespaces ignorieren aktiviert ist und bei XML-Tag für Datenblatt der Root-Name des XML, also CrossIndustryInvoice eingetragen ist.


images/download/thumbnails/177913855/phase_2_de-version-1-modificationdate-1747395559646-api-v2.png


Ist das erledigt öffnen Sie das Menü auf der Quellseite und wählen Sie Satzarterkennungen neu erstellen aus. Daraufhin sollte ein Fenster erscheinen, welches die Aktion bestätigt und angibt, wo welche Satzart erstellt wurde.


images/download/attachments/177913855/create_new_matchcodes_de-version-1-modificationdate-1747395559675-api-v2.png

Praxisbeispiel - manueller Strukturimport über XSD

Laden Sie sich das Paket für Version 2.3 herunter und suchen Sie sich dafür das entsprechende Schema heraus. Die Schemata sind jeweils abwärtskompatibel.

Für den Fall ZUGFeRD 2.1 EXTENDED verwenden Sie ZUGFeRD 2.3 EXTENDED. Das Schema besteht aus 4 XSDs:

  1. Factur-X_1.0.07_EXTENDED.xsd (Haupt-XSD)

  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


Die Haupt XSD verweist auf die Unter-XSDs. Legen Sie die 3 Unter-XSDs in das Root-Verzeichnis Ihres Lobster Integration.

Erzeugen Sie nun die Zielstruktur über die Datei-Analyse im Menü der Zielstruktur (Menü → Struktur erzeugen → aus Datei-Analyse), indem Sie die Haupt-XSD auf die Analyse ziehen und XSD/DTD Schema als Art auswählen.

Als Root-Elementname geben Sie CrossIndustryInvoice an.

Hinweis: Wenn Sie den Root-Namen einer XSD nicht kennen, können Sie data in das Feld eingeben. Lobster Integration sucht dann nach dem Root-Namen. Voraussetzung ist allerdings, dass es nur einen Rootnamen in der XSD gibt.


Da die Struktur für die ZUGFeRD 2.3 Extended die maximale Ausprägung darstellt, wird der Zielbaum sehr groß werden. Lobster Integration berücksichtig bei rekursiven Strukturen, wie es die ZUGFeRD Struktur auch ist, per Default nicht alle ebenen, was dazu führt, dass Feldnamen mit dem Inhalt Skipped_to_much_content... erstellt werden.

Lobster Data Plattform bietet im XSD Parser Parameter, welche dieses Verhalten verhindern.

Diese Parameter lauten maxDuplicatedElementCount und maxRecursionDepth.

Für ZUGFeRD 2.3 EXTENDED setzen Sie maxDuplicatedElementCount auf 800 und maxRecursionDepth auf 100.


Praktischerweise wird die Dokumentart XML sowie das Root-Element in Phase 2 automatisch eingetragen, sodass Sie sich darüber keine Gedanken mehr machen müssen.

Mehr zu XML-Schemas: XML-Schemas (XSD/DTD)

Haben Sie alles richtig gemacht, wird eine Struktur erstellt und Sie können mit dem Mapping beginnen.

In dem ZUGFeRD-Paket finden Sie auch Beschreibungen, welche Ihnen helfen, die richtigen Orte für Ihre Daten zu finden.


Namespaces


ZUGFeRD XML Arbeiten mit Namespaces, welche im Root-Element mit dem Präfix xmlns und einem Suffix deklariert werden müssen, z.B. xmlns:rsm="urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100".

Namespaces werden entweder als Felder oder in der Namespaceverwaltung angelegt. Nachfolgend werden beide Herangehensweisen beschrieben. Bitte verwenden Sie nur eine davon.


Namespacefelder


Ein Feld für eine Namespacedefinition bekommt immer den Namen des Namespaces und das Suffix _nsdef.

Bleiben wir also beim Beispiel ZUGFeRD 2.3 EXTENDED. Dort werden folgenden Namespaces benötigt:

xmlns:rsm="urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100"
xmlns:qdt="urn:un:unece:uncefact:data:standard:QualifiedDataType:10"
xmlns:udt="urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100"
xmlns:ram="urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100"

Hier haben wir also vier Namespaces, die deklariert werden müssen. Legen Sie daher die Felder wie folgt unter dem Knoten CrossIndustryInvoice an und weisen Sie ihnen die URI als Fixwert zu:

images/download/thumbnails/177913855/nsdef_de-en-version-1-modificationdate-1747396069170-api-v2.png


Feldname

Fixwert

rsm_nsdef

urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100

qdt_nsdef

urn:un:unece:uncefact:data:standard:QualifiedDataType:10

udt_nsdef

urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100

ram_nsdef

urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100


Nun müssen die deklarierten Namespaces auch den Knoten und Felder bekannt gemacht werden, um den Tags das jeweilige Präfix zu geben.

Dafür steht Ihnen in den Knoten- und Feldeigenschaften das Attribut XML Namespace zur Verfügung. Tragen Sie dort den Namespace ein, welcher als Suffix für das XML-Element verwendet werden soll.


images/download/thumbnails/177913855/XML_Namespace_de-version-1-modificationdate-1727265295094-api-v2.png


Soll eine untergeordnete Struktur ebenfalls den gleichen Namespace erhalten, kann der Namespace über das Kontextmenü an die untergeordneten Knoten und Felder vererbt werden.

Öffnen Sie dafür auf dem entsprechenden Knoten das Kontextmenü durch einen Rechtsklick und wählen Sie XML Namespaces vererben aus.

Gehen Sie so durch die gesamte Struktur, um den Elementen die Namespaces, genau wie in den Beispielen aus dem Paket, zuzuordnen.


Namespaceverwaltung


Die Namespaceverwaltung erreichen Sie auf der Zielseite über Menü XML Namespaces verwalten.

Es öffnet sich ein neues Fenster, in welchem Sie dann den Namespacepräfix und die dazugehörige URI (ohne Anführungszeichen) eintragen.


images/download/attachments/177913855/namespace_administration-de-version-1-modificationdate-1747396189155-api-v2.png


Namespaces die dort angegeben werden, werden immer in das Root-Element des XML eingetragen, also genau so, wie wir es für ZUGFeRD benötigen.

Außerdem werden die Namespaces automatisch im Attribut XML Namespaces im Dropdown-Menü angezeigt und können dort dann gewählt werden.

Ändert man den Namen eines Namespaces in der Verwaltung, wird die Änderung sofort an die Struktur weitergegeben, somit muss kein Knoten oder Feld mehr angepasst werden.


images/download/attachments/177913855/xml_namespace_attribute-de-version-1-modificationdate-1747396189482-api-v2.png

Mapping


Jetzt haben wir ganz viel über XML geredet, aber Sie fragen sich bestimmt, wann die PDF-Rechnung wichtig wird. Genau jetzt.

Nachdem das Mapping steht, sollte man sich auch überlegen, wo die PDF-Rechnung herkommt.

Idealerweise hat ein vorgelagertes System diese schon erstellt und in ein Verzeichnis gelegt.

Diesen Pfad ermitteln Sie mit einer eigenen Logik und speichern diesen in eine Variable, welche wir in einer der nächsten Phasen brauchen.

Hinweis: Achten Sie darauf, dass es sich um ein Verzeichnis innerhalb von Lobster Integration handelt und nicht um ein Netzlaufwerk. Netzlaufwerke können hier zwar prinzipiell angegeben werden, allerdings können Sie nur auf Freigaben zugreifen, für welche auch der User, unter welchem Lobster Integration ausgeführt wird, berechtigt ist.


Das PDF kann auch durch Lobster Data Plattform erzeugt werden, wenn dies nicht durch ein anderes System erledigt werden kann.

Mehr Informationen dazu finden Sie hier: PDFCreator


Phase 5: Integration Unit


Es gibt zwei Wege, eine ZUGFeRD zu erstellen:


  1. Die ZUGFeRD IU.

  2. Die XMLNoTemplateUnit in Verbindung mit dem ZUGFeRD PostExecuter


Unsere Empfehlung ist der 2. Weg mit der XMLNoTemplateUnit in Verbindung mit dem ZUGFeRD PostExecuter.

Die Vorteile liegen auf der Hand:


  1. Es muss keine Vorlage erstellt werden.

  2. Alle XML-Besonderheiten (Attribute, Namespaces, Strukturen) werden in der Zielstruktur erzeugt, sind für jeden sichtbar und leicht zu debuggen.
    Siehe auch: Satzarterkennungen, eindeutige/reservierte Namen für XML.

  3. Es kann auch ohne weiteres in anderen Antwortwegen auf das XML zugegriffen werden.


Basierend auf der Empfehlung, verwenden Sie die XMLNoTemplateUnit wie gewohnt.

Je nachdem, ob Sie in anderen Antwortwegen das XML benötigen (z.B. für das Archiv) oder nicht, kann direkt unter der Integration Unit im Bereich Nachbearbeitung der Postexecuter ZUGFerdPDF verwendet werden.

In diesem Fall würde dann das Ergebnis aus der Integration Unit immer die ZUGFeRD sein und das XML wäre nur noch über diese auszulesen.

Daher empfehlen wir die Erstellung der ZUGFeRD erst im entsprechenden Antwortweg.

Phase 6: ZUGFeRD erstellen


Es kann selbstverständlich jede Art von Antwortweg verwendet werden.

Der Antwortweg (oder auch mehrere), der die ZUGFeRD als Ergebnis ausgeben soll, erhält in den Inhalts-Einstellungen dem ZUGFeRD PostExecuter.

Hier brauchen Sie nun den Pfad zur PDF-Rechnung. Dieser sollte vollständig aus einer Variablen kommen. In der Konfiguration wird auch das Konformitätslevel und die ZUGFeRD-Version erwartet. Optional können ab ZUGFeRD 2 noch weitere Anhänge in das PDF gepackt werden.

Gehen wir davon aus, dass wir den Pfad zur PDF-Rechnung in Phase 3 in die Variable var__pfad_zum_PDF geschrieben haben, wir das Konformitätslevel EXTENDED brauchen, eine ZUGFeRD Version 2 erstellen und keine weiteren Daten mit Anhängen wollen.

Die Konfiguration dazu sieht dann so aus:

@var__pfad_zum_PDF@:EXTENDED:2

Außerdem setzen Sie die Inhalts-Einstellung auf Ausgabe von IU und die Kodierung auf UTF-8.


images/download/attachments/177913855/Phase6_content_settings_de-version-1-modificationdate-1727265389903-api-v2.png


Das Ergebnis ist eine ZUGFeRD-PDF mit eingebettetem XML.

Jetzt fragen Sie sich aber vielleicht, wann welche ZUGFeRD-Version und welches Konformitätslevel benötigt wird. Gute Frage!

Diese Frage lässt sich recht einfach beantworten: Ihr Partner wird Ihnen mitteilen, welche ZUGFeRD-Version Sie ihm in welchem Level übermitteln sollen.

Was aber, wenn Ihr Partner Ihnen nur eine Beispiel-XML gesendet hat?

Auch hier gilt: Kein Problem. Die ZUGFeRD-Version lässt sich anhand des XMLs über folgende Punkte herausfinden.

  1. Der Name der XML.
    ZUGFeRD 1: ZUGFeRD-invoice.xml und zugferd-invoice.xml
    ZUGFeRD 2: factur-x.xml, xrechnung.xml

  2. Das Root-Element.
    ZUGFeRD 1: CrossIndustryDocument
    ZUGFeRD 2: CrossIndustryInvoice


Damit wissen wir jetzt die Version, aber wie steht es um das Konformitätslevel?

Das steht praktischerweise in einer validen ZUGFeRD-Nachricht in den Daten. Suchen Sie nach dem Tag <ram:ID>. Dort finden Sie einen String, welcher das konkrete Konformitätslevel enthält.


Beispiel
<ram:ID>urn:cen.eu:en16931:2017#compliant#urn:factur-x.eu:1p0:basic</ram:ID>


In diesem Beispiel sehen wir, dass es sich um das Konformitätslevel BASIC handelt.

Mit diesen Informationen kann die ZUGFeRD-Konfiguration dann in jedem Fall erfolgreich durchgeführt werden.

Phase 6: ZUGFeRD auslesen


Parallel zum ZUGFeRD PreParser, welcher eine XML aus einer ZUGFeRD ausliest, gibt es auch einen PostExecuter, der dies kann: ZUGFeRDExtractXML

Dieser kann verwendet werden, wenn in Phase 3 z.B. nur der PDF-Teil analysiert werden soll, um zu entscheiden, was mit XML und PDF geschehen soll.

Es kann dann z.B. einen Antwortweg geben, der die komplette ZUGFeRD archiviert, einen der das XML an ein Verarbeitungsprofil schickt und einen, der nur das XML archiviert.

Der PostExecuter sollte nicht in Phase 5 verwendet werden.

Besonderheiten


PDF/A-3


ZUGFeRD basiert auf dem PDF/A-3-Standard. Lobster Integration versucht beim Erstellen der Daten die verknüpfte PDF-Rechnung zu einer PDF/A-3 umzuwandeln. Damit das gelingen kann, sollte das PDF sauber erstellt worden sein.

Abweichend von der Dokumentation kann auch ein PDF-A verwendet werden, da dort die Metadaten meist schon in der richtigen Form sind.


EN16931 XRECHNUNG


ZUGFeRD 2.2 in der Konformitätsstufe XRECHNUNG wird von deutschen Behörden im Rahmen der EN16931 als Rechnungsformat für die e-Rechnung akzeptiert.

Allerdings wird hier nur der XML-Teil ohne PDF erwartet. Beachten Sie dafür aber auch die Anforderungen der jeweiligen Behörden und Partner.

Der Ablauf zur Erstellung des XML ist genau derselbe wie bei den anderen Typen, mit dem Unterschied, dass das XML am Ende nicht in ein PDF eingebettet wird.

Da die ZUGFeRD XML Vorlagen mit der Konformitätsstufe EN16931 und EXTENDED der ISO EN16931 entsprechen, können diese für Mappings verwendet werden welche das CII-Format unterstützen sollen.

Fehlerbehandlung


1. Invalides PDF/A3 oder XML

Wenn ein Validator das XML oder das PDF moniert, gilt es, verschiedenes zu prüfen.

Wird das XML moniert, prüfen Sie, ob die Strukturen korrekt sind, alle Namespaces richtig deklariert und zugeordnet sind und dass an den entsprechenden Stellen die richtigen Formate und Codes gemäß ZUGFeRD Beschreibungen vorhanden sind.

Wird das PDF selbst moniert, muss an der Stelle geprüft werden, an der das PDF erstellt wird. Lobster Integration konnte dann aus dem vorliegenden PDF keine valide PDF/A-3 erstellen.

Gründe dafür können schon vorab defekte PDF-Metadaten sein. Dies kann z.B. passieren, wenn mehrere unterschiedliche Programme an der Erstellung des PDFs beteiligt waren.

Wir arbeiten daran, dass diese externen Einflüsse keine Auswirkungen mehr auf die Erstellung von validen PDF/A-3 haben.

Lassen Sie aber bei einem beanstandeten PDF Ihren Partner prüfen, ob er die ZUGFeRD annehmen würde.