ZUGFeRD API for compliant hybrid invoices
Germany's B2B mandate made ZUGFeRD a workhorse: reception has been mandatory since January 2025, issuance follows in 2027 and 2028. But not every ZUGFeRD file is an e-invoice in the legal sense. MINIMUM and BASIC WL are booking aids, and most validators pass them without a word. InvoiceXML validates every profile against the official Factur-X and ZUGFeRD artifacts and attaches a PROFILE-SCOPE warning when a document does not qualify. Your AP team learns it from the API, not from an auditor.
curl -X POST https://api.invoicexml.com/v1/validate/zugferd \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "[email protected]"
{
"valid": true,
"data": {
"profile": "minimum",
"customizationId": "urn:factur-x.eu:1p0:minimum"
},
"warnings": [
{
"rule": "PROFILE-SCOPE",
"layer": "cius",
"message": "Factur-X/ZUGFeRD MINIMUM is a
header-only profile and not a full
EN 16931 e-invoice. Under the German
B2B e-invoicing rules it does not
qualify as an e-invoice."
}
]
}
Technically valid and legally counting are two columns
Every profile validates against its own schema and rule set from the official package. But technical validity and legal standing are different questions, and a validator that answers only one of them is setting you up. We answer both.
| Profile | Technically valid? | An e-invoice in German B2B? | What you get from us |
|---|---|---|---|
| MINIMUM | Yes, against its own rule set | No. A booking aid, per the BMF | A pass plus a PROFILE-SCOPE warning, never silence |
| BASIC WL | Yes, against its own rule set | No. Header-only, same BMF carve-out | The same honest advisory |
| BASIC | Yes, schema and rules | Yes, from here on up | The BASIC-restricted XSD plus the BASIC rules |
| EN 16931 | Yes, schema and rules | Yes | CEN artifacts; the profile our created hybrids declare |
| EXTENDED | Yes, schema and rules | Yes | The EXTENDED XSD and rules; extra fields are never failed |
| ZUGFeRD 1.0 | No. Retired | No | Reported clearly as schema-invalid, with the advice to re-issue as 2.x |
zugferd.de (2p0) identifiers are accepted exactly as the official rules specify, and the XRechnung reference profile (an xrechnung.xml attachment) routes to the KoSIT rules. Technically, ZUGFeRD 2.x and Factur-X are one standard: the French half of the family lives on the Factur-X hub.
Every profile, minimum to extended
More invoice detail
- MINIMUM
- BASIC WL
- BASIC
- EN 16931
- EXTENDED
Issue, receive, and everything in between
One engine behind six endpoints, each with a free in-browser companion for quick checks without code.
Create ZUGFeRD
JSON in, a hybrid PDF out: our template (EN/DE/FR, brand color, logo) or your own via pdfUrl.
Open toolValidate ZUGFeRD
Every profile checked honestly, PROFILE-SCOPE advisories included.
Open toolEmbed XML → PDF
Marry your CII XML and your PDF into a ZUGFeRD hybrid.
Open toolExtract the XML
The embedded CII out of any supplier hybrid, byte for byte.
Open toolExtract JSON
Supplier hybrids as BT-mapped JSON, ready for your ERP.
Open toolConvert → ZUGFeRD
Turn XRechnung, UBL, or CII files into hybrid PDFs.
Open tool2027 is Germany's deadline. It doesn't have to be yours.
Reception has been law since January 2025; the issuance phases land in 2027 and 2028. The format itself is stewarded by FeRD, and we run its official validation package unmodified, per-profile XSD plus Schematron, regression-tested against FeRD's own sample sets. When artifacts or legal interpretations move, the engine here moves with them, server-side, on the effective date. You keep posting the same JSON.
See which artifact versions are live right nowFrom 2027, businesses above EUR 800k turnover must issue e-invoices; from 2028, everyone. Hybrids created here already qualify: they declare the EN 16931 profile.
A BT-by-BT report your auditors can keep
Validations return more than a verdict: a compliance report walks the document business term by business term, with the extracted value and a per-field result. AP triage, archive evidence, and import debugging all read from the same array.
DATEV and SAP still run their own container-level import checks. What we certify is the XML business layer they consume.
{
"valid": true,
"data": {
"profile": "en16931",
"customizationId": "urn:cen.eu:en16931:2017"
},
"report": [
{ "code": "BT-1", "name": "Invoice number",
"value": "RE-2026-0107", "isValid": true },
{ "code": "BT-31", "name": "Seller VAT identifier",
"value": "DE811234567", "isValid": true },
{ "code": "BT-115", "name": "Amount due for payment",
"value": "11900.00", "isValid": true }
]
// one row per business term, the whole document
}
Validation errors and warnings in German language
Ask for German and every finding comes back as a plain-language explanation of what is wrong and how to fix it, ready to show in your app as it is. Each finding also carries its rule id, Business Term code and field path, so you can highlight the form field that caused it.
-
One field, three languages
Send validationLanguage with the upload, or options.validationLanguage with a create call: German, French or English. Validate, create, embed, convert and transform all speak it, with no translation layer to build or maintain on your side.
-
Every rule explained, not just translated
Every EN 16931 business rule, the full KoSIT XRechnung rule set and the Peppol BIS rules each have their own reviewed message, written for the people who fix invoices rather than for Schematron authors. No rule codes in the text, just what to change.
-
A PDF report in the same language
The printable report comes out in German too: verdict, field names, dates and every finding. Hand it to your tax advisor or file it with the invoice for GoBD.
-
XRechnung and the KoSIT rules, covered
Leitweg-ID, payment details, seller contact: every check of the German XRechnung rules comes back in German and names the field to fill, the way public-sector recipients check them.
Die USt-IdNr. des Verkäufers muss mit dem Code des ausstellenden Landes beginnen, z. B. DE123456789. Griechenland verwendet EL.
{ "rule": "BR-CO-09", "btCodes": ["BT-31"], "fields": ["seller.vatIdentifier"], "message": "Die USt-IdNr. des Verkäufers muss mit dem Code des ausstellenden Landes beginnen, z. B. DE123456789. Griechenland verwendet EL." }
rule, btCodes and fields stay the same in every language
The PDF report, as your reader gets it
POST /v1/validate/…/report
XRechnung rules, in plain German
Every KoSIT check names the field to fill, Leitweg-ID included.
Eine XRechnung braucht die Käuferreferenz, bei öffentlichen Auftraggebern die Leitweg-ID.
Geben Sie die Kontaktdaten des Verkäufers an: Ansprechpartner, Telefonnummer und E-Mail-Adresse (Pflichtangaben in der XRechnung).
Germany's mandate, phase by phase
ZUGFeRD's home turf is the German B2B mandate: the PDF keeps working for people while the law starts speaking XML.
The qualifying formats are defined in the BMF FAQ, on the European floor of Directive 2014/55/EU. German B2G is XRechnung territory, and the wider rollout is mapped on the Mandate Map. Selling into France, the Netherlands, or the Peppol countries too? One API covers the European formats.
Wire it up before the auditor calls
Secure by Architecture
Your invoices are processed in memory and returned in the same response. Zero data retention is not a policy we enforce, it is an architecture we built.
- Encrypted in transit. TLS on the request and on the response stream.
- Our own code, end to end. No subprocessor ever sees an invoice.
- Signed DPA and SLA available. For Enterprise customers, on request.
- Disknever
- Queuenever
- Backupnever
Zero data retention
Processed in volatile memory only. Never written to disk, never queued, never backed up.
EU-only processing
Servers in Frankfurt, Germany. No transfers outside the European Economic Area.
No use of your data
Never used for analytics, never to train AI models, never shared with third parties.
Certified infrastructure
SOC 2 Type II, ISO/IEC 27001 and PCI-DSS at the platform layer, held by our infrastructure provider.
Compliance Overview
Formats, validation and data protection on four pages. Ready to forward to your procurement, legal or IT team.
GDPR compliant by design · nothing stored on our servers
What German AP and AR teams ask us
What is the difference between ZUGFeRD and XRechnung?
Two German answers to different questions. XRechnung is pure XML for public-sector portals; ZUGFeRD is a hybrid PDF for B2B workflows where humans still open invoices. Both qualify under the German B2B rules (ZUGFeRD from BASIC upward), both come out of this API, and there is even a ZUGFeRD profile that carries XRechnung XML. The B2G side has its own hub.
Why does my valid MINIMUM invoice carry a warning?
Because both statements are true: the file passes its own MINIMUM rules, and under the German B2B e-invoicing rules it does not qualify as an e-invoice, per the BMF. Most validators only tell you the first part. The PROFILE-SCOPE warning rides along with valid: true, so nothing breaks and nobody is misled.
Do you still accept ZUGFeRD 1.0?
ZUGFeRD 1.0 (the CrossIndustryDocument root) is retired and reported as schema-invalid with a clear finding recommending a re-issue as 2.x. ZUGFeRD 2.x documents carrying legacy zugferd.de identifiers are a different matter: the official rules accept those, and so do we.
Can I keep my own invoice layout?
Yes. Hand us your PDF via options.pdfUrl (an absolute URL, up to 20 MB) and we embed the validated XML into it. Otherwise we render our template in German, English, or French, with options.brandColor applied to headings and accents and your logo (options.logoUrl, PNG or JPEG) printed top-left.
Will DATEV or SAP import the hybrids you create?
We cannot speak for another product's import pipeline, and we do not pretend to: DATEV and SAP run their own container-level checks. What we certify is the layer they consume, validated XML with the EN 16931 profile declared, plus a BT-by-BT report that makes import problems quick to triage.
What do I need to be ready for 2027 and 2028?
From 2027 businesses above EUR 800k turnover must issue e-invoices; from 2028 everyone must. Hybrids created here declare the EN 16931 profile, which qualifies, and validation flags supplier files that do not. The spec tracking is our job, not a line on your roadmap.