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