ZUGFeRD for developers: understanding the CII format and PDF/A-3

ZUGFeRD is the hybrid e-invoice format of the Forum elektronische Rechnung Deutschland (FeRD): a PDF file for humans, with embedded XML data for machines. This article explains the format from a developer's perspective – the underlying Cross Industry Invoice (CII) XML, the profiles and the PDF/A-3 embedding.

What is ZUGFeRD?

A ZUGFeRD invoice consists of two components:

1. Visual component: a PDF/A-3 document (ISO 19005-3) that renders the invoice in a human-readable way
2. Structured data: an XML file in the UN/CEFACT CII format embedded into the PDF for machine processing

Recipients without special software simply open the PDF; systems with e-invoicing support process the XML data automatically. Important in practice: according to the German Federal Ministry of Finance's guidance on mandatory e-invoicing, the structured XML part is the authoritative part of hybrid formats – if the two diverge, the XML data takes precedence over the PDF.

ZUGFeRD is developed jointly with the French standard Factur-X; the two are technically identical. The current version is ZUGFeRD 2.5 (corresponding to Factur-X 1.09), published in June 2026 and fully backwards compatible. This version is based on UN/CEFACT CII D22B and remains compatible with the previous D16B baseline.

Legal framework

Since 2025-01-01, e-invoicing under § 14 UStG has been the standard for transactions between domestic German businesses: every business must be able to receive e-invoices, while transition periods under § 27(38) UStG apply to issuing them (with the recipient's consent until the end of 2026, or until the end of 2027 for businesses with a previous-year turnover of up to €800,000). The Federal Ministry of Finance guidance of 2024-10-15 (amended on 2025-10-15) recognizes ZUGFeRD from version 2.0.1 as a permissible format – except for the MINIMUM and BASIC WL profiles.

ZUGFeRD vs. XRechnung

If you master the CII format, you can therefore create both ZUGFeRD invoices and XRechnung invoices in the CII syntax.

The ZUGFeRD profiles

ZUGFeRD defines five profiles with different levels of detail, plus a reference profile:

• MINIMUM: only basic header data, without a VAT breakdown. In Germany not a complete invoice, only a bookkeeping aid.
• BASIC WL ("without lines"): header data without invoice lines. Also not a complete invoice.
• BASIC: basic data including lines; recognized as a complete invoice.
• EN 16931 (COMFORT): maps the complete semantic data model of EN 16931. The right choice for most use cases.
• EXTENDED: an extension beyond EN 16931 for complex industry requirements.
• XRECHNUNG (reference profile): additionally satisfies the German XRechnung business rules; included since ZUGFeRD 2.1.1 in coordination with KoSIT.

The CII format: namespaces

CII uses four central XML namespaces:

<?xml version="1.0" encoding="UTF-8"?>
<rsm:CrossIndustryInvoice
    xmlns:rsm="urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100"
    xmlns:ram="urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100"
    xmlns:qdt="urn:un:unece:uncefact:data:standard:QualifiedDataType:100"
    xmlns:udt="urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100">
    <!-- Invoice content -->
</rsm:CrossIndustryInvoice>

• rsm: the root element and main structure
• ram: reusable business entities (parties, addresses, lines)
• qdt / udt: qualified and unqualified data types (dates, amounts, codes)

While UBL uses the prefixes cac:/cbc:, CII documents are immediately recognizable by rsm: and ram:.

Anatomy of a CII invoice

A CII invoice is organized into three main areas:

1. ExchangedDocumentContext: the context, in particular the profile
2. ExchangedDocument: document metadata
3. SupplyChainTradeTransaction: the business transaction with all details

1. The document context (ExchangedDocumentContext)

<rsm:ExchangedDocumentContext>
    <ram:GuidelineSpecifiedDocumentContextParameter>
        <ram:ID>urn:cen.eu:en16931:2017</ram:ID>
    </ram:GuidelineSpecifiedDocumentContextParameter>
</rsm:ExchangedDocumentContext>

The GuidelineSpecifiedDocumentContextParameter/ID is the most important identifier: it states the profile in use.

2. The document (ExchangedDocument)

<rsm:ExchangedDocument>
    <ram:ID>RE-2026-001</ram:ID>
    <ram:TypeCode>380</ram:TypeCode>
    <ram:IssueDateTime>
        <udt:DateTimeString format="102">20260615</udt:DateTimeString>
    </ram:IssueDateTime>
</rsm:ExchangedDocument>

• ID (BT-1): the invoice number
• TypeCode (BT-3): the document type according to UNTDID 1001 – "380" for a commercial invoice, "381" for a credit note
• IssueDateTime: the invoice date; format="102" means YYYYMMDD

3. The business transaction (SupplyChainTradeTransaction)

3.1 Invoice lines (IncludedSupplyChainTradeLineItem)

<ram:IncludedSupplyChainTradeLineItem>
    <ram:AssociatedDocumentLineDocument>
        <ram:LineID>1</ram:LineID>
    </ram:AssociatedDocumentLineDocument>
    <ram:SpecifiedTradeProduct>
        <ram:Name>IT-Beratung</ram:Name>
    </ram:SpecifiedTradeProduct>
    <ram:SpecifiedLineTradeAgreement>
        <ram:NetPriceProductTradePrice>
            <ram:ChargeAmount>120.00</ram:ChargeAmount>
        </ram:NetPriceProductTradePrice>
    </ram:SpecifiedLineTradeAgreement>
    <ram:SpecifiedLineTradeDelivery>
        <ram:BilledQuantity unitCode="HUR">8</ram:BilledQuantity>
    </ram:SpecifiedLineTradeDelivery>
    <ram:SpecifiedLineTradeSettlement>
        <ram:ApplicableTradeTax>
            <ram:TypeCode>VAT</ram:TypeCode>
            <ram:CategoryCode>S</ram:CategoryCode>
            <ram:RateApplicablePercent>19</ram:RateApplicablePercent>
        </ram:ApplicableTradeTax>
        <ram:SpecifiedTradeSettlementLineMonetarySummation>
            <ram:LineTotalAmount>960.00</ram:LineTotalAmount>
        </ram:SpecifiedTradeSettlementLineMonetarySummation>
    </ram:SpecifiedLineTradeSettlement>
</ram:IncludedSupplyChainTradeLineItem>

• BilledQuantity with a unitCode according to UN/ECE Rec. N°20/N°21
• ApplicableTradeTax with the tax category according to UNTDID 5305 and the tax rate
• LineTotalAmount: the net amount of the line (quantity × unit price)

3.2 Trade agreement (ApplicableHeaderTradeAgreement)

Contains the seller, the buyer and the buyer reference (BT-10, the Leitweg-ID when invoicing German authorities):

<ram:ApplicableHeaderTradeAgreement>
    <ram:BuyerReference>PROJEKT-2026-ZF</ram:BuyerReference>
    <ram:SellerTradeParty>
        <ram:Name>Muster Software GmbH</ram:Name>
        <ram:PostalTradeAddress>
            <ram:PostcodeCode>10115</ram:PostcodeCode>
            <ram:LineOne>Musterstraße 42</ram:LineOne>
            <ram:CityName>Berlin</ram:CityName>
            <ram:CountryID>DE</ram:CountryID>
        </ram:PostalTradeAddress>
        <ram:SpecifiedTaxRegistration>
            <ram:ID schemeID="VA">DE123456789</ram:ID>
        </ram:SpecifiedTaxRegistration>
    </ram:SellerTradeParty>
    <ram:BuyerTradeParty>
        <ram:Name>Kunde GmbH</ram:Name>
        <ram:PostalTradeAddress>
            <ram:PostcodeCode>80331</ram:PostcodeCode>
            <ram:LineOne>Kundenweg 1</ram:LineOne>
            <ram:CityName>München</ram:CityName>
            <ram:CountryID>DE</ram:CountryID>
        </ram:PostalTradeAddress>
    </ram:BuyerTradeParty>
</ram:ApplicableHeaderTradeAgreement>

The VAT identification number is given in SpecifiedTaxRegistration with schemeID="VA".

3.3 Delivery information (ApplicableHeaderTradeDelivery)

<ram:ApplicableHeaderTradeDelivery>
    <ram:ActualDeliverySupplyChainEvent>
        <ram:OccurrenceDateTime>
            <udt:DateTimeString format="102">20260601</udt:DateTimeString>
        </ram:OccurrenceDateTime>
    </ram:ActualDeliverySupplyChainEvent>
</ram:ApplicableHeaderTradeDelivery>

3.4 Settlement information (ApplicableHeaderTradeSettlement)

<ram:ApplicableHeaderTradeSettlement>
    <ram:InvoiceCurrencyCode>EUR</ram:InvoiceCurrencyCode>
    <ram:SpecifiedTradeSettlementPaymentMeans>
        <ram:TypeCode>58</ram:TypeCode>
        <ram:PayeePartyCreditorFinancialAccount>
            <ram:IBANID>DE12345678901234567890</ram:IBANID>
        </ram:PayeePartyCreditorFinancialAccount>
    </ram:SpecifiedTradeSettlementPaymentMeans>
    <ram:ApplicableTradeTax>
        <ram:CalculatedAmount>182.40</ram:CalculatedAmount>
        <ram:TypeCode>VAT</ram:TypeCode>
        <ram:BasisAmount>960.00</ram:BasisAmount>
        <ram:CategoryCode>S</ram:CategoryCode>
        <ram:RateApplicablePercent>19</ram:RateApplicablePercent>
    </ram:ApplicableTradeTax>
    <ram:SpecifiedTradePaymentTerms>
        <ram:DueDateDateTime>
            <udt:DateTimeString format="102">20260715</udt:DateTimeString>
        </ram:DueDateDateTime>
    </ram:SpecifiedTradePaymentTerms>
    <ram:SpecifiedTradeSettlementHeaderMonetarySummation>
        <ram:LineTotalAmount>960.00</ram:LineTotalAmount>
        <ram:TaxBasisTotalAmount>960.00</ram:TaxBasisTotalAmount>
        <ram:TaxTotalAmount currencyID="EUR">182.40</ram:TaxTotalAmount>
        <ram:GrandTotalAmount>1142.40</ram:GrandTotalAmount>
        <ram:DuePayableAmount>1142.40</ram:DuePayableAmount>
    </ram:SpecifiedTradeSettlementHeaderMonetarySummation>
</ram:ApplicableHeaderTradeSettlement>

• SpecifiedTradeSettlementPaymentMeans/TypeCode (BT-81): the payment means according to UNTDID 4461 – "58" is the SEPA credit transfer, "30" the generic credit transfer
• ApplicableTradeTax: the tax breakdown per tax rate
• SpecifiedTradeSettlementHeaderMonetarySummation: the document totals; they must add up exactly to the lines

PDF/A-3: the carrier format

PDF/A-3 (ISO 19005-3) is the archival standard for PDF that – unlike PDF/A-1 and PDF/A-2 – permits embedding arbitrary files. This is exactly what ZUGFeRD uses: the CII XML file is embedded into the PDF as an attachment (named factur-x.xml in ZUGFeRD 2.x, or xrechnung.xml in the XRECHNUNG profile).

A compliant PDF/A document must, among other things, satisfy these requirements:

• All fonts must be embedded
• No encryption, no active content such as JavaScript
• Metadata must be present as XMP; FeRD provides an XMP extension schema for the ZUGFeRD-specific metadata (including the profile and the file name of the XML)

In practice, correct embedding including the XMP metadata is the most common source of errors in home-grown implementations – PDF libraries do not produce a valid PDF/A-3 without extra effort.

Validation

Both the XML and the PDF container should be checked before productive use:

• FeRD's ZUGFeRD 2.5 package contains XSD schemas and Schematron rules for all profiles.
• The KoSIT validator checks the XML data (UBL and CII) for EN 16931 and XRechnung conformance.
• The open-source project Mustang validates ZUGFeRD files including the PDF part.

The checks cover schema conformance, the EN 16931 business rules (especially the totals), PDF/A-3 conformance and correct embedding.

The easier way: creating ZUGFeRD invoices via API

If you don't want to generate CII XML and embed it into PDF/A-3 in a standards-compliant way yourself, you can leave both to an API: RechnungsAPI turns a JSON request into a finished, validated ZUGFeRD invoice including the PDF. Our tutorial on creating ZUGFeRD invoices via API shows how.

Sources

• FeRD: The ZUGFeRD standard and FAQ
• FeRD: ZUGFeRD 2.5 release
• Federal Ministry of Finance guidance of 2025-10-15 on mandatory e-invoicing
• § 14 UStG and § 27 UStG
• KoSIT validator on GitHub