Developer

ZUGFeRD XML-Struktur: Die wichtigsten Felder für Entwickler

Letzte Aktualisierung: 1. Mai 2026

Für Entwickler: ZUGFeRD nutzt die UN/CEFACT Cross Industry Invoice (CII) Syntax. Das Root-Element heißt CrossIndustryInvoice (ZUGFeRD 2.x) bzw. CrossIndustryDocument (ZUGFeRD 1.x). Namespaces und Pflichtfelder unterscheiden sich je nach Profil.

Grundstruktur: Die vier Hauptblöcke

Jede ZUGFeRD-2.x-Datei besteht aus vier hierarchischen Hauptblöcken:

<rsm:CrossIndustryInvoice>
  <rsm:ExchangedDocumentContext>   <!-- Kontext: Profil, Version -->
  <rsm:ExchangedDocument>          <!-- Dokumentkopf: Nummer, Datum, Typ -->
  <rsm:SupplyChainTradeTransaction> <!-- Hauptinhalt: Parteien, Positionen, Steuer, Beträge -->
</rsm:CrossIndustryInvoice>

Namespaces

ZUGFeRD 2.x verwendet diese Namespace-Präfixe:

Präfix	Namespace-URI	Bedeutung
`rsm:`	urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100	Root-Elemente (Dokumentstruktur)
`ram:`	urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100	Wiederverwendbare Geschäftsobjekte (Parteien, Beträge etc.)
`udt:`	urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100	Datentypen (Betrag, Datum, ID)
`qdt:`	urn:un:unece:uncefact:data:standard:QualifiedDataType:100	Qualifizierte Datentypen

ExchangedDocumentContext: Profil und Version

Hier wird das ZUGFeRD-Profil deklariert. Dieses Element muss als erstes korrekt gesetzt sein — sonst schlägt die Profilvalidierung fehl:

<rsm:ExchangedDocumentContext>
  <ram:GuidelineSpecifiedDocumentContextParameter>
    <ram:ID>urn:cen.eu:en16931:2017#compliant#urn:factur-x.eu:1p0:en16931</ram:ID>
  </ram:GuidelineSpecifiedDocumentContextParameter>
</rsm:ExchangedDocumentContext>

Die Profil-URN für jedes Profil:

Profil	URN
MINIMUM	`urn:factur-x.eu:1p0:minimum`
BASIC WL	`urn:factur-x.eu:1p0:basicwl`
BASIC	`urn:factur-x.eu:1p0:basic`
EN 16931	`urn:cen.eu:en16931:2017#compliant#urn:factur-x.eu:1p0:en16931`
EXTENDED	`urn:factur-x.eu:1p0:extended`
XRECHNUNG	`urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_2.3`

ExchangedDocument: Rechnungskopf

<rsm:ExchangedDocument>
  <ram:ID>RE-2025-042</ram:ID>                         <!-- Rechnungsnummer -->
  <ram:TypeCode>380</ram:TypeCode>                      <!-- 380=Rechnung, 381=Gutschrift -->
  <ram:IssueDateTime>
    <udt:DateTimeString format="102">20250315</udt:DateTimeString>  <!-- YYYYMMDD -->
  </ram:IssueDateTime>
</rsm:ExchangedDocument>

Wichtig: Das Datumsformat ist immer YYYYMMDD (format="102"), nicht das deutsche DD.MM.YYYY. Das ist eine häufige Fehlerquelle.

SupplyChainTradeTransaction: Der Kern der Rechnung

Dieser Block enthält drei Unterelemente:

<rsm:SupplyChainTradeTransaction>
  <ram:IncludedSupplyChainTradeLineItem> ... </ram:IncludedSupplyChainTradeLineItem>
  <!-- 0..n Positionen (bei BASIC WL und MINIMUM: keine Positionen) -->

  <ram:ApplicableHeaderTradeAgreement>   <!-- Aussteller + Empfänger -->
  <ram:ApplicableHeaderTradeDelivery>    <!-- Lieferdatum (optional) -->
  <ram:ApplicableHeaderTradeSettlement>  <!-- Steuer, Beträge, Zahlungsbedingungen -->
</rsm:SupplyChainTradeTransaction>

Aussteller und Empfänger

<ram:ApplicableHeaderTradeAgreement>
  <ram:SellerTradeParty>            <!-- Rechnungsaussteller -->
    <ram:Name>Muster GmbH</ram:Name>
    <ram:PostalTradeAddress>
      <ram:PostcodeCode>10115</ram:PostcodeCode>
      <ram:LineOne>Musterstraße 1</ram:LineOne>
      <ram:CityName>Berlin</ram:CityName>
      <ram:CountryID>DE</ram:CountryID>
    </ram:PostalTradeAddress>
    <ram:SpecifiedTaxRegistration>
      <ram:ID schemeID="VA">DE123456789</ram:ID>  <!-- USt-IdNr. -->
    </ram:SpecifiedTaxRegistration>
  </ram:SellerTradeParty>

  <ram:BuyerTradeParty>             <!-- Rechnungsempfänger -->
    <ram:Name>Kunde AG</ram:Name>
    ...
  </ram:BuyerTradeParty>
</ram:ApplicableHeaderTradeAgreement>

Gesamtbeträge und Steuer

<ram:ApplicableHeaderTradeSettlement>
  <ram:InvoiceCurrencyCode>EUR</ram:InvoiceCurrencyCode>

  <ram:ApplicableTradeTax>
    <ram:CalculatedAmount>95.00</ram:CalculatedAmount>   <!-- Steuerbetrag -->
    <ram:TypeCode>VAT</ram:TypeCode>
    <ram:BasisAmount>500.00</ram:BasisAmount>             <!-- Nettobetrag -->
    <ram:CategoryCode>S</ram:CategoryCode>               <!-- S=Standard -->
    <ram:RateApplicablePercent>19</ram:RateApplicablePercent>
  </ram:ApplicableTradeTax>

  <ram:SpecifiedTradePaymentTerms>
    <ram:DueDateDateTime>
      <udt:DateTimeString format="102">20250415</udt:DateTimeString>
    </ram:DueDateDateTime>
  </ram:SpecifiedTradePaymentTerms>

  <ram:SpecifiedTradeSettlementHeaderMonetarySummation>
    <ram:LineTotalAmount>500.00</ram:LineTotalAmount>
    <ram:TaxBasisTotalAmount>500.00</ram:TaxBasisTotalAmount>
    <ram:TaxTotalAmount currencyID="EUR">95.00</ram:TaxTotalAmount>
    <ram:GrandTotalAmount>595.00</ram:GrandTotalAmount>
    <ram:DuePayableAmount>595.00</ram:DuePayableAmount>
  </ram:SpecifiedTradeSettlementHeaderMonetarySummation>
</ram:ApplicableHeaderTradeSettlement>

Das eingebettete XML in einer PDF finden

Das XML ist als Dateianhang in der PDF/A-3-Struktur eingebettet. Der Dateiname ist bei ZUGFeRD 2.x entweder zugferd-invoice.xml oder factur-x.xml. Du kannst es mit Libraries wie PyPDF2, iText (Java) oder PDFBox extrahieren — oder direkt mit dem X-Ray-Viewer ansehen.

Weiterführend: X-Ray-Viewer — XML direkt im Browser ansehen · ZUGFeRD mit Python erzeugen