API-Referenz
Jede Ressource als eigene Seite, serverseitig gerendert. Dort lässt sich jeder Endpunkt direkt mit dem eigenen API-Key ausprobieren.
Alle Endpunkte
Konto
Den API-Key als Verbindungstest prüfen und das zugehörige Konto abfragen.
1 Endpunkt
Rechnungen
Rechnungen und Rechnungskorrekturen anlegen, auflisten, bearbeiten, nach § 14 UStG festschreiben, korrigieren und stornieren.
11 Endpunkte
E-Rechnung & PDF
Zu einer Rechnung das PDF (DIN 5008), XRechnung 3.0.2, ZUGFeRD 2.5.2 / Factur-X und den GiroCode abrufen.
5 Endpunkte
Kunden
Gespeicherte Empfänger anlegen, auflisten, ändern, löschen und deren USt-IdNr. prüfen.
6 Endpunkte
Vorlagen
Positions-Vorlagen, Sets und Rechnungsvorlagen verwalten, eine Rechnung aus einer Vorlage erstellen und Vorlagen in einen Entwurf einfügen (Positions-Vorlagen ab Pro, Sets und Rechnungsvorlagen ab Business).
17 Endpunkte
Angebote, Auftragsbestätigungen, Lieferscheine
Angebote, Auftragsbestätigungen und Lieferscheine anlegen, auflisten, ändern, als PDF abrufen, umwandeln und zu einer Sammelrechnung zusammenfassen (Angebote ab Pro; Auftragsbestätigungen, Lieferscheine und Sammelrechnung ab Business).
10 Endpunkte
Zahlungen
Zahlungseingänge zu einer Rechnung auflisten und erfassen, einen erfassten Eingang berichtigen oder stornieren.
5 Endpunkte
Eigene Felder
Die eigenen Felder des Kontos auflisten. Die Werte stehen als custom_fields an Kunden, Rechnungen und Belegen und lassen sich dort setzen und filtern.
1 Endpunkt
Webhooks
HTTPS-Endpunkte für Ereignis-Benachrichtigungen registrieren, Test-Zustellungen auslösen und Signaturen prüfen.
6 Endpunkte
Prüfungen
Zustandslose USt-IdNr.- und IBAN-Prüfung.
2 Endpunkte
DATEV-Export
DATEV-Buchungsstapel (EXTF-CSV) für einen Zeitraum und die Personenkonten-Stammdaten abrufen.
2 Endpunkte
Authentifizierung
Jeder Request braucht einen API-Key im Header:
Authorization: Bearer mxr_live_…
Keys entstehen in der App unter Einstellungen → API (nur Business-Tarif) und werden dort einmalig angezeigt. Jeder Key trägt Scopes; fehlt der passende, antwortet der Endpunkt mit 403.
| Scope | Erlaubt |
|---|---|
| invoices:read | Rechnungen, Angebote, Auftragsbestätigungen, Lieferscheine und Zahlungseingänge lesen (inkl. PDF/E-Rechnung) |
| invoices:draft | Rechnungen anlegen und Entwürfe ändern, Angebote und weitere Belege anlegen, ändern, weiterführen und löschen – kein Festschreiben, kein Storno, keine Zahlungen |
| invoices:write | Voller Schreibzugriff: zusätzlich festschreiben, stornieren, korrigieren, Zahlungen erfassen |
| customers:read | Kunden lesen |
| customers:write | Kunden anlegen, ändern und löschen |
| templates:read | Vorlagen lesen (Positionen, Sets, Rechnungsvorlagen) |
| templates:write | Vorlagen anlegen, ändern und löschen |
| webhooks:read | Webhook-Endpunkte auflisten, Signaturen prüfen |
| webhooks:write | Webhook-Endpunkte anlegen und löschen, Test-Zustellung senden |
| checks:read | USt-IdNr.- und IBAN-Prüfung (/check/*) |
| datev:read | DATEV-Buchungsstapel herunterladen: Ausgangs- und Eingangsrechnungen samt Namen, Zahlungen (/exports/datev) |
Idempotenz
Jeder POST, der etwas anlegt oder anhängt, wertet den Header Idempotency-Key aus. Eine Wiederholung mit gleichem Body liefert innerhalb von 24 Stunden dieselbe Antwort zurück (Idempotency-Replayed: true), ohne den Vorgang erneut auszuführen; ein abweichender Body zum selben Key ergibt 409, ebenso ein zweiter Request, solange der erste mit dem Key noch läuft. Der Key gilt je API-Key und darf höchstens 255 Zeichen lang sein. PATCH, DELETE, die Test-Zustellung und die Signaturprüfung eines Webhooks werten ihn nicht aus.
Paginierung
limit (1–100, Standard 25) und offset; has_more zeigt an, ob weitere Seiten folgen.
Rate-Limits
Pro Key gilt ein Minutenlimit (Standard 120). Jede Antwort nach der Prüfung des Keys, auch ein Fehler, trägt X-RateLimit-Limit / -Remaining / -Reset; bei Überschreitung 429 mit Retry-After.
Fehler
Immer JSON: { "error": { "code", "message", "details"? } }. Feldfehler stehen in details als { field, message }.
| Code | HTTP | Wann |
|---|---|---|
| unauthorized | 401 | API-Key fehlt, ist ungültig, widerrufen oder abgelaufen. |
| forbidden | 403 | Kein aktiver Business-Tarif oder dem Key fehlt der nötige Scope. |
| plan_required | 403 | Funktion oder Feld liegt über dem Tarif des Kontos (KI-Agent-Keys; x-min-plan je Operation). Die Meldung nennt den nötigen Tarif und den Link zum Wechsel. |
| not_found | 404 | Ressource existiert nicht oder gehört einem anderen Konto. |
| invalid_request | 400 | Body oder Parameter fehlen bzw. sind nicht lesbar. |
| validation_failed | 422 | Felder ungültig — details[] nennt Feld und Grund. |
| conflict | 409 | Zustandskonflikt: festgeschriebener Beleg, vergebene Nummer, Idempotency-Key mit abweichendem Body oder noch laufendem ersten Request. |
| rate_limited | 429 | Minutenlimit des Keys überschritten — Retry-After abwarten. |
| method_not_allowed | 405 | HTTP-Methode auf dieser Route nicht unterstützt — der Header Allow nennt die erlaubten. |
| server_error | 500 | Unerwarteter Fehler. |
| service_unavailable | 503 | Nachgelagerter Dienst nicht erreichbar (VIES/BZSt, ZUGFeRD-Rendering). |