API-Referenz

Jede Ressource als eigene Seite, serverseitig gerendert. Dort lässt sich jeder Endpunkt direkt mit dem eigenen API-Key ausprobieren.

Ressourcen

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

Grundlagen

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.

ScopeErlaubt
invoices:readRechnungen, Angebote, Auftragsbestätigungen, Lieferscheine und Zahlungseingänge lesen (inkl. PDF/E-Rechnung)
invoices:draftRechnungen anlegen und Entwürfe ändern, Angebote und weitere Belege anlegen, ändern, weiterführen und löschen – kein Festschreiben, kein Storno, keine Zahlungen
invoices:writeVoller Schreibzugriff: zusätzlich festschreiben, stornieren, korrigieren, Zahlungen erfassen
customers:readKunden lesen
customers:writeKunden anlegen, ändern und löschen
templates:readVorlagen lesen (Positionen, Sets, Rechnungsvorlagen)
templates:writeVorlagen anlegen, ändern und löschen
webhooks:readWebhook-Endpunkte auflisten, Signaturen prüfen
webhooks:writeWebhook-Endpunkte anlegen und löschen, Test-Zustellung senden
checks:readUSt-IdNr.- und IBAN-Prüfung (/check/*)
datev:readDATEV-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 }.

CodeHTTPWann
unauthorized401API-Key fehlt, ist ungültig, widerrufen oder abgelaufen.
forbidden403Kein aktiver Business-Tarif oder dem Key fehlt der nötige Scope.
plan_required403Funktion 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_found404Ressource existiert nicht oder gehört einem anderen Konto.
invalid_request400Body oder Parameter fehlen bzw. sind nicht lesbar.
validation_failed422Felder ungültig — details[] nennt Feld und Grund.
conflict409Zustandskonflikt: festgeschriebener Beleg, vergebene Nummer, Idempotency-Key mit abweichendem Body oder noch laufendem ersten Request.
rate_limited429Minutenlimit des Keys überschritten — Retry-After abwarten.
method_not_allowed405HTTP-Methode auf dieser Route nicht unterstützt — der Header Allow nennt die erlaubten.
server_error500Unerwarteter Fehler.
service_unavailable503Nachgelagerter Dienst nicht erreichbar (VIES/BZSt, ZUGFeRD-Rendering).