This page is available in German only.

Rechnungs-API für Shops und eigene Systeme

Mit der BelegDock-API stellt dein Shop oder deine Software Rechnungen und Rechnungskorrekturen aus, ohne selbst ein Rechnungsprogramm zu bauen. Du schickst die Beträge der Bestellung, BelegDock vergibt die Rechnungsnummer, erzeugt die E-Rechnung, prüft sie mit dem offiziellen KoSIT-Validator, rendert die PDF in deinem Design, archiviert alles und verschickt es auf Wunsch per E-Mail.

Was du bekommst

• Lückenlose Nummern. Rechnungen und Korrekturen teilen sich einen Nummernkreis pro Jahr (RE-2026-…). Schlägt etwas fehl, wird keine Nummer verbraucht.
• E-Rechnung für Geschäftskunden. Wahlweise eine XRechnung (UBL) plus PDF als Lesekopie oder eine ZUGFeRD-PDF (PDF/A-3 mit eingebettetem XML, Profil EN 16931). Privatkunden erhalten nur die PDF.
• Geprüft, bevor es eine Nummer gibt. Das XML muss den KoSIT-Validator bestehen, bevor der Beleg seine Nummer erhält: die XRechnung nach den XRechnung-Regeln, das ZUGFeRD-XML nach der Norm EN 16931. Die PDF/A-3-Hülle der ZUGFeRD-PDFs prüfen wir in unseren Tests mit dem Mustang-Validator.
• Unveränderbar. Ausgestellte Belege lassen sich weder ändern noch löschen; Fehler korrigierst du mit einer Rechnungskorrektur.
• Dein Design. Logo, Akzentfarbe und eine Fußzeile mit bis zu sechs Zeilen stellst du im Arbeitsbereich ein, nicht pro Anfrage.

So sieht ein Aufruf aus

curl https://belegdock.io/v1/invoices \
  -H "Authorization: Bearer bd_test_..." \
  -H "Content-Type: application/json" \
  -d @bestellung-1001.json

Die Antwort ist 202 Accepted mit dem Beleg im Status queued. Du fragst GET /v1/documents/{id} ab, bis der Status issued, sent oder delivered ist, und lädst dann /pdf und, bei Geschäftskunden, /xml herunter.

Regeln, die deine Integration sicher machen

• Idempotent. external_id ist die dauerhafte ID der Bestellung, etwa die Shopify-Order-GID. Dieselbe ID mit denselben Daten liefert denselben Beleg zurück (200, Idempotent-Replayed: true). Dieselbe ID mit anderen Daten ist ein Fehler (409), kein zweiter Beleg.
• Keine Steuerberechnung. BelegDock rechnet nicht, es prüft: Die Umsatzsteuer jeder Position muss auf den Cent zum Steuersatz passen, die Summen pro Steuersatz exakt. Stimmt etwas nicht, antwortet die API sofort mit 422 und nennt Feld und Regel.
• Fehlerklassen. 422 heißt: Daten ändern. 429 und 5xx heißen: später mit derselben external_id wiederholen.
• Testschlüssel. Mit bd_test_… entstehen Belege mit der Nummer TEST-…, gekennzeichnet als TESTDOKUMENT in PDF und XML. Sie werden nie per E-Mail verschickt und zählen nicht zum Kontingent.

Zugang und Sicherheit

API-Schlüssel legen Inhaber im Arbeitsbereich unter API an; dafür ist die Zwei-Faktor-Anmeldung nötig. BelegDock speichert nur einen Hash des Schlüssels und zeigt ihn genau einmal an. Schlüssel lassen sich jederzeit widerrufen. Ein Schlüssel gilt für genau einen Arbeitsbereich und sieht nur dessen Belege.

Dokumentation

• Interaktive API-Referenz
• OpenAPI-Spezifikation (JSON) zum Erzeugen von Clients, auch im Arbeitsbereich unter API zum Download

Was die API nicht abdeckt

Version 1 stellt Rechnungen für bezahlte Bestellungen aus, in Euro, an Käufer in Deutschland, mit 19 % und 7 % Umsatzsteuer. Abgelehnt werden andere Währungen und Länder, Reverse Charge, innergemeinschaftliche Lieferungen, OSS, Differenzbesteuerung, Kleinunternehmer nach § 19 UStG, Anzahlungsrechnungen und Rechnungen an Behörden mit Leitweg-ID. Mehr dazu im Prüfumfang.