QuoteCashbeta
Sign InGet Started
Hybrid invoice API

ZUGFeRD API for Hybrid PDF/XML Invoices

Generate a readable invoice PDF with embedded structured CII XML through one REST endpoint.

PDF and XML are derived from the same accepted invoice payload. QuoteCash validates the XML before attachment and returns the result with the generated files.

Hybrid PDF + CII XMLEN 16931 profileXML validation included
01QuoteCash

Hybrid invoice document

On success, POST /api/v1/invoices/zugferd returns a base64 PDF with factur-x.xml attached, plus the generated CII XML as a separate response field.

02QuoteCash

Transparent XML validation

The generated XML is checked through the configured KoSIT-compatible validator. A failed 422 response returns XML and error details for diagnosis, but no send-ready PDF.

03QuoteCash

REST API for integrations

Use business-scoped API keys and predictable JSON responses in billing, ERP, agency, and SaaS workflows. The legacy endpoint returns files without storing the invoice.

How it works

How QuoteCash builds and validates the hybrid document

POST /api/v1/invoices/zugferd maps the accepted JSON payload into generic EN 16931 CII XML, validates that XML, generates the visible PDF, and attaches factur-x.xml. The successful response contains the PDF, XML, validation result, and suggested filename.

The current generator emits the UN/CEFACT CII namespace ending in :100 and the generic guideline identifier urn:cen.eu:en16931:2017. It does not emit a release-specific ZUGFeRD/Factur-X identifier, so QuoteCash does not currently claim conformance with ZUGFeRD 2.5 / Factur-X 1.09.

Validation covers the XML rules executed by the configured service. The final PDF container, PDF/A level, attachment relationship, and XMP metadata are not independently validated. A 422 response contains diagnostic XML and validation details only.

Who it’s for

Who benefits from the hybrid workflow?

Freelancers and small businesses

Create a familiar invoice document while also supplying structured data for automated processing.

Software and SaaS providers

Add server-side PDF/XML generation and explicit validation outcomes to billing products.

Agencies and resellers

Use one documented response contract and route invalid XML into a controlled correction workflow.

ERP integrators

Connect invoice payloads, XML validation, and artifact handling without relying on a manual export screen.

Editorial note

Last reviewed: July 24, 2026

The technical scope, stated precisely

QuoteCash currently creates a PDF with generic EN 16931 CII XML attached. XML validation, PDF/A conformance, and formal support for a specific ZUGFeRD/Factur-X release are separate claims.

Implementation guidance

Current standard versus current implementation

The current joint release, ZUGFeRD 2.5 / Factur-X 1.09, is technically identical, uses UN/CEFACT CII D22B, and should be used from July 1, 2026 according to FeRD. It includes dedicated XSD and Schematron artifacts for five profiles.

QuoteCash does not currently use those release-specific artifacts. Its internal xmlbuilder2 generator writes the :100 CII namespace with the generic guideline identifier urn:cen.eu:en16931:2017. The product copy therefore does not name a supported ZUGFeRD release.

Implementation guidance

EN16931 profile and receiver requirements

The generator produces only its generic EN16931 output, and EN16931 is the default. Other profile values do not change the XML and are rejected by the canonical artifact request.

MINIMUM and BASIC WL would not meet the usual EN-16931-based German B2B e-invoice requirements. QuoteCash does not offer those profiles, BASIC, or EXTENDED. Public-sector and other receivers may additionally require XRechnung, a buyer reference, or a specific portal.

Implementation guidance

XML validation is not PDF/A-3 validation

QuoteCash sends generated CII XML to the configured KoSIT-compatible validation service. The exact XSD, Schematron, and code-list versions are controlled by that service and are not versioned in this repository.

Only after XML passes does pdf-lib attach factur-x.xml to the visible PDF. No independent PDF/A-3 validator runs, and the PDF attachment relationship and XMP metadata are not checked. The result must not be marketed as proven PDF/A-3 conformant.

Implementation guidance

Content identity, failures, and retention

The visible PDF and structured XML must represent the same invoice information. QuoteCash derives both from the same accepted API payload but uses separate transformations, so integration tests should compare totals, tax, parties, payment data, and line items. If a hybrid e-invoice differs, the structured part is decisive under the German guidance.

If XML validation fails, the legacy endpoint returns only XML and error details with status 422; it does not assemble a PDF. Treat that XML as diagnostic, not as a valid invoice. Preserve the successfully transmitted hybrid original unchanged in your retention process; the BMF currently states eight years for VAT invoice retention. This is not legal advice.

Example

API example: generate a hybrid invoice PDF

This example matches the actual request schema. The legacy endpoint uses EN16931 as its fixed profile and does not store the invoice.

POST /api/v1/invoices/zugferd
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "schema_version": "1",
  "invoice_number": "RE-2026-2048",
  "issue_date": "2026-07-24",
  "due_date": "2026-08-07",
  "currency": "EUR",
  "seller": {
    "name": "Muster GmbH",
    "vat_id": "DE123456789",
    "street": "Musterstraße 1",
    "city": "Berlin",
    "postal_code": "10115",
    "country": "DE",
    "email": "rechnung@muster.example",
    "phone": "+49 30 123456"
  },
  "buyer": {
    "name": "Kunde GmbH",
    "vat_id": "DE987654321",
    "street": "Kundenweg 2",
    "city": "Hamburg",
    "postal_code": "20095",
    "country": "DE"
  },
  "line_items": [
    {
      "description": "Support package",
      "quantity": 10,
      "price": 95,
      "total": 950,
      "vatRate": 19,
      "unitCode": "C62"
    }
  ],
  "totals": {
    "net": 950,
    "tax": 180.5,
    "gross": 1130.5
  },
  "payment": {
    "iban": "DE02120300000000202051",
    "bic": "BYLADEM1001"
  }
}
Implementation

ZUGFeRD implementation checklist

  1. 1Confirm whether the receiver expects EN16931, XRechnung, or another specific profile.
  2. 2Send the documented payload with complete parties, line items, totals, and payment data.
  3. 3Inspect validation.valid and use 422 responses only for diagnosis.
  4. 4Compare amounts, tax logic, and core data in the visible PDF and XML.
  5. 5Add independent PDF/A and metadata validation before production delivery when formal ZUGFeRD conformance is required.
  6. 6Preserve the successfully transmitted hybrid original unchanged in your own retention process.

Related QuoteCash pages

XRechnung APIUse pure XML when the recipient expects a strict structured invoice without a PDF shell.XRechnung validatorCheck XML before it is embedded into a hybrid PDF or sent as a standalone invoice.Cashflow Forecast API for open invoicesRetrieve expected invoice payments and overdue receivables from stored invoice data.

Official sources and standards

FeRD: ZUGFeRD 2.5 / Factur-X 1.09FeRD describes the current joint release, CII D22B, five profiles, and the related XSD and Schematron artifacts.FeRD: standard overview and content identityThe overview explains the hybrid format, PDF/A-3, and the need for matching visible and structured invoice content.German Finance Ministry: e-invoices, leading XML, and retentionThe BMF explains acceptable formats, the decisive structured part, and the eight-year VAT retention period for invoices.

Frequently Asked Questions

Which ZUGFeRD version does QuoteCash support?
The current implementation does not claim a specific ZUGFeRD or Factur-X release. It emits generic EN 16931 CII XML without a release-specific guideline identifier or the ZUGFeRD 2.5 / Factur-X 1.09 D22B validation artifacts.
Which profiles does the API support?
QuoteCash currently generates only the EN16931 profile, and it is the default. MINIMUM, BASIC WL, BASIC, and EXTENDED are not generated by this endpoint. Receiver-specific requirements can still apply.
Does QuoteCash validate only XML or also PDF/A conformance?
Only the generated CII XML is sent to the configured validator. QuoteCash does not currently run an independent PDF/A-3 conformance check or validate the PDF attachment and XMP metadata.
May I send a PDF returned after a validation failure?
No. The legacy endpoint does not assemble a PDF after XML validation fails; its 422 response returns the XML and validation details for diagnosis. Correct the payload and validate again before sending or archiving the result as final.
How are ZUGFeRD and Factur-X related?
For the current joint release, ZUGFeRD 2.5 and Factur-X 1.09 are the German and French names for technically identical formats. This statement does not turn QuoteCash’s current generic CII output into that release.
Does QuoteCash return a hybrid PDF or only XML?
After successful XML validation, the endpoint returns a PDF with factur-x.xml attached and the XML separately. The response does not prove PDF/A-3 conformance.
Is ZUGFeRD accepted by every German public authority?
Not automatically. Public-sector recipients often define specific portal and format requirements. Check the recipient process before choosing a format.
How should the hybrid invoice be retained?
Preserve the successfully transmitted hybrid original unchanged. The separately returned XML can also be stored for processing and checks; the structured original content must remain intact.