Alle Anleitungen

MaxRechnung mit n8n verbinden

Vier n8n-Bausteine gegen die REST-API: Kunde anlegen, Rechnung anlegen und festschreiben, alle bezahlten Beträge aufsummieren, überfällige Rechnungen herausfiltern.

10 Min. LesezeitStand 13. Oktober 2026

Voraussetzungen: Business-Tarif (öffentliche API), eine n8n-Instanz (Cloud oder self-hosted)


Inhalt

n8n ruft die öffentliche REST-API von MaxRechnung (/api/v1, Business-Tarif) mit dem HTTP-Request-Node auf: kein eigener Code, keine eigene Server-Anwendung. Diese Anleitung zeigt vier Bausteine, die du einzeln oder kombiniert nutzt:

  1. Kunde anlegen (POST /customers)
  2. Rechnung anlegen und festschreiben (POST /invoices + PATCH /invoices/{id}/status)
  3. Alle bezahlten Beträge abrufen (GET /payments, paginiert, aufsummiert)
  4. Überfällige Rechnungen abrufen (GET /invoices, paginiert, gefiltert)

Voraussetzungen

  • Business-Tarif in MaxRechnung (schaltet die öffentliche API frei). Verlässt das Konto den Business-Tarif, werden alle API-Keys widerrufen. Nach einem erneuten Wechsel zu Business legst du einen neuen Key an und trägst ihn in der Credential ein.
  • Ein API-Key: Einstellungen, Reiter API, Namen eintragen, Scopes anhaken, Key erstellen. Der Key (mxr_live_…) wird einmalig angezeigt.
  • Deine Absenderdaten unter Absender: die API übernimmt sie in jede Rechnung.
  • n8n (Cloud oder self-hosted), Version mit dem HTTP-Request-Node v4+ (Pagination-Optionen).

Nötige Scopes am Key:

BausteinScope
Kunde anlegencustomers:write
Kunde lesencustomers:read
Rechnung anlegen + festschreibeninvoices:write
Zahlungen / Rechnungen leseninvoices:read

Zugangsdaten in n8n hinterlegen

Einmal eine Credential anlegen, dann in jedem HTTP-Request-Node auswählen:

  1. Credentials → New → „Header Auth"
  2. Name: Authorization
  3. Value: Bearer mxr_live_…

Basis-URL für alle Aufrufe: https://maxrechnung.de/api/v1. Fehlerantworten sind immer JSON: { "error": { "code", "message", "details"? } }.

Baustein 1: Kunde anlegen

HTTP Request Node:

FeldWert
MethodPOST
URLhttps://maxrechnung.de/api/v1/customers
AuthenticationGeneric Credential Type → Header Auth (oben)
Send HeadersIdempotency-Key = ={{ $json.email }} (verhindert Doppelanlage bei einem erneuten Lauf)
Send BodyJSON

Body (JSON):

{
  "name": "{{ $json.name }}",
  "address": "{{ $json.street }}\n{{ $json.zip }} {{ $json.city }}",
  "country": "DE",
  "email": "{{ $json.email }}",
  "vat_id": "{{ $json.vat_id }}"
}

Antwort: 201 mit dem Kundenobjekt inkl. id. Diese id ist im nächsten Node als ={{ $json.id }} verfügbar; sie ist aber nicht Pflicht, um eine Rechnung zu schreiben (der Empfänger steht auch inline in der Rechnung).

Baustein 2: Rechnung anlegen und festschreiben

Zwei HTTP-Request-Nodes hintereinander.

2a: Entwurf anlegen

FeldWert
MethodPOST
URLhttps://maxrechnung.de/api/v1/invoices
HeadersIdempotency-Key = ein stabiler Schlüssel je Vorgang, z. B. ={{ $json.order_id }}
BodyJSON (siehe unten)
{
  "invoice_date": "{{ $now.toFormat('yyyy-MM-dd') }}",
  "service_date": "{{ $now.toFormat('yyyy-MM-dd') }}",
  "payment_term_days": 14,
  "price_mode": "net",
  "recipient": {
    "name": "{{ $json.customer_name }}",
    "address": "{{ $json.customer_address }}",
    "email": "{{ $json.customer_email }}"
  },
  "line_items": [
    {
      "description": "{{ $json.item_description }}",
      "quantity": {{ $json.quantity }},
      "unit_price": {{ $json.unit_price }},
      "vat_rate": 19
    }
  ],
  "notes": ""
}
  • price_mode: net (Positionspreise netto) oder gross (brutto).
  • vat_rate je Position: 19, 7 oder 0; musst du selbst setzen.
  • quantity und unit_price sind Zahlen, ohne Anführungszeichen. Ein String endet mit 422.
  • number fehlt mit Absicht: MaxRechnung vergibt die nächste Nummer im Kreis RE-<Jahr>-<laufende Nummer>, zum Beispiel RE-2026-0124. Führst du ein anderes Schema, gib number mit und halte den Zähler in n8n (z. B. per Node „Postgres"/„Airtable"/„n8n Data table"); eine schon vergebene Nummer lehnt die API mit 409 conflict ab.
  • sender fehlt ebenfalls: Name, Anschrift, Steuernummer und Bankverbindung kommen aus Absender in deinem Konto. Felder, die du mitschickst, haben Vorrang.

Antwort: 201 mit dem Rechnungsobjekt inkl. id, number und totals.

2b: Festschreiben

FeldWert
MethodPATCH
URLhttps://maxrechnung.de/api/v1/invoices/{{ $json.id }}/status
BodyJSON: { "status": "sent" }

draft → sent durchläuft den § 14-Vollständigkeitscheck. 422 in der Antwort = ein Pflichtfeld fehlt, details[] nennt es. Danach ist der Beleg unveränderlich (Korrektur: POST /invoices/{id}/corrections).

Baustein 3: Alle bezahlten Beträge abrufen

GET /payments liefert die erfassten Zahlungseingänge, neueste zuerst, seitenweise (limit max. 100, offset, has_more). Jede Seite ist ein Objekt mit den Zahlungen im Feld data.

HTTP Request Node:

FeldWert
MethodGET
URLhttps://maxrechnung.de/api/v1/payments
Query Parameterslimit = 100
Options → PaginationMode: Update a Parameter in Each Request · Type: Query · Name: offset · Value: ={{ $pageCount * 100 }} · Complete when: ={{ $response.body.has_more === false }}

Der Node holt damit alle Seiten. Summe bilden mit einem Code-Node:

// je Seite ein Item: die Zahlungen stehen in data
const rows = $input
  .all()
  .flatMap(i => i.json.data ?? [i.json])
  .filter(p => !p.voided_at); // stornierte Zahlungseingänge zählen nicht
const total = rows.reduce((s, p) => s + Number(p.amount), 0);
// optional: nur ein Zeitraum
// const inRange = rows.filter((p) => p.paid_on >= "2026-01-01" && p.paid_on <= "2026-12-31");
return [{ json: { count: rows.length, total_paid: Math.round(total * 100) / 100 } }];

Stornierte Zahlungseingänge bleiben in der Liste und tragen einen Zeitstempel in voided_at; deshalb der Filter.

Alternativ ohne Code: Node Split Out auf Feld data, ein Filter auf leeres voided_at, dann Summarize → Aggregate sum auf Feld amount.

Jede Zahlung trägt amount, paid_on, invoice_id, note und voided_at; für „bezahlte Beträge je Rechnung" nach invoice_id gruppieren (Summarize → Fields to Split By). Nur die Zahlungen einer Rechnung liefert der Query-Parameter invoice_id.

Baustein 4: Überfällige Rechnungen abrufen

Es gibt keinen fertigen „overdue"-Filter; hol die Rechnungen und filtere über status, due_date und amount_open.

HTTP Request Node:

FeldWert
MethodGET
URLhttps://maxrechnung.de/api/v1/invoices
Query Parameterslimit = 100 · type = invoice
Options → Paginationwie in Baustein 3 (offset = ={{ $pageCount * 100 }}, complete ={{ $response.body.has_more === false }})

Offen sind zwei Status: sent (festgeschrieben, noch nichts bezahlt) und partial (Teilzahlung erfasst). Der Query-Parameter status nimmt nur einen Wert, deshalb filtert der Code-Node:

const today = $now.toFormat("yyyy-MM-dd");
const overdue = $input
  .all()
  .flatMap(i => i.json.data ?? [i.json])
  .filter(inv => ["sent", "partial"].includes(inv.status))
  .filter(inv => inv.due_date && inv.due_date < today && Number(inv.amount_open) > 0)
  .map(inv => ({
    number: inv.number,
    recipient: inv.recipient.name,
    due_date: inv.due_date,
    amount_open: inv.amount_open,
    days_overdue: Math.floor((Date.now() - Date.parse(inv.due_date)) / 86400000),
  }));
return overdue.map(json => ({ json }));

Ohne Code: Node Split Out auf Feld data, dann ein Filter mit drei Bedingungen: ={{ $json.status }} ist sent oder partial, ={{ $json.due_date }} is before ={{ $today }} und ={{ Number($json.amount_open) }} larger 0.

Häng einen Schedule Trigger (täglich) davor und ein Send Email / Slack dahinter, fertig ist die tägliche Mahnliste.

Idempotenz, Rate-Limit, Fehler

  • Anlegen (POST): setz einen Idempotency-Key-Header mit einem pro Vorgang stabilen Wert (Bestell-ID, E-Mail). Ein wiederholter Lauf legt dann nichts doppelt an; MaxRechnung spielt die erste Antwort 24 h zurück. Der Wert gilt je Endpunkt und Body: Derselbe Key an einem anderen Endpunkt endet mit 409. PATCH kennt keinen Idempotency-Key; ein zweites sent auf eine festgeschriebene, noch offene Rechnung antwortet mit 200.
  • Rate-Limit: 120 Requests/Minute je Key. Bei Massenläufen im HTTP-Node Options → Batching (z. B. 50 pro Intervall) setzen. Bei 429 steht die Wartezeit im Header Retry-After.
  • Fehler: Settings → Continue On Fail am Node, danach prüfen: ={{ $json.error?.code }} (validation_failed → Body korrigieren, nicht wiederholen; conflict → z. B. Nummer schon vergeben).

Vollständige Endpunkt- und Feldreferenz: /developers/api. Dort steht zu jedem Endpunkt ein fertiger curl-Aufruf; den übernimmt der HTTP-Request-Node über Import cURL. Die OpenAPI-Spezifikation liegt unter /api/openapi.json.