cd /news/agent-protocols/german-e-invoicing-for-developers-xr… · home › topics › agent-protocols › article
[ARTICLE · art-173974] src=dev.to ↗ pub= topic=agent-protocols verified=true sentiment=· neutral

German e-invoicing for developers: XRechnung and ZUGFeRD via REST API and MCP

The team behind MaxRechnung, a German invoicing app, detailed how it generates both XRechnung and ZUGFeRD e-invoices from a single structured invoice object via its REST API and an MCP integration. The writeup explains Germany's phased B2B e-invoicing mandate—receiving mandatory since January 2025, sending for larger firms from 2027 and nearly all businesses from 2028—and recommends running open EN 16931 validators in CI because schematron rules change with each XRechnung release. The API freezes finalized invoice XML and uses idempotency keys to make retries safe.

key takeaway

Finalizing an invoice with e_invoice_formats set enforces full EN 16931/XRechnung rules and freezes the XML, and an Idempotency-Key returns the original response on retry within 24 hours but a 409 conflict if the body differs.

by read6 min views2 publishedNov 21, 2026

From 2027, many German businesses have to send structured e-invoices to other businesses, and from 2028 almost all of them. Receiving them has been mandatory since 1 January 2025. If you build software that creates or processes invoices for German customers, this is now your problem too.

This post covers what counts as an e-invoice, the two formats you will meet, how to validate them, and how we generate both formats from a single invoice object in our own API. Disclosure up front: we build MaxRechnung, a German invoicing app, and the examples in the second half use our API.

Date Who What
1 Jan 2025 All German businesses Must be able to receive e-invoices (B2B)
1 Jan 2027 Businesses with prior-year revenue > €800,000 Must send e-invoices for domestic B2B
1 Jan 2028 All other businesses Must send e-invoices for domestic B2B

Small businesses under § 19 UStG ("Kleinunternehmer") are exempt from sending, but they still have to receive. Small-amount invoices up to €250 and travel tickets are exempt as well, and B2C invoices are not affected.

A PDF is not an e-invoice under German law, even if it is generated by software. An e-invoice is a structured, machine-readable format that complies with the European standard EN 16931. The law also allows other agreed formats such as EDI, as long as the data can be extracted in a way compatible with EN 16931. In practice, though, you will meet one of two formats:

Legally, the XML is what counts. If the PDF and the embedded XML disagree, the XML wins. That also means you have to archive the original file, not a printout or a re-rendered PDF. Strictly, the XML is what must be kept; the PDF part only matters if it carries additional relevant information, but keeping the original file covers both.

Two open validators cover almost everything:

Typical findings in real data:

Std. on the PDF has to become HUR in the XML) If you build an invoicing feature yourself, run these validators in CI against a set of fixture invoices. The schematron rules change with every XRechnung release, and you want to notice before your customers' accounting software does.

In MaxRechnung, an invoice is created once as a structured object. XRechnung and ZUGFeRD are two renderings of the same data, and once an e-invoice is finalized, its XML is frozen. The flow over the REST API (/api/v1) looks like this.

curl -X POST "https://maxrechnung.de/api/v1/invoices" \
  -H "Authorization: Bearer $MXR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-10023" \
  -d '{
    "recipient": {
      "name": "Kunde AG",
      "address": "Kundenweg 5\n20095 Hamburg",
      "email": "rechnung@kunde-ag.example"
    },
    "e_invoice_formats": ["xrechnung", "zugferd"],
    "service_date": "2026-09-01",
    "payment_term_days": 14,
    "line_items": [
      {
        "description": "Beratung vor Ort",
        "quantity": 6.5,
        "unit": "Std.",
        "unit_price": 95,
        "vat_rate": 19
      }
    ]
  }'

Setting e_invoice_formats makes finalizing enforce the full EN 16931/XRechnung rules and freezes the XML. Leave it out only for invoices that don't need to be e-invoices (B2C, for example). The sender (name, address, tax ID) is taken from your account settings; pass a sender object to override it. Seller contact name and phone (BT-41/BT-42) always come from your account settings. A draft may be incomplete, so this call succeeds even if those settings are still empty.

The Idempotency-Key makes retries safe: the same key with the same body within 24 hours returns the original response instead of creating a second invoice, while the same key with a different body returns 409 conflict. Use something stable like your order ID.

curl -X PATCH "https://maxrechnung.de/api/v1/invoices/$INVOICE_ID/status" \
  -H "Authorization: Bearer $MXR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "sent" }'

Finalizing checks the mandatory invoice fields required by § 14 UStG. If something is missing, you get a 422 validation_failed with the affected fields in details (on a fresh account without sender data, for example sender.name, sender.address and sender.tax_id), and nothing is finalized. After that the invoice is immutable; corrections go through a separate corrections endpoint, which is what German bookkeeping rules (GoBD) expect.

curl "https://maxrechnung.de/api/v1/invoices/$INVOICE_ID/xrechnung" \
  -H "Authorization: Bearer $MXR_API_KEY" \
  -o invoice.xml

This returns XRechnung 3.0.2 (CII). With Accept: application/json you get a JSON wrapper that also contains a warnings array from our pre-check against the XRechnung rules, e.g. a missing seller contact (BT-41/BT-42) or buyer e-mail address (BT-49). The free-text unit Std. from the example ends up as unitCode="HUR" in the XML. If you set e_invoice_formats in step 1, finalizing has already enforced these rules and you get the frozen file; don't rely on the HTTP status alone for invoices created without it.

curl -i "https://maxrechnung.de/api/v1/invoices/$INVOICE_ID/zugferd?wait=30" \
  -H "Authorization: Bearer $MXR_API_KEY"

Building a PDF/A-3 takes a moment, so this runs through a queue. If the file is ready within wait seconds you get it directly. Otherwise you get 202 Accepted with a Location: /api/v1/jobs/{id} header that you can poll, or you subscribe to the invoice.zugferd_ready webhook. The profile is set on the invoice, not as a parameter of this call: the default is EN 16931 (COMFORT), and basic and extended are available too. The output has been validated with Mustang (veraPDF + profile schematron) for all three profiles.

The full reference, including a cURL import for each endpoint, is at maxrechnung.de/developers/api, and the OpenAPI 3.1 spec is at https://maxrechnung.de/api/openapi.json.

The same API is exposed as an MCP server, so Claude Code, Cursor or any MCP client that speaks Streamable HTTP can create drafts, look up customers or download e-invoices:

{
  "mcpServers": {
    "maxrechnung": {
      "type": "http",
      "url": "https://maxrechnung.de/mcp",
      "headers": {
        "Authorization": "Bearer mxr_live_…",
        "X-MCP-Read-Only": "1"
      }
    }
  }
}

The server stores nothing and passes your key through to the REST API, so scopes and rate limits are identical. Two details we found important in practice:

X-MCP-Read-Only: 1 limits the assistant to the 28 reading tools. Add write access only when you trust the workflow.invoices:draft scope can create and edit drafts but cannot finalize, correct, cancel or record payments; those need invoices:write. Letting the model draft and a human finalize is a sensible default for anything that ends up in the books. Tool overview: maxrechnung.de/developers/mcp.

If you'd rather not write code, the API works with n8n's standard HTTP Request node: a "Header Auth" credential with Authorization: Bearer <key>, base URL https://maxrechnung.de/api/v1. We documented four building blocks (create customer, create and finalize invoice, sum payments, list overdue invoices for a daily dunning list) in the n8n guide.

API access in MaxRechnung requires the Business plan. If you're building your own implementation instead, the validators and the format notes above apply just the same. Questions about edge cases (Leitweg-ID, reverse charge, partial invoices) are welcome in the comments.

── more in #agent-protocols 4 stories · sorted by recency
── more on @maxrechnung 3 stories trending now
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
→ Live at https://your-agent.zahid.host ✓
Get free account → Pricing
from €0/mo · no card required
LIVE [news/german-e-invoicing-f…] indexed:0 read:6min 2026-11-21 · —