E-Rechnung & PDF

Zu einer Rechnung das PDF (DIN 5008), XRechnung 3.0.2, ZUGFeRD 2.5.2 / Factur-X und den GiroCode abrufen.

Authentifizierung

Jeder Request braucht einen API-Key im Header. Keys entstehen unter Einstellungen → API (nur Business-Tarif). Details zu Scopes, Idempotenz und Rate-Limits auf der Übersichtsseite.

Authorization: Bearer mxr_live_…

Bleibt in diesem Browser-Tab (sessionStorage), nur für „Ausprobieren“ auf dieser Seite, und geht direkt aus deinem Browser an /api/v1 — kein Versand an unseren Server, kein Log.

PDF der Rechnung

get/api/v1/invoices/{id}/pdf

Serverseitig gerendertes PDF (DIN 5008). Entwürfe tragen das ENTWURF-Wasserzeichen.

Scope

invoices:read

Parameter

  • id path · string · uuid*Interne id der Rechnung (UUID), nicht die Belegnummer. Zu einer Nummer (z. B. RE-2026-0004) liefert GET /invoices?number=… (MCP: list_invoices mit number) die id.
curl -X GET "https://maxrechnung.de/api/v1/invoices/{id}/pdf" \
  -H "Authorization: Bearer $MXR_API_KEY"

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 200 PDF
  • 401 Kein oder ungültiger API-Key
  • 403 Scope fehlt oder der Tarif reicht nicht (plan_required)
  • 404 Nicht gefunden
  • 429 Rate Limit überschritten

E-Rechnung (XRechnung 3.0.2 / CII-XML)

get/api/v1/invoices/{id}/xrechnung

XRechnung 3.0.2 (CII-XML nach EN 16931, XRechnung-CIUS 3.0.2 der KoSIT; gegen den KoSIT-Validator geprüft). Ohne Accept-Header: das XML als Datei-Download. Mit Accept: application/json: { filename, warnings, xml } — warnings listet offene Punkte (z. B. fehlende Leitweg-ID/BT-49). Das XML wird beim Festschreiben eingefroren und danach unverändert ausgeliefert.

Scope

invoices:read

Parameter

  • id path · string · uuid*Interne id der Rechnung (UUID), nicht die Belegnummer. Zu einer Nummer (z. B. RE-2026-0004) liefert GET /invoices?number=… (MCP: list_invoices mit number) die id.
curl -X GET "https://maxrechnung.de/api/v1/invoices/{id}/xrechnung" \
  -H "Authorization: Bearer $MXR_API_KEY"

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 200 XRechnung-XML
  • 401 Kein oder ungültiger API-Key
  • 403 Scope fehlt oder der Tarif reicht nicht (plan_required)
  • 404 Nicht gefunden
  • 429 Rate Limit überschritten

Schema 200

  • object "xrechnung"
  • filename string
  • version "3.0.2"XRechnung-Version des XML. Beim Datei-Download im Header X-XRechnung-Version.
  • frozen booleantrue: das beim Festschreiben eingefrorene XML. false: aus dem Entwurf frisch erzeugt.
  • warnings string[]
  • xml string

Beispiel 200

{
  "object": "xrechnung",
  "filename": "…",
  "version": "3.0.2",
  "frozen": false,
  "warnings": [
    "…"
  ],
  "xml": "…"
}

ZUGFeRD 2.5.2 / Factur-X 1.09.2 (PDF/A-3 mit eingebettetem XML)

get/api/v1/invoices/{id}/zugferd

Das Rechnungs-PDF als PDF/A-3 (ISO 19005-3) mit eingebettetem CII-XML (factur-x.xml) nach ZUGFeRD 2.5.2 / Factur-X 1.09.2. Profil je Rechnung: BASIC, EN 16931 (COMFORT, Vorgabe) oder EXTENDED. Mit Accept: application/json: { filename, warnings }. Gegen den Mustang-Validator (veraPDF + Profil-Schematron) geprüft; abwärtskompatibel bis ZUGFeRD 2.0.1 (BMF-Untergrenze § 14 UStG). Das eingebettete XML wird beim Festschreiben eingefroren.

Asynchron. Die Wandlung läuft in einer Warteschlange; bereits erzeugte Dateien kommen sofort (Cache nach Inhalt, festgeschriebene Belege werden beim Festschreiben vorab erzeugt). Ist die Datei nicht binnen wait Sekunden fertig, antwortet der Endpunkt mit 202 + Job-Objekt und Location: /api/v1/jobs/{id} — dort pollen oder auf das Webhook-Event invoice.zugferd_ready warten, danach diesen Endpunkt erneut abrufen. Höchstens 100 offene Aufträge je Konto (sonst 429).

Scope

invoices:read

Parameter

  • id path · string · uuid*Interne id der Rechnung (UUID), nicht die Belegnummer. Zu einer Nummer (z. B. RE-2026-0004) liefert GET /invoices?number=… (MCP: list_invoices mit number) die id.
  • wait query · integerSekunden, die der Aufruf auf die fertige Datei wartet, bevor er mit 202 antwortet (0–60, Vorgabe 30).
curl -X GET "https://maxrechnung.de/api/v1/invoices/{id}/zugferd" \
  -H "Authorization: Bearer $MXR_API_KEY"

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 200 ZUGFeRD-PDF
  • 202 Wird noch erzeugt — Job unter Location pollen
  • 401 Kein oder ungültiger API-Key
  • 403 Scope fehlt oder der Tarif reicht nicht (plan_required)
  • 404 Nicht gefunden
  • 429 Zu viele offene ZUGFeRD-Aufträge
  • 503 ZUGFeRD-Erzeugung fehlgeschlagen

Schema 200

  • object "zugferd"
  • filename string
  • profile "basic" | "en16931" | "extended"ZUGFeRD-Profil des Belegs.
  • frozen booleantrue: das beim Festschreiben eingefrorene XML wird eingebettet.
  • warnings string[]

Beispiel 200

{
  "object": "zugferd",
  "filename": "…",
  "profile": "basic",
  "frozen": false,
  "warnings": [
    "…"
  ]
}

Stand eines asynchronen Auftrags (ZUGFeRD-Erzeugung)

get/api/v1/jobs/{id}

Liefert den Stand eines Jobs aus 202-Antworten (bisher nur type: zugferd). status: queued → processing → done (dann download_url) oder failed. Wiederholungen nach Fehlern laufen automatisch und zeigen sich als queued.

Scope

invoices:read

Parameter

  • id path · string · uuid*
curl -X GET "https://maxrechnung.de/api/v1/jobs/{id}" \
  -H "Authorization: Bearer $MXR_API_KEY"

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 200 Job
  • 401 Kein oder ungültiger API-Key
  • 403 Scope fehlt oder der Tarif reicht nicht (plan_required)
  • 404 Nicht gefunden
  • 429 Rate Limit überschritten

Schema 200

Beispiel 200

{
  "object": "job",
  "id": "00000000-0000-0000-0000-000000000000",
  "type": "zugferd",
  "status": "queued",
  "invoice_id": "00000000-0000-0000-0000-000000000000",
  "profile": "basic",
  "attempts": 0,
  "created_at": "2026-01-31T12:00:00Z",
  "finished_at": "2026-01-31T12:00:00Z",
  "download_url": "…",
  "error": "…"
}

GiroCode (EPC069-12) für den Rechnungsbetrag

get/api/v1/invoices/{id}/girocode

EPC-QR-Code (GiroCode) über den Brutto-Rechnungsbetrag auf die Absender-IBAN. Standard: JSON { object, invoice_id, payload, data_uri } — payload ist die BCD-Nutzlast, data_uri ein PNG als data:-URI. ?format=png gibt das PNG direkt zurück. 409, wenn im Absender keine IBAN hinterlegt ist oder kein positiver Betrag zu zahlen ist. Kein Betragslimit unterhalb des EPC-Maximums (999.999.999,99 €); Entwurf oder fehlende Kundendaten sind kein Hindernis. Scope invoices:read.

Scope

invoices:read

Parameter

  • id path · string · uuid*Interne id der Rechnung (UUID), nicht die Belegnummer. Zu einer Nummer (z. B. RE-2026-0004) liefert GET /invoices?number=… (MCP: list_invoices mit number) die id.
  • format query · "png"png liefert das QR-Bild direkt (image/png) statt JSON.
curl -X GET "https://maxrechnung.de/api/v1/invoices/{id}/girocode" \
  -H "Authorization: Bearer $MXR_API_KEY"

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 200 GiroCode
  • 401 Kein oder ungültiger API-Key
  • 403 Scope fehlt oder der Tarif reicht nicht (plan_required)
  • 404 Nicht gefunden
  • 409 Kein GiroCode möglich; message nennt den Grund: Fremdwährung, keine Absender-IBAN, kein Absendername, kein positiver Betrag oder Betrag über 999.999.999,99 €
  • 429 Rate Limit überschritten

Schema 200

  • object "girocode"
  • invoice_id string · uuid
  • payload string
  • data_uri string

Beispiel 200

{
  "object": "girocode",
  "invoice_id": "00000000-0000-0000-0000-000000000000",
  "payload": "…",
  "data_uri": "…"
}

Schemas

Von den Endpunkten oben referenzierte Objekte. Vollständig auch in der OpenAPI-Spezifikation.