ZUGFeRD REST API: The Complete E-Invoice Toolkit for German B2B

Germany's B2B e-invoicing mandate is already in effect. Since January 2025, every German business must be able to receive structured e-invoices. From January 2027, companies with annual turnover above €800,000 must also issue them. By January 2028, the obligation extends to every VAT-registered business in Germany regardless of size. ZUGFeRD — the hybrid format that embeds machine-readable CII XML inside a PDF/A-3 document — is the format of choice for the vast majority of German B2B transactions.

If you are building accounting software, an ERP integration, a billing platform, or any product used by German businesses, ZUGFeRD support is no longer optional. It is a compliance requirement your customers are under legal obligation to meet.

InvoiceXML provides a complete ZUGFeRD API toolkit: convert any legacy invoice to ZUGFeRD, create ZUGFeRD from structured data, validate against the official FeRD Schematron, extract structured data from ZUGFeRD files, and convert between ZUGFeRD and other e-invoice formats. This post covers every tool, explains the German-specific compliance context that makes ZUGFeRD different from other formats, and addresses the practical questions German developers and ISVs face most often.

What is ZUGFeRD? The German-specific context

ZUGFeRD stands for Zentraler User Guide des Forums elektronische Rechnung Deutschland — the Central User Guide of the Forum for Electronic Invoices Germany. It was developed by FeRD (Forum elektronische Rechnung Deutschland), a consortium that includes the German federal government, DATEV, SAP, and major industry associations.

Technically, ZUGFeRD 2.x is identical to Factur-X — both formats embed CII XML inside a PDF/A-3 container. The distinction is branding and the German-specific compliance ecosystem built around it. Where Factur-X is the French-branded version, ZUGFeRD is the German one. In practice this means:

• The embedded XML file is named zugferd-invoice.xml (not factur-x.xml)
• The specification identifier uses ZUGFeRD-specific URNs
• The format is deeply integrated into the German ERP ecosystem — DATEV, SAP, Lexware, sevDesk, Sage 50, and Lexoffice all have native ZUGFeRD support
• German tax law (GoBD) has specific archiving requirements that ZUGFeRD's PDF/A-3 container satisfies
• The German BMF (Bundesministerium der Finanzen) has explicitly named ZUGFeRD as an accepted format under the 2025 B2B e-invoicing provisions

Here is what the specification identifier looks like at different ZUGFeRD versions and profiles:

<!-- ZUGFeRD 2.3.2 — EN 16931 profile (most common B2B choice) -->
<ram:GuidelineSpecifiedDocumentContextParameter>
  <ram:ID>urn:cen.eu:en16931:2017#conformant#urn:factur-x.eu:1p0:en16931</ram:ID>
</ram:GuidelineSpecifiedDocumentContextParameter>

<!-- ZUGFeRD 2.3.2 — EXTENDED profile -->
<ram:GuidelineSpecifiedDocumentContextParameter>
  <ram:ID>urn:cen.eu:en16931:2017#conformant#urn:factur-x.eu:1p0:extended</ram:ID>
</ram:GuidelineSpecifiedDocumentContextParameter>

<!-- ZUGFeRD 2.1.1 — XRechnung reference profile (B2G compatible) -->
<ram:GuidelineSpecifiedDocumentContextParameter>
  <ram:ID>urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_2.1</ram:ID>
</ram:GuidelineSpecifiedDocumentContextParameter>

<!-- ZUGFeRD 2.4 — latest release (identical to Factur-X 1.08) -->
<ram:GuidelineSpecifiedDocumentContextParameter>
  <ram:ID>urn:cen.eu:en16931:2017#conformant#urn:factur-x.eu:1p0:en16931</ram:ID>
</ram:GuidelineSpecifiedDocumentContextParameter>

One subtle but important point: from ZUGFeRD 2.1 onwards, the EN 16931 profile uses the Factur-X URN rather than a ZUGFeRD-specific one. This is intentional — it signals that ZUGFeRD 2.x and Factur-X 1.x are technically harmonised standards. Your validator needs to handle both URN families correctly to avoid false negatives.

ZUGFeRD vs XRechnung: the question every German developer faces

Every team adding German e-invoicing support to a product eventually faces this question. The answer depends on who your customers are billing:

ZUGFeRD for B2B — invoices between private-sector companies. The hybrid PDF/A-3 format is accepted by all German accounting systems, can be read by any PDF viewer without specialist software, and satisfies GoBD archiving requirements in a single file. No Leitweg-ID required. Appropriate for the vast majority of German B2B invoices.

XRechnung for B2G — invoices to German federal authorities, state governments, and public sector entities. Pure XML, no PDF wrapper. Requires a Leitweg-ID (the routing identifier assigned by the public sector buyer). Submitted via the PEPPOL network or directly to OZG-RE / ZRE portals. Not human-readable without a viewer tool.

Both — if your customers invoice both private companies and government entities, you need both. ZUGFeRD 2.1+ introduced a dedicated XRechnung reference profile (xrechnung_2.x) that makes the CII XML inside a ZUGFeRD file simultaneously compliant with XRechnung rules — but this only covers the XML data layer. For B2G submission you still typically need to extract the XML and submit it as standalone XRechnung via the appropriate portal.

InvoiceXML supports both. See our XRechnung API post for the B2G-specific toolkit.

The ZUGFeRD version landscape: what your platform needs to handle

Unlike UBL — which has been stable at version 2.1 since 2013 — ZUGFeRD has evolved significantly and German businesses have files from multiple versions in their archives and incoming invoice flows:

The version detection problem is real and frequent. A business receiving invoices via email from German suppliers in 2025 will encounter ZUGFeRD 1.0 files from 2018, ZUGFeRD 2.1.1 from 2021, and ZUGFeRD 2.3.2 from 2024 in the same inbox. Each version has different root elements, different namespace structures, and different validation rule sets. Your extraction and validation layer must handle all of them.

InvoiceXML detects the version automatically from the embedded XML and applies the appropriate validation. You do not pass a version to the validation endpoint — the API reads it from the document and routes accordingly.

The GoBD dimension: why archiving matters in Germany

GoBD (Grundsätze zur ordnungsmäßigen Führung und Aufbewahrung von Büchern, Aufzeichnungen und Unterlagen in elektronischer Form) is the German regulation governing digital bookkeeping and document archiving. For e-invoices, GoBD requires:

• Immutability: The invoice document must not be modifiable after archiving. PDF/A-3 satisfies this because it is an ISO archival standard that prohibits certain dynamic elements.
• Readability throughout the retention period: The format must remain readable for the 10-year statutory retention period. PDF/A-3 with embedded fonts and ICC profiles is explicitly designed for long-term readability.
• Verifiability: It must be possible to verify that the document has not been tampered with. The XML layer inside a ZUGFeRD file serves as a machine-verifiable record of the invoice data.
• Completeness: The invoice record must contain all relevant data. A ZUGFeRD file with a validated XML attachment satisfies this better than a standalone PDF because the structured data is machine-verifiable.

This is why ZUGFeRD — rather than plain CII XML — dominates German B2B invoicing. Pure XML satisfies the machine-readability requirement but fails on long-term human readability without specialist software. A plain PDF satisfies human readability but provides no machine-verifiable structured data layer. ZUGFeRD satisfies both simultaneously in a single file, making GoBD compliance straightforward.

For developers building document management or ERP systems for German customers: the ZUGFeRD PDF/A-3 file is the GoBD-compliant archival unit. It should be stored in its entirety, not split into a PDF and an XML.

The InvoiceXML ZUGFeRD API toolkit

All endpoints share the same base URL and authentication pattern:

Base URL: https://api.invoicexml.com
Authentication: Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data

Tool 1: Convert any invoice to ZUGFeRD

What it does: Accepts any invoice document — PDF, scanned image, DOCX, XLSX — and returns a ZUGFeRD-compliant PDF/A-3b with an embedded zugferd-invoice.xml attachment. The AI pipeline handles OCR (for scanned documents), semantic field extraction, EN 16931 data mapping, Schematron validation, PDF/A-3b conversion, XMP metadata injection, and XML embedding — all in a single API call.

The output is accepted by DATEV, SAP Business One, Lexware, sevDesk, Sage 50, Lexoffice, and every other German accounting system with ZUGFeRD support, because it conforms to the FeRD specification at the byte level — not just structurally but including the embedded file naming, attachment relationship declaration, and XMP metadata block that these systems check.

When to use it: Your customers send PDF invoices and need ZUGFeRD output for their German trading partners. You are building a billing or accounting feature for German businesses. Your ERP generates legacy PDF invoices and you want to add ZUGFeRD compliance without replacing your document generation pipeline. You receive invoices from suppliers who cannot yet generate ZUGFeRD natively and need to batch-convert them on ingestion.

curl -X POST https://api.invoicexml.com/v1/transform/to/zugferd \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "profile=en16931" \
  -F "version=2.3.2"

Setting embed=false returns the standalone CII XML without a PDF wrapper — useful when you want to extract the structured data layer only, for example to feed into a downstream system that accepts raw CII rather than the full hybrid file.

Profile selection guide for German B2B:

• en16931 — Recommended default for most B2B invoices. Full EN 16931 data model, accepted by all German accounting systems.
• extended — Use when your invoice data contains fields beyond the EN 16931 scope (industry-specific identifiers, additional reference documents, custom line item attributes).
• minimum — For B2B contexts where the receiver only needs header-level payment data and handles line item matching internally (e.g. against a purchase order).
• basicwl — Header level only, no line items. Used when transmitting invoices to systems that handle AP matching automatically.

Tool 2: Create ZUGFeRD from JSON data

What it does: Accepts structured invoice data as form fields and generates a complete ZUGFeRD PDF/A-3b file from scratch. Both the visual PDF layer and the embedded XML are generated by the API — you supply the invoice data, the API handles the rest.

When to use it: You are building an invoicing feature for German businesses and want to offer native ZUGFeRD output. You have invoice data in a database and need to produce GoBD-compliant ZUGFeRD files for archiving and transmission. You want to add ZUGFeRD to your product without maintaining a CII XML generator alongside a PDF template engine and a PDF/A-3 conversion pipeline.

curl -X POST https://api.invoicexml.com/v1/create/zugferd \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "InvoiceNumber=RE-2025-0847" \
  -F "IssueDate=2025-06-01" \
  -F "PaymentDueDate=2025-07-01" \
  -F "SellerName=Müller Software GmbH" \
  -F "SellerTaxId=DE289736534" \
  -F "SellerStreet=Berliner Allee 42" \
  -F "SellerPostcode=40212" \
  -F "SellerCity=Düsseldorf" \
  -F "SellerCountry=DE" \
  -F "BuyerName=Schmidt Logistik AG" \
  -F "BuyerTaxId=DE198273645" \
  -F "BuyerStreet=Hansaallee 17" \
  -F "BuyerPostcode=40549" \
  -F "BuyerCity=Düsseldorf" \
  -F "BuyerCountry=DE" \
  -F "Currency=EUR" \
  -F "TaxBasisTotal=4200.00" \
  -F "TaxTotalAmount=798.00" \
  -F "GrandTotalAmount=4998.00" \
  -F "PaymentMeansCode=58" \
  -F "IBAN=DE89370400440532013000" \
  -F "BIC=COBADEFFXXX" \
  -F "Lines[0][description]=Softwareentwicklung – Sprint 12" \
  -F "Lines[0][quantity]=42" \
  -F "Lines[0][unitPrice]=100.00" \
  -F "Lines[0][lineTotal]=4200.00" \
  -F "Lines[0][unitCode]=HUR" \
  -F "Lines[0][taxPercentage]=19" \
  -F "Lines[0][taxCategoryCode]=S"

Note PaymentMeansCode=58 — SEPA credit transfer, the standard German B2B payment method. Code 30 is generic credit transfer; 58 is SEPA-specific. German accounting systems distinguish between these codes when importing ZUGFeRD invoices into payment runs. Using 58 with a valid IBAN and BIC ensures the invoice imports cleanly into DATEV and SAP without manual payment method correction.

The TaxBreakdown array supports multiple VAT categories in a single invoice — standard rate (19%), reduced rate (7%), zero-rated, and reverse charge. Each breakdown item maps to a separate ApplicableTradeTax element in the CII output, which is what German ERP systems use to split invoices across different tax accounts in the general ledger automatically.

Tool 3: Validate ZUGFeRD

What it does: Accepts a ZUGFeRD PDF of any version (1.0 through 2.4) and runs a complete validation pipeline: extracts the embedded XML, detects the version and profile automatically, validates against the CII D16B XSD schema, validates against the EN 16931 Schematron business rules, and checks the PDF container for PDF/A-3b conformance.

The version auto-detection matters here more than anywhere else. A ZUGFeRD 1.0 file uses CrossIndustryDocument as its root element, a completely different namespace structure, and different validation rules than ZUGFeRD 2.x. A validator that only handles 2.x will either reject or silently mishandle 1.0 files. InvoiceXML detects the version from the embedded XML and routes to the correct validation pipeline — no version parameter required.

When to use it: Before sending a ZUGFeRD invoice to a German trading partner or accounting system. When building a ZUGFeRD generation pipeline and need to verify output during development. When ingesting ZUGFeRD invoices from suppliers and wanting to screen for non-compliant files before they cause ERP import errors. When migrating an archive of legacy ZUGFeRD 1.0 files and need to assess their current compliance status.

curl -X POST https://api.invoicexml.com/v1/validate/zugferd \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]"

The response includes the detected version and profile alongside the validation result:

{
  "valid": true,
  "detectedVersion": "2.3.2",
  "profile": "urn:cen.eu:en16931:2017#conformant#urn:factur-x.eu:1p0:en16931",
  "errorCount": 0,
  "warningCount": 0,
  "errors": [],
  "warnings": []
}

For a file with violations:

{
  "valid": false,
  "detectedVersion": "2.3.2",
  "profile": "urn:cen.eu:en16931:2017#conformant#urn:factur-x.eu:1p0:en16931",
  "errorCount": 1,
  "errors": [
    {
      "rule": "BR-DE-1",
      "message": "A Payment account identifier (BT-84) must be provided if the payment means code (BT-81) is 30 or 58.",
      "source": "schematron",
      "severity": "error",
      "layer": "en16931",
      "context": "/rsm:CrossIndustryInvoice/.../ram:SpecifiedTradeSettlementPaymentMeans"
    }
  ]
}

BR-DE-1 is a German-specific business rule — one of several national extensions that apply when a ZUGFeRD invoice declares German parties. These rules are enforced by German ERP systems on import and are a common source of rejection for teams who only test against the base EN 16931 Schematron without the German national extensions.

Add ?errors=friendly to the request URL to receive plain-language error descriptions alongside the technical rule codes — useful for surfacing validation results in dashboards, no-code workflows, or customer-facing error messages.

Tool 4: Extract structured data from ZUGFeRD

What it does: Accepts a ZUGFeRD PDF and extracts the embedded CII XML, or returns the invoice data as structured JSON. For ZUGFeRD 1.0 files, the extraction normalises the legacy CrossIndustryDocument structure to the current EN 16931 data model, so downstream processing does not need version-specific code paths.

The legacy ZUGFeRD 1.0 challenge: Millions of ZUGFeRD 1.0 invoices are sitting in German company archives generated between 2014 and 2018. Their root element is rsm:CrossIndustryDocument (not rsm:CrossIndustryInvoice), the namespace URIs are different, and the element hierarchy does not map one-to-one to the 2.x/EN 16931 structure. Any system that needs to process these files alongside modern ZUGFeRD 2.x files needs version-aware extraction logic. InvoiceXML normalises both to the same JSON output schema regardless of source version.

When to use it: You receive ZUGFeRD invoices from German suppliers via email or PEPPOL and need to import the structured data into your ERP or accounting system. You are building an AP automation workflow. You need to migrate a legacy ZUGFeRD 1.0 archive to the current standard. You want to verify that the XML data layer of a ZUGFeRD invoice matches the visual PDF layer.

# Extract as CII XML
curl -X POST https://api.invoicexml.com/v1/extract/xml \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  --output invoice-cii.xml

# Extract as structured JSON
curl -X POST https://api.invoicexml.com/v1/extract/json \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]"

The JSON extraction endpoint runs a full validation pipeline on the extracted data before returning it: arithmetic verification (line totals, VAT totals, grand total), German VAT number format validation (DE prefix, 9 digits), IBAN format check, and address consistency. Each field carries a confidence score — values extracted directly from the embedded XML score 1.0; values that required AI inference from the PDF visual layer carry lower scores, flagging fields that may benefit from human review before ERP import.

Tool 5: Convert ZUGFeRD to other formats

What it does: Enables interoperability between ZUGFeRD and other European e-invoice standards, covering two key workflows: extracting the CII XML from a ZUGFeRD file and converting it to UBL for Peppol submission, and converting incoming Peppol UBL invoices to ZUGFeRD for GoBD-compliant archiving.

The German cross-border workflow problem:

A medium-sized German manufacturer invoices both domestic German customers (who expect ZUGFeRD) and customers in Belgium, Netherlands, and Norway (who receive invoices via Peppol in UBL). Maintaining two separate invoice generation pipelines — one producing ZUGFeRD PDF/A-3b, one producing Peppol UBL — doubles the compliance maintenance burden. Every time EN 16931 updates, both pipelines need updating and testing.

The efficient architecture is to generate ZUGFeRD as the canonical output format for all invoices (it contains the richest data layer and satisfies GoBD), then convert on demand to Peppol UBL for cross-border Peppol submissions. The CII XML inside a ZUGFeRD file maps cleanly to UBL 2.1 — no data is lost in the conversion.

# Step 1: Extract CII from ZUGFeRD
curl -X POST https://api.invoicexml.com/v1/extract/xml \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  --output extracted-cii.xml

# Step 2: Convert CII to Peppol-ready UBL
curl -X POST https://api.invoicexml.com/v1/convert/cii/to/ubl \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  --output invoice-ubl.xml

Conversely, a German company receiving Peppol UBL invoices from Dutch or Belgian suppliers:

# Convert incoming Peppol UBL to CII
curl -X POST https://api.invoicexml.com/v1/convert/ubl/to/cii \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  --output invoice-cii.xml

# Then embed in ZUGFeRD PDF/A-3 for GoBD-compliant archiving
# (pass invoice-cii.xml to /v1/create/zugferd with your PDF visual layer)

German ERP ecosystem compatibility: what "accepted by DATEV" actually means

Being "ZUGFeRD compliant" at the schema level is necessary but not sufficient for acceptance by German accounting systems. DATEV, SAP Business One, Lexware, and similar products perform their own import checks beyond EN 16931 Schematron validation. Common points of failure:

The embedded file must be named exactly zugferd-invoice.xml. Not invoice.xml, not ZUGFeRD.xml, not structured-data.xml. DATEV and SAP check the attachment filename as part of their import logic. Files with non-standard names are either rejected or imported as plain PDFs without extracting the XML data.

The AFRelationship value must be Alternative. This is an embedded file attribute in the PDF structure that tells the reading application the XML is an alternative representation of the PDF content. Some PDF generation libraries either omit this attribute or set it to Data or Supplement, which causes DATEV to ignore the attachment.

The XMP metadata namespace must be present. DATEV reads the ZUGFeRD XMP extension block to determine the version and profile before attempting to extract the XML. Missing XMP metadata results in the file being treated as a plain PDF.

German-specific BR-DE-x rules must pass. The German national extensions to EN 16931 include rules like BR-DE-1 (payment IBAN required when payment means is 30/58), BR-DE-15 (seller's VAT ID or tax number required), and BR-DE-17 (buyer reference required for XRechnung reference profile). These rules are checked by DATEV and SAP on import.

InvoiceXML handles all of these correctly. The embedded filename, AFRelationship, XMP metadata, and German national rule validation are all part of the standard output pipeline — not optional add-ons.

Why managing ZUGFeRD yourself is harder than it looks

The unique difficulty of ZUGFeRD compared to pure XML formats like XRechnung or CII is that it requires two entirely independent technical capabilities working correctly in combination:

XML compliance — generating valid CII XML, running EN 16931 Schematron validation, handling German national extensions. This is achievable with open-source libraries and the official FeRD validation artefacts.

PDF/A-3b generation — converting or creating PDF/A-3b files with correct ICC colour profiles, embedded fonts, XMP metadata, and properly declared attachments. This requires a different and separate technical stack. iText, Apache PDFBox, and similar libraries can do it, but the interaction between their PDF/A-3 compliance logic and the ZUGFeRD-specific metadata requirements is not straightforward.

Getting both right in the same codebase, maintaining both as standards evolve, and ensuring the interaction between them remains correct across library updates is the ongoing operational cost that most teams underestimate when deciding to build this themselves.

When FeRD publishes ZUGFeRD 2.4 and changes which fields are mandatory, your XML generation layer needs to change. If that change requires updating the validation Schematron, that needs to change too. And if the updated Schematron changes how the embedded XML is structured in ways that affect the PDF/A-3 metadata declaration, that needs to change as well. These updates compound. InvoiceXML handles all of them as a service — you receive the update transparently as part of the API.

Additionally: the financial documents your API processes contain sensitive business data — German Steuernummern, IBANs, business relationships, payment amounts. Every self-hosted processing service is a GDPR compliance commitment. Our architecture is stateless by design: documents are processed in memory and purged immediately on response delivery. Nothing is written to disk. Our security team monitors the infrastructure around the clock, runs regular penetration tests, and maintains GDPR and HIPAA certifications. You get enterprise-grade security for a compliance feature without needing to build or staff the security function yourself.

Complete ZUGFeRD API endpoint reference

All endpoints are available at https://api.invoicexml.com. Authentication uses Bearer token in the Authorization header. Error responses follow RFC 7807 ProblemDetails with structured errorCode fields and human-readable friendly error messages.

Full OpenAPI 3.1 schema available at api.invoicexml.com/openapi.

Supported ZUGFeRD versions and profiles

Get started

Upload any PDF invoice at invoicexml.com/pdf-to-zugferd to see a ZUGFeRD conversion in seconds — no account or API key required.

To integrate via API, start your free 30-day trial. The permanent free tier of 100 credits per month keeps your development environment running without a paid plan.

Related resources:

• How the AI document pipeline works
• Full API documentation
• Factur-X API: the complete toolkit
• CII API: the complete toolkit
• UBL API: the complete toolkit
• Automation and no-code integrations
• Pricing

InvoiceXML is the compliance layer for modern European e-invoicing. It covers ZUGFeRD (all versions), Factur-X, XRechnung, CII, UBL, and EN 16931 via a single REST API — with stateless processing, DATEV-compatible output, GoBD-ready PDF/A-3b containers, and no e-invoice infrastructure to maintain on your side.