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

> Source: <https://dev.to/dominikschroeter/german-e-invoicing-for-developers-xrechnung-and-zugferd-via-rest-api-and-mcp-16dl>
> Published: 2026-11-21 23:32:15+00:00

**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.

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](https://maxrechnung.de), 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](https://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](https://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](https://maxrechnung.de/anleitungen/n8n-integration).

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.
