Rechnungen

Rechnungen und Rechnungskorrekturen anlegen, auflisten, bearbeiten, nach § 14 UStG festschreiben, korrigieren und stornieren.

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.

Belege auflisten

get/api/v1/invoices

Listet alle Belegarten: Rechnungen, Korrekturen (KR-) und Stornos (ST-). Mit type auf eine Art einschränken.

Scope

invoices:read

Parameter

  • status query · "draft" | "sent" | "partial" | "paid" | "void"
  • type query · "invoice" | "correction" | "cancellation" | "advance_invoice" | "final_invoice"Belegart filtern. Ohne Angabe: alle Arten. invoice ohne Abschlags- und Schlussrechnungen.
  • number query · stringExakte Belegnummer (z. B. RE-2026-0004) — so findet man die id zu einer Nummer.
  • custom_fields query · objectFilter nach eigenen Feldern: custom_fields[schlüssel]=wert, mehrere sind UND-verknüpft. Ja/Nein: true oder false (nicht gesetzt). Unbekannter Schlüssel → 400.
  • limit query · integer
  • offset query · integer
curl -X GET "https://maxrechnung.de/api/v1/invoices" \
  -H "Authorization: Bearer $MXR_API_KEY"

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

Antworten

  • 200 Liste
  • 401 Kein oder ungültiger API-Key
  • 403 Scope invoices:read fehlt oder kein Business-Tarif
  • 429 Rate Limit überschritten

Schema 200

  • object "list"
  • data Invoice[]
  • limit integer
  • offset integer
  • has_more boolean

Beispiel 200

{
  "object": "list",
  "data": [
    {
      "object": "invoice",
      "id": "00000000-0000-0000-0000-000000000000",
      "type": "invoice",
      "status": "draft",
      "number": "RE-2026-004",
      "invoice_date": "2026-01-31",
      "service_date": "2026-01-31",
      "service_date_end": "2026-01-31",
      "collected_on": "2026-01-31",
      "due_date": "2026-01-31",
      "payment_term_days": 14,
      "amount_paid": 0,
      "amount_open": 428.4,
      "corrected_invoice": {
        "id": "00000000-0000-0000-0000-000000000000",
        "number": "…",
        "date": "2026-01-31"
      },
      "sender": {
        "name": "…",
        "address": "…",
        "tax_id": "…",
        "tax_id_kind": "vat_id",
        "email": "…",
        "bank_name": "…",
        "iban": "…"
      },
      "recipient": {
        "name": "…",
        "address": "…",
        "email": "…",
        "vat_id": "…",
        "vat_id_check": {
          "status": "valid",
          "source": "vies",
          "checked_at": "2026-01-31T12:00:00Z",
          "name": "…",
          "stale": false,
          "matches": {
            "name": "…",
            "street": "…",
            "postcode": "…",
            "city": "…"
          }
        },
        "country": "…",
        "contact_name": "…"
      },
      "delivery": {
        "name": "…",
        "address": "…",
        "country": "DE"
      },
      "buyer_reference": "…",
      "customer_order_number": "…",
      "customer_order_date": "2026-01-31",
      "customer_id": "00000000-0000-0000-0000-000000000000",
      "customer_number": "…",
      "supplier_number": "…",
      "e_invoice_formats": [
        "xrechnung"
      ],
      "vat_scheme": "standard",
      "vat_exempt_clause": "8",
      "small_business": false,
      "price_mode": "net",
      "language": "de",
      "currency": "EUR",
      "exchange_rate": 0,
      "discount": {
        "type": "percent",
        "value": 0,
        "reason": "…"
      },
      "skonto": {
        "percent": 0,
        "days": 0
      },
      "line_items": [
        {
          "description": "…",
          "quantity": 3,
          "unit": "Std.",
          "unit_price": 120,
          "vat_rate": 19,
          "article_number": "BER-01",
          "vat_exempt_clause": "8"
        }
      ],
      "notes": "…",
      "advances": [
        {
          "invoice_id": "00000000-0000-0000-0000-000000000000",
          "number": "…",
          "date": "2026-01-31",
          "net": 0,
          "vat": 0,
          "gross": 0,
          "vat_groups": [
            {
              "rate": null,
              "net": null,
              "vat": null
            }
          ],
          "paid": false
        }
      ],
      "totals": {
        "lines": 0,
        "discount": 0,
        "net": 0,
        "vat": 0,
        "gross": 0,
        "service": {
          "net": 0,
          "vat": 0,
          "gross": 0
        },
        "prepaid": {
          "net": 0,
          "vat": 0,
          "gross": 0
        },
        "vat_groups": [
          {
            "rate": 0,
            "net": 0,
            "vat": 0
          }
        ]
      },
      "custom_fields": {
        "projekt_nr": "P-17",
        "stripe_customer_id": "cus_Q1w2e3"
      },
      "created_at": "2026-01-31T12:00:00Z",
      "updated_at": "2026-01-31T12:00:00Z"
    }
  ],
  "limit": 0,
  "offset": 0,
  "has_more": false
}

Rechnung anlegen (Entwurf)

post/api/v1/invoices

Legt immer einen Entwurf an. Zum Festschreiben anschließend PATCH /invoices/{id}/status. Scope invoices:draft (oder invoices:write).

Scope

invoices:draft

Parameter

  • Idempotency-Key header · stringFrei gewählter Schlüssel, höchstens 255 Zeichen. Eine Wiederholung mit demselben Schlüssel und demselben Body liefert 24 Stunden lang die erste Antwort zurück.

Request-Body · application/json · erforderlich

{
  "recipient": {
    "name": "Kunde AG",
    "address": "Kundenweg 5\n20095 Hamburg"
  },
  "sender": {
    "name": "Muster Design GmbH",
    "tax_id": "DE123456789"
  },
  "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
    }
  ]
}

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

Antworten

  • 201 Angelegt
  • 400 Ungültiges JSON im Body
  • 401 Kein oder ungültiger API-Key
  • 403 Scope invoices:draft fehlt oder kein Business-Tarif
  • 409 Rechnungsnummer bereits vergeben
  • 422 Ungültige Felder im Body
  • 429 Rate Limit überschritten

Schema 201

Beispiel 201

{
  "object": "invoice",
  "id": "00000000-0000-0000-0000-000000000000",
  "type": "invoice",
  "status": "draft",
  "number": "RE-2026-004",
  "invoice_date": "2026-01-31",
  "service_date": "2026-01-31",
  "service_date_end": "2026-01-31",
  "collected_on": "2026-01-31",
  "due_date": "2026-01-31",
  "payment_term_days": 14,
  "amount_paid": 0,
  "amount_open": 428.4,
  "corrected_invoice": {
    "id": "00000000-0000-0000-0000-000000000000",
    "number": "…",
    "date": "2026-01-31"
  },
  "sender": {
    "name": "…",
    "address": "…",
    "tax_id": "…",
    "tax_id_kind": "vat_id",
    "email": "…",
    "bank_name": "…",
    "iban": "…"
  },
  "recipient": {
    "name": "…",
    "address": "…",
    "email": "…",
    "vat_id": "…",
    "vat_id_check": {
      "status": "valid",
      "source": "vies",
      "checked_at": "2026-01-31T12:00:00Z",
      "name": "…",
      "stale": false,
      "matches": {
        "name": "…",
        "street": "…",
        "postcode": "…",
        "city": "…"
      }
    },
    "country": "…",
    "contact_name": "…"
  },
  "delivery": {
    "name": "…",
    "address": "…",
    "country": "DE"
  },
  "buyer_reference": "…",
  "customer_order_number": "…",
  "customer_order_date": "2026-01-31",
  "customer_id": "00000000-0000-0000-0000-000000000000",
  "customer_number": "…",
  "supplier_number": "…",
  "e_invoice_formats": [
    "xrechnung"
  ],
  "vat_scheme": "standard",
  "vat_exempt_clause": "8",
  "small_business": false,
  "price_mode": "net",
  "language": "de",
  "currency": "EUR",
  "exchange_rate": 0,
  "discount": {
    "type": "percent",
    "value": 0,
    "reason": "…"
  },
  "skonto": {
    "percent": 0,
    "days": 0
  },
  "line_items": [
    {
      "description": "…",
      "quantity": 3,
      "unit": "Std.",
      "unit_price": 120,
      "vat_rate": 19,
      "article_number": "BER-01",
      "vat_exempt_clause": "8"
    }
  ],
  "notes": "…",
  "advances": [
    {
      "invoice_id": "00000000-0000-0000-0000-000000000000",
      "number": "…",
      "date": "2026-01-31",
      "net": 0,
      "vat": 0,
      "gross": 0,
      "vat_groups": [
        {
          "rate": 0,
          "net": 0,
          "vat": 0
        }
      ],
      "paid": false
    }
  ],
  "totals": {
    "lines": 0,
    "discount": 0,
    "net": 0,
    "vat": 0,
    "gross": 0,
    "service": {
      "net": 0,
      "vat": 0,
      "gross": 0
    },
    "prepaid": {
      "net": 0,
      "vat": 0,
      "gross": 0
    },
    "vat_groups": [
      {
        "rate": 0,
        "net": 0,
        "vat": 0
      }
    ]
  },
  "custom_fields": {
    "projekt_nr": "P-17",
    "stripe_customer_id": "cus_Q1w2e3"
  },
  "created_at": "2026-01-31T12:00:00Z",
  "updated_at": "2026-01-31T12:00:00Z"
}

Summen je Kunde, Status oder Monat

get/api/v1/invoices/summary

Serverseitig gerechnete Summen über die Belege (Rechnungen, Korrekturen, Stornos): Anzahl, netto, USt., brutto, bezahlt, offen und überfällig je Gruppe und gesamt. Gruppen nach Netto absteigend (Monate chronologisch) — so beantwortet man „Welcher Kunde brachte am meisten Umsatz?“ ohne selbst zu addieren. Stornierte Belege zählen nie, Entwürfe nur mit include_drafts=true; beide stehen gezählt in excluded. Korrekturen (KR-) mindern mit negativen Beträgen die Summe ihres Kunden.

Scope

invoices:read

Parameter

  • group_by query · "customer" | "status" | "month"customer (Kunden-id, sonst Empfängername), status oder month (Rechnungsmonat YYYY-MM).
  • status query · "draft" | "sent" | "partial" | "paid" | "void"Nur Belege mit diesem Status. draft schließt Entwürfe automatisch ein.
  • type query · "invoice" | "correction" | "cancellation"Belegart filtern. Ohne Angabe: alle Arten.
  • from query · string · dateRechnungsdatum ab (einschließlich), YYYY-MM-DD.
  • to query · string · dateRechnungsdatum bis (einschließlich), YYYY-MM-DD.
  • include_drafts query · booleanEntwürfe mitzählen (Standard: nein — Entwürfe sind kein Umsatz).
curl -X GET "https://maxrechnung.de/api/v1/invoices/summary" \
  -H "Authorization: Bearer $MXR_API_KEY"

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

Antworten

  • 200 Summen
  • 401 Kein oder ungültiger API-Key
  • 403 Scope invoices:read fehlt oder kein Business-Tarif
  • 422 Ungültige Gruppierung, Status, Belegart oder Datum
  • 429 Rate Limit überschritten

Schema 200

Beispiel 200

{
  "object": "invoice_summary",
  "group_by": "customer",
  "from": "2026-01-31",
  "to": "2026-01-31",
  "include_drafts": false,
  "currency": "…",
  "total": {
    "count": 0,
    "net": 0,
    "vat": 0,
    "gross": 0,
    "paid": 0,
    "open": 0,
    "overdue": 0
  },
  "groups": [
    {
      "key": "…",
      "label": "…",
      "customer_id": "00000000-0000-0000-0000-000000000000",
      "currency": "…",
      "invoice_numbers": [
        "…"
      ],
      "count": 0,
      "net": 0,
      "vat": 0,
      "gross": 0,
      "paid": 0,
      "open": 0,
      "overdue": 0
    }
  ],
  "excluded": {
    "drafts": 0,
    "void": 0
  }
}

Beleg abrufen

get/api/v1/invoices/{id}

Liefert den Beleg zu {id} — Rechnung, Korrektur (KR-) oder Storno (ST-). type im Body unterscheidet sie; eigene Abruf-Endpunkte für Korrektur/Storno gibt es nicht.

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}" \
  -H "Authorization: Bearer $MXR_API_KEY"

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

Antworten

  • 200 OK
  • 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": "invoice",
  "id": "00000000-0000-0000-0000-000000000000",
  "type": "invoice",
  "status": "draft",
  "number": "RE-2026-004",
  "invoice_date": "2026-01-31",
  "service_date": "2026-01-31",
  "service_date_end": "2026-01-31",
  "collected_on": "2026-01-31",
  "due_date": "2026-01-31",
  "payment_term_days": 14,
  "amount_paid": 0,
  "amount_open": 428.4,
  "corrected_invoice": {
    "id": "00000000-0000-0000-0000-000000000000",
    "number": "…",
    "date": "2026-01-31"
  },
  "sender": {
    "name": "…",
    "address": "…",
    "tax_id": "…",
    "tax_id_kind": "vat_id",
    "email": "…",
    "bank_name": "…",
    "iban": "…"
  },
  "recipient": {
    "name": "…",
    "address": "…",
    "email": "…",
    "vat_id": "…",
    "vat_id_check": {
      "status": "valid",
      "source": "vies",
      "checked_at": "2026-01-31T12:00:00Z",
      "name": "…",
      "stale": false,
      "matches": {
        "name": "…",
        "street": "…",
        "postcode": "…",
        "city": "…"
      }
    },
    "country": "…",
    "contact_name": "…"
  },
  "delivery": {
    "name": "…",
    "address": "…",
    "country": "DE"
  },
  "buyer_reference": "…",
  "customer_order_number": "…",
  "customer_order_date": "2026-01-31",
  "customer_id": "00000000-0000-0000-0000-000000000000",
  "customer_number": "…",
  "supplier_number": "…",
  "e_invoice_formats": [
    "xrechnung"
  ],
  "vat_scheme": "standard",
  "vat_exempt_clause": "8",
  "small_business": false,
  "price_mode": "net",
  "language": "de",
  "currency": "EUR",
  "exchange_rate": 0,
  "discount": {
    "type": "percent",
    "value": 0,
    "reason": "…"
  },
  "skonto": {
    "percent": 0,
    "days": 0
  },
  "line_items": [
    {
      "description": "…",
      "quantity": 3,
      "unit": "Std.",
      "unit_price": 120,
      "vat_rate": 19,
      "article_number": "BER-01",
      "vat_exempt_clause": "8"
    }
  ],
  "notes": "…",
  "advances": [
    {
      "invoice_id": "00000000-0000-0000-0000-000000000000",
      "number": "…",
      "date": "2026-01-31",
      "net": 0,
      "vat": 0,
      "gross": 0,
      "vat_groups": [
        {
          "rate": 0,
          "net": 0,
          "vat": 0
        }
      ],
      "paid": false
    }
  ],
  "totals": {
    "lines": 0,
    "discount": 0,
    "net": 0,
    "vat": 0,
    "gross": 0,
    "service": {
      "net": 0,
      "vat": 0,
      "gross": 0
    },
    "prepaid": {
      "net": 0,
      "vat": 0,
      "gross": 0
    },
    "vat_groups": [
      {
        "rate": 0,
        "net": 0,
        "vat": 0
      }
    ]
  },
  "custom_fields": {
    "projekt_nr": "P-17",
    "stripe_customer_id": "cus_Q1w2e3"
  },
  "created_at": "2026-01-31T12:00:00Z",
  "updated_at": "2026-01-31T12:00:00Z"
}

Entwurf bearbeiten

patch/api/v1/invoices/{id}

Ändert Felder an einem Entwurf. Festgeschriebene Belege lehnen das mit 409 ab – außer der Body enthält nur custom_fields (eigene Felder gehören nicht zum Beleg). Scope invoices:draft (oder invoices:write). Statuswechsel (Festschreiben, Bezahlt-Markieren): PATCH /invoices/{id}/status.

Scope

invoices:draft

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.

Request-Body · application/json · erforderlich

{
  "notes": "Zahlbar sofort",
  "payment_term_days": 0
}

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

Antworten

  • 200 OK
  • 400 Ungültiges JSON im Body
  • 401 Kein oder ungültiger API-Key
  • 403 Scope invoices:draft fehlt oder kein Business-Tarif
  • 404 Nicht gefunden
  • 409 Beleg ist festgeschrieben
  • 422 Ungültige Felder im Body
  • 429 Rate Limit überschritten

Schema 200

Beispiel 200

{
  "object": "invoice",
  "id": "00000000-0000-0000-0000-000000000000",
  "type": "invoice",
  "status": "draft",
  "number": "RE-2026-004",
  "invoice_date": "2026-01-31",
  "service_date": "2026-01-31",
  "service_date_end": "2026-01-31",
  "collected_on": "2026-01-31",
  "due_date": "2026-01-31",
  "payment_term_days": 14,
  "amount_paid": 0,
  "amount_open": 428.4,
  "corrected_invoice": {
    "id": "00000000-0000-0000-0000-000000000000",
    "number": "…",
    "date": "2026-01-31"
  },
  "sender": {
    "name": "…",
    "address": "…",
    "tax_id": "…",
    "tax_id_kind": "vat_id",
    "email": "…",
    "bank_name": "…",
    "iban": "…"
  },
  "recipient": {
    "name": "…",
    "address": "…",
    "email": "…",
    "vat_id": "…",
    "vat_id_check": {
      "status": "valid",
      "source": "vies",
      "checked_at": "2026-01-31T12:00:00Z",
      "name": "…",
      "stale": false,
      "matches": {
        "name": "…",
        "street": "…",
        "postcode": "…",
        "city": "…"
      }
    },
    "country": "…",
    "contact_name": "…"
  },
  "delivery": {
    "name": "…",
    "address": "…",
    "country": "DE"
  },
  "buyer_reference": "…",
  "customer_order_number": "…",
  "customer_order_date": "2026-01-31",
  "customer_id": "00000000-0000-0000-0000-000000000000",
  "customer_number": "…",
  "supplier_number": "…",
  "e_invoice_formats": [
    "xrechnung"
  ],
  "vat_scheme": "standard",
  "vat_exempt_clause": "8",
  "small_business": false,
  "price_mode": "net",
  "language": "de",
  "currency": "EUR",
  "exchange_rate": 0,
  "discount": {
    "type": "percent",
    "value": 0,
    "reason": "…"
  },
  "skonto": {
    "percent": 0,
    "days": 0
  },
  "line_items": [
    {
      "description": "…",
      "quantity": 3,
      "unit": "Std.",
      "unit_price": 120,
      "vat_rate": 19,
      "article_number": "BER-01",
      "vat_exempt_clause": "8"
    }
  ],
  "notes": "…",
  "advances": [
    {
      "invoice_id": "00000000-0000-0000-0000-000000000000",
      "number": "…",
      "date": "2026-01-31",
      "net": 0,
      "vat": 0,
      "gross": 0,
      "vat_groups": [
        {
          "rate": 0,
          "net": 0,
          "vat": 0
        }
      ],
      "paid": false
    }
  ],
  "totals": {
    "lines": 0,
    "discount": 0,
    "net": 0,
    "vat": 0,
    "gross": 0,
    "service": {
      "net": 0,
      "vat": 0,
      "gross": 0
    },
    "prepaid": {
      "net": 0,
      "vat": 0,
      "gross": 0
    },
    "vat_groups": [
      {
        "rate": 0,
        "net": 0,
        "vat": 0
      }
    ]
  },
  "custom_fields": {
    "projekt_nr": "P-17",
    "stripe_customer_id": "cus_Q1w2e3"
  },
  "created_at": "2026-01-31T12:00:00Z",
  "updated_at": "2026-01-31T12:00:00Z"
}

Entwurf löschen

delete/api/v1/invoices/{id}

Löscht einen Entwurf endgültig und feuert invoice.deleted. Festgeschriebene Belege lehnen das mit 409 ab — die werden storniert (POST /invoices/{id}/cancellations). Scope invoices:draft (oder invoices:write).

Scope

invoices:draft

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 DELETE "https://maxrechnung.de/api/v1/invoices/{id}" \
  -H "Authorization: Bearer $MXR_API_KEY"

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

Antworten

  • 200 Gelöscht
  • 401 Kein oder ungültiger API-Key
  • 403 Scope invoices:draft fehlt oder kein Business-Tarif
  • 404 Nicht gefunden
  • 409 Beleg ist festgeschrieben
  • 429 Rate Limit überschritten

Schema 200

  • object "invoice"
  • id string · uuid
  • deleted true

Beispiel 200

{
  "object": "invoice",
  "id": "00000000-0000-0000-0000-000000000000",
  "deleted": true
}

Beleg festschreiben

patch/api/v1/invoices/{id}/status

Statusänderung, { "status": … } — keine weiteren Felder. sent: § 14-UStG-Pflichtcheck, danach unveränderlich (Korrekturen über POST /invoices/{id}/corrections). paid gibt es nur in Free und Pro, also mit den Keys des KI-Agenten: Im Business-Tarif ergibt sich der Status aus den Zahlungseingängen, paid wird dort mit 409 abgelehnt, die Zahlung erfasst POST /payments. Öffentliche Keys laufen immer im Business-Tarif. Scope invoices:write.

Scope

invoices:write

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.

Request-Body · application/json · erforderlich

  • status "sent" | "paid"*
{
  "status": "sent"
}

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

Antworten

  • 200 OK
  • 400 Ungültiges JSON oder weitere Felder neben status
  • 401 Kein oder ungültiger API-Key
  • 403 Scope invoices:write fehlt, der Entwurf enthält Angaben, die der Tarif nicht führt (plan_required; Entwurf per PATCH ändern, dabei entfallen sie), oder im Tarif Free ist das Monatslimit festgeschriebener Rechnungen erreicht (ebenfalls plan_required, Feld status; der Entwurf bleibt)
  • 404 Nicht gefunden
  • 409 Status-Rückschritt, paid im Business-Tarif (Zahlung über POST /payments erfassen) oder Entwurf zwischenzeitlich geändert (erneut versuchen)
  • 422 Pflichtangaben nach § 14 UStG unvollständig (details nennt die Felder), oder status ist weder sent noch paid
  • 429 Rate Limit überschritten

Schema 200

Beispiel 200

{
  "object": "invoice",
  "id": "00000000-0000-0000-0000-000000000000",
  "type": "invoice",
  "status": "draft",
  "number": "RE-2026-004",
  "invoice_date": "2026-01-31",
  "service_date": "2026-01-31",
  "service_date_end": "2026-01-31",
  "collected_on": "2026-01-31",
  "due_date": "2026-01-31",
  "payment_term_days": 14,
  "amount_paid": 0,
  "amount_open": 428.4,
  "corrected_invoice": {
    "id": "00000000-0000-0000-0000-000000000000",
    "number": "…",
    "date": "2026-01-31"
  },
  "sender": {
    "name": "…",
    "address": "…",
    "tax_id": "…",
    "tax_id_kind": "vat_id",
    "email": "…",
    "bank_name": "…",
    "iban": "…"
  },
  "recipient": {
    "name": "…",
    "address": "…",
    "email": "…",
    "vat_id": "…",
    "vat_id_check": {
      "status": "valid",
      "source": "vies",
      "checked_at": "2026-01-31T12:00:00Z",
      "name": "…",
      "stale": false,
      "matches": {
        "name": "…",
        "street": "…",
        "postcode": "…",
        "city": "…"
      }
    },
    "country": "…",
    "contact_name": "…"
  },
  "delivery": {
    "name": "…",
    "address": "…",
    "country": "DE"
  },
  "buyer_reference": "…",
  "customer_order_number": "…",
  "customer_order_date": "2026-01-31",
  "customer_id": "00000000-0000-0000-0000-000000000000",
  "customer_number": "…",
  "supplier_number": "…",
  "e_invoice_formats": [
    "xrechnung"
  ],
  "vat_scheme": "standard",
  "vat_exempt_clause": "8",
  "small_business": false,
  "price_mode": "net",
  "language": "de",
  "currency": "EUR",
  "exchange_rate": 0,
  "discount": {
    "type": "percent",
    "value": 0,
    "reason": "…"
  },
  "skonto": {
    "percent": 0,
    "days": 0
  },
  "line_items": [
    {
      "description": "…",
      "quantity": 3,
      "unit": "Std.",
      "unit_price": 120,
      "vat_rate": 19,
      "article_number": "BER-01",
      "vat_exempt_clause": "8"
    }
  ],
  "notes": "…",
  "advances": [
    {
      "invoice_id": "00000000-0000-0000-0000-000000000000",
      "number": "…",
      "date": "2026-01-31",
      "net": 0,
      "vat": 0,
      "gross": 0,
      "vat_groups": [
        {
          "rate": 0,
          "net": 0,
          "vat": 0
        }
      ],
      "paid": false
    }
  ],
  "totals": {
    "lines": 0,
    "discount": 0,
    "net": 0,
    "vat": 0,
    "gross": 0,
    "service": {
      "net": 0,
      "vat": 0,
      "gross": 0
    },
    "prepaid": {
      "net": 0,
      "vat": 0,
      "gross": 0
    },
    "vat_groups": [
      {
        "rate": 0,
        "net": 0,
        "vat": 0
      }
    ]
  },
  "custom_fields": {
    "projekt_nr": "P-17",
    "stripe_customer_id": "cus_Q1w2e3"
  },
  "created_at": "2026-01-31T12:00:00Z",
  "updated_at": "2026-01-31T12:00:00Z"
}

Rechnungskorrektur anlegen

post/api/v1/invoices/{id}/corrections

Erstellt einen Korrektur-Entwurf (Nummernkreis KR-) mit Pflichtbezug auf die festgeschriebene Rechnung {id}. Positionen werden übernommen — für eine Gutschrift die Einzelpreise negativ setzen (PATCH), dann festschreiben.

Scope

invoices:write

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.
  • Idempotency-Key header · stringFrei gewählter Schlüssel, höchstens 255 Zeichen. Eine Wiederholung mit demselben Schlüssel und demselben Body liefert 24 Stunden lang die erste Antwort zurück.
curl -X POST "https://maxrechnung.de/api/v1/invoices/{id}/corrections" \
  -H "Authorization: Bearer $MXR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

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

Antworten

  • 201 Angelegt
  • 401 Kein oder ungültiger API-Key
  • 403 Scope fehlt oder der Tarif reicht nicht (plan_required)
  • 404 Ursprungsrechnung nicht gefunden
  • 409 Ursprung ist noch ein Entwurf oder storniert, oder {id} ist selbst eine Korrektur bzw. ein Stornobeleg — korrigiert und storniert wird nur das Original; die Meldung nennt dessen Nummer
  • 429 Rate Limit überschritten

Schema 201

Beispiel 201

{
  "object": "invoice",
  "id": "00000000-0000-0000-0000-000000000000",
  "type": "invoice",
  "status": "draft",
  "number": "RE-2026-004",
  "invoice_date": "2026-01-31",
  "service_date": "2026-01-31",
  "service_date_end": "2026-01-31",
  "collected_on": "2026-01-31",
  "due_date": "2026-01-31",
  "payment_term_days": 14,
  "amount_paid": 0,
  "amount_open": 428.4,
  "corrected_invoice": {
    "id": "00000000-0000-0000-0000-000000000000",
    "number": "…",
    "date": "2026-01-31"
  },
  "sender": {
    "name": "…",
    "address": "…",
    "tax_id": "…",
    "tax_id_kind": "vat_id",
    "email": "…",
    "bank_name": "…",
    "iban": "…"
  },
  "recipient": {
    "name": "…",
    "address": "…",
    "email": "…",
    "vat_id": "…",
    "vat_id_check": {
      "status": "valid",
      "source": "vies",
      "checked_at": "2026-01-31T12:00:00Z",
      "name": "…",
      "stale": false,
      "matches": {
        "name": "…",
        "street": "…",
        "postcode": "…",
        "city": "…"
      }
    },
    "country": "…",
    "contact_name": "…"
  },
  "delivery": {
    "name": "…",
    "address": "…",
    "country": "DE"
  },
  "buyer_reference": "…",
  "customer_order_number": "…",
  "customer_order_date": "2026-01-31",
  "customer_id": "00000000-0000-0000-0000-000000000000",
  "customer_number": "…",
  "supplier_number": "…",
  "e_invoice_formats": [
    "xrechnung"
  ],
  "vat_scheme": "standard",
  "vat_exempt_clause": "8",
  "small_business": false,
  "price_mode": "net",
  "language": "de",
  "currency": "EUR",
  "exchange_rate": 0,
  "discount": {
    "type": "percent",
    "value": 0,
    "reason": "…"
  },
  "skonto": {
    "percent": 0,
    "days": 0
  },
  "line_items": [
    {
      "description": "…",
      "quantity": 3,
      "unit": "Std.",
      "unit_price": 120,
      "vat_rate": 19,
      "article_number": "BER-01",
      "vat_exempt_clause": "8"
    }
  ],
  "notes": "…",
  "advances": [
    {
      "invoice_id": "00000000-0000-0000-0000-000000000000",
      "number": "…",
      "date": "2026-01-31",
      "net": 0,
      "vat": 0,
      "gross": 0,
      "vat_groups": [
        {
          "rate": 0,
          "net": 0,
          "vat": 0
        }
      ],
      "paid": false
    }
  ],
  "totals": {
    "lines": 0,
    "discount": 0,
    "net": 0,
    "vat": 0,
    "gross": 0,
    "service": {
      "net": 0,
      "vat": 0,
      "gross": 0
    },
    "prepaid": {
      "net": 0,
      "vat": 0,
      "gross": 0
    },
    "vat_groups": [
      {
        "rate": 0,
        "net": 0,
        "vat": 0
      }
    ]
  },
  "custom_fields": {
    "projekt_nr": "P-17",
    "stripe_customer_id": "cus_Q1w2e3"
  },
  "created_at": "2026-01-31T12:00:00Z",
  "updated_at": "2026-01-31T12:00:00Z"
}

Rechnung stornieren

post/api/v1/invoices/{id}/cancellations

Stellt eine Stornorechnung (Nummernkreis ST-) aus, die {id} 1:1 mit umgekehrten Vorzeichen neutralisiert. Die Ursprungsrechnung erhält den Status void. Erhaltene Zahlungen bleiben ihr zugeordnet, amount_open wird negativ (Erstattung offen); die Rückzahlung erfasst POST /payments mit negativem Betrag. Ein Skonto-Ausgleich war kein Geld und wird mit dem Storno storniert (payment.cancelled). Anders als bei der Korrektur ist keine weitere Bearbeitung nötig. Die Antwort ist der Stornobeleg: type: cancellation, ebenfalls status: void (beide Belege sind abgeschlossen), negierte Einzelpreise, corrected_invoice verweist auf die Ursprungsrechnung.

Scope

invoices:write

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.
  • Idempotency-Key header · stringFrei gewählter Schlüssel, höchstens 255 Zeichen. Eine Wiederholung mit demselben Schlüssel und demselben Body liefert 24 Stunden lang die erste Antwort zurück.
curl -X POST "https://maxrechnung.de/api/v1/invoices/{id}/cancellations" \
  -H "Authorization: Bearer $MXR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

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

Antworten

  • 201 Storniert
  • 401 Kein oder ungültiger API-Key
  • 403 Scope fehlt oder der Tarif reicht nicht (plan_required)
  • 404 Ursprungsrechnung nicht gefunden
  • 409 Ursprung ist Entwurf oder bereits storniert, oder {id} ist eine Korrektur bzw. ein Stornobeleg — storniert wird nur das Original; die Meldung nennt dessen Nummer
  • 429 Rate Limit überschritten

Schema 201

Beispiel 201

{
  "object": "invoice",
  "id": "00000000-0000-0000-0000-000000000000",
  "type": "invoice",
  "status": "draft",
  "number": "RE-2026-004",
  "invoice_date": "2026-01-31",
  "service_date": "2026-01-31",
  "service_date_end": "2026-01-31",
  "collected_on": "2026-01-31",
  "due_date": "2026-01-31",
  "payment_term_days": 14,
  "amount_paid": 0,
  "amount_open": 428.4,
  "corrected_invoice": {
    "id": "00000000-0000-0000-0000-000000000000",
    "number": "…",
    "date": "2026-01-31"
  },
  "sender": {
    "name": "…",
    "address": "…",
    "tax_id": "…",
    "tax_id_kind": "vat_id",
    "email": "…",
    "bank_name": "…",
    "iban": "…"
  },
  "recipient": {
    "name": "…",
    "address": "…",
    "email": "…",
    "vat_id": "…",
    "vat_id_check": {
      "status": "valid",
      "source": "vies",
      "checked_at": "2026-01-31T12:00:00Z",
      "name": "…",
      "stale": false,
      "matches": {
        "name": "…",
        "street": "…",
        "postcode": "…",
        "city": "…"
      }
    },
    "country": "…",
    "contact_name": "…"
  },
  "delivery": {
    "name": "…",
    "address": "…",
    "country": "DE"
  },
  "buyer_reference": "…",
  "customer_order_number": "…",
  "customer_order_date": "2026-01-31",
  "customer_id": "00000000-0000-0000-0000-000000000000",
  "customer_number": "…",
  "supplier_number": "…",
  "e_invoice_formats": [
    "xrechnung"
  ],
  "vat_scheme": "standard",
  "vat_exempt_clause": "8",
  "small_business": false,
  "price_mode": "net",
  "language": "de",
  "currency": "EUR",
  "exchange_rate": 0,
  "discount": {
    "type": "percent",
    "value": 0,
    "reason": "…"
  },
  "skonto": {
    "percent": 0,
    "days": 0
  },
  "line_items": [
    {
      "description": "…",
      "quantity": 3,
      "unit": "Std.",
      "unit_price": 120,
      "vat_rate": 19,
      "article_number": "BER-01",
      "vat_exempt_clause": "8"
    }
  ],
  "notes": "…",
  "advances": [
    {
      "invoice_id": "00000000-0000-0000-0000-000000000000",
      "number": "…",
      "date": "2026-01-31",
      "net": 0,
      "vat": 0,
      "gross": 0,
      "vat_groups": [
        {
          "rate": 0,
          "net": 0,
          "vat": 0
        }
      ],
      "paid": false
    }
  ],
  "totals": {
    "lines": 0,
    "discount": 0,
    "net": 0,
    "vat": 0,
    "gross": 0,
    "service": {
      "net": 0,
      "vat": 0,
      "gross": 0
    },
    "prepaid": {
      "net": 0,
      "vat": 0,
      "gross": 0
    },
    "vat_groups": [
      {
        "rate": 0,
        "net": 0,
        "vat": 0
      }
    ]
  },
  "custom_fields": {
    "projekt_nr": "P-17",
    "stripe_customer_id": "cus_Q1w2e3"
  },
  "created_at": "2026-01-31T12:00:00Z",
  "updated_at": "2026-01-31T12:00:00Z"
}

Änderungshistorie (GoBD)

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

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}/audit" \
  -H "Authorization: Bearer $MXR_API_KEY"

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

Antworten

  • 200 Ereignisliste
  • 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 "list"
  • data object[]
    • id string · uuid
    • action "created" | "correction_created" | "cancellation_created" | "edited" | "status_changed" | "payment_added" | "payment_voided" | "payment_edited" | "payment_removed" | "mail_sent" | "recurring_created"correction_created steht am Korrekturbeleg (seine Anlage, detail.corrected_invoice_id) und an der korrigierten Rechnung, sobald eine Korrektur festgeschrieben ist (detail.correction_id, detail.correction_number).
    • label string
    • detail object
    • actor_type "api_key" | "web" | "automation"Womit die Änderung ausgelöst wurde: API-Key, Web-Oberfläche oder Automatik (wiederkehrende Rechnung).
    • actor string · nullableGekürzte Kennung des Auslösers (Key-Prefix bzw. Login-Anfang).
    • at string · date-time

Beispiel 200

{
  "object": "list",
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "action": "created",
      "label": "…",
      "detail": {},
      "actor_type": "api_key",
      "actor": "…",
      "at": "2026-01-31T12:00:00Z"
    }
  ]
}

Empfänger-USt-IdNr. prüfen und festhalten

post/api/v1/invoices/{id}/vat-check

Prüft recipient.vat_id serverseitig (qualifiziert per BZSt, wenn sender.tax_id eine deutsche USt-IdNr. ist, sonst VIES) und schreibt das Ergebnis inkl. Prüf-Schnappschuss nach recipient.vat_id_check. Bodylos. Nur am Entwurf — festgeschriebene Belege frieren die Empfängerangaben ein (dafür GET /check/vat). Antwort ist die aktualisierte Rechnung.

Scope

invoices:draft

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.
  • Idempotency-Key header · stringFrei gewählter Schlüssel, höchstens 255 Zeichen. Eine Wiederholung mit demselben Schlüssel und demselben Body liefert 24 Stunden lang die erste Antwort zurück.
curl -X POST "https://maxrechnung.de/api/v1/invoices/{id}/vat-check" \
  -H "Authorization: Bearer $MXR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

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

Antworten

  • 200 Geprüft, Ergebnis in recipient.vat_id_check
  • 401 Kein oder ungültiger API-Key
  • 403 Scope invoices:draft fehlt
  • 404 Nicht gefunden
  • 409 Beleg ist festgeschrieben
  • 422 recipient.vat_id fehlt oder ist keine EU-USt-IdNr.
  • 429 Rate Limit überschritten
  • 503 Prüfdienst (VIES/BZSt) aktuell nicht erreichbar

Schema 200

Beispiel 200

{
  "object": "invoice",
  "id": "00000000-0000-0000-0000-000000000000",
  "type": "invoice",
  "status": "draft",
  "number": "RE-2026-004",
  "invoice_date": "2026-01-31",
  "service_date": "2026-01-31",
  "service_date_end": "2026-01-31",
  "collected_on": "2026-01-31",
  "due_date": "2026-01-31",
  "payment_term_days": 14,
  "amount_paid": 0,
  "amount_open": 428.4,
  "corrected_invoice": {
    "id": "00000000-0000-0000-0000-000000000000",
    "number": "…",
    "date": "2026-01-31"
  },
  "sender": {
    "name": "…",
    "address": "…",
    "tax_id": "…",
    "tax_id_kind": "vat_id",
    "email": "…",
    "bank_name": "…",
    "iban": "…"
  },
  "recipient": {
    "name": "…",
    "address": "…",
    "email": "…",
    "vat_id": "…",
    "vat_id_check": {
      "status": "valid",
      "source": "vies",
      "checked_at": "2026-01-31T12:00:00Z",
      "name": "…",
      "stale": false,
      "matches": {
        "name": "…",
        "street": "…",
        "postcode": "…",
        "city": "…"
      }
    },
    "country": "…",
    "contact_name": "…"
  },
  "delivery": {
    "name": "…",
    "address": "…",
    "country": "DE"
  },
  "buyer_reference": "…",
  "customer_order_number": "…",
  "customer_order_date": "2026-01-31",
  "customer_id": "00000000-0000-0000-0000-000000000000",
  "customer_number": "…",
  "supplier_number": "…",
  "e_invoice_formats": [
    "xrechnung"
  ],
  "vat_scheme": "standard",
  "vat_exempt_clause": "8",
  "small_business": false,
  "price_mode": "net",
  "language": "de",
  "currency": "EUR",
  "exchange_rate": 0,
  "discount": {
    "type": "percent",
    "value": 0,
    "reason": "…"
  },
  "skonto": {
    "percent": 0,
    "days": 0
  },
  "line_items": [
    {
      "description": "…",
      "quantity": 3,
      "unit": "Std.",
      "unit_price": 120,
      "vat_rate": 19,
      "article_number": "BER-01",
      "vat_exempt_clause": "8"
    }
  ],
  "notes": "…",
  "advances": [
    {
      "invoice_id": "00000000-0000-0000-0000-000000000000",
      "number": "…",
      "date": "2026-01-31",
      "net": 0,
      "vat": 0,
      "gross": 0,
      "vat_groups": [
        {
          "rate": 0,
          "net": 0,
          "vat": 0
        }
      ],
      "paid": false
    }
  ],
  "totals": {
    "lines": 0,
    "discount": 0,
    "net": 0,
    "vat": 0,
    "gross": 0,
    "service": {
      "net": 0,
      "vat": 0,
      "gross": 0
    },
    "prepaid": {
      "net": 0,
      "vat": 0,
      "gross": 0
    },
    "vat_groups": [
      {
        "rate": 0,
        "net": 0,
        "vat": 0
      }
    ]
  },
  "custom_fields": {
    "projekt_nr": "P-17",
    "stripe_customer_id": "cus_Q1w2e3"
  },
  "created_at": "2026-01-31T12:00:00Z",
  "updated_at": "2026-01-31T12:00:00Z"
}

Schemas

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