Beide Workflows mit der API – Schritt für Schritt · API-Dokumentation
Die API deckt beide Seiten der vorbereitenden Buchhaltung ab: eingehende Rechnungen, die geprüft und gebucht werden müssen, und ausgehende Rechnungen, die erzeugt, gebucht und exportiert werden. Beide Wege laufen durch das gleiche Journal und enden in derselben Übergabe an die Buchhaltung.
Das Journal ist dabei kein reines Archiv, sondern ein Freigabeworkflow: Eine Rechnung durchläuft die Status new → in_progress → done → exported; die Zahlung wird unterwegs als paid vermerkt. Die Übergabe an die Buchhaltung nimmt ausschließlich Rechnungen im Status done mit – so wird nichts weitergereicht, an dem noch jemand arbeitet. Ab exported ist die Rechnung gesperrt und lässt sich nicht mehr ändern. Jeder Statuswechsel wird mit Zeitpunkt und Bearbeiter protokolliert.
Eine E-Rechnung kommt herein – als XML oder als ZUGFeRD-PDF. Der Workflow: validieren, ins Journal buchen, prüfen und abschließen, als ZIP an die Buchhaltung übergeben.
Der Endpunkt POST /v1/assessment nimmt die Datei entgegen, erkennt Format und Standard automatisch und prüft gegen die Schematron-Regeln der EN16931 bzw. der jeweiligen CIUS. Mit dem Parameter archive=vault wird die Rechnung gleichzeitig revisionssicher archiviert und automatisch als neuer Eintrag im Journal angelegt – kein separater API-Call notwendig.
Die Response enthält den Header X-Validation-Assessment mit dem Wert accept oder reject sowie die Journal-ID der neu angelegten Rechnung im Body. Rechnungen mit dem Status reject können trotzdem ins Journal übernommen werden – die Entscheidung, wie mit fehlerhaften Rechnungen umgegangen wird, liegt in der eigenen Anwendungslogik.
Nachdem die Rechnung im Journal liegt, werden Buchungsrichtung, Sachkonto und Gegenkonto hinterlegt. Erst wenn alle drei Pflichtfelder gesetzt sind, kann der Status auf done gesetzt werden – das API erzwingt diese Vollständigkeit und antwortet mit einem Fehler, der die fehlenden Felder benennt.
Der Endpunkt POST /v1/invoices/export/zip bündelt die übergebenen Rechnungen als ZIP-Archiv ihrer Originaldokumente und setzt sie auf den Status exported. Mitgenommen wird nur, was auf done steht; alles andere meldet der Header X-Skipped-Invoices.
Das Archiv enthält die Originale so, wie sie eingegangen oder erzeugt wurden — XML oder ZUGFeRD-PDF, benannt nach der Belegnummer, die jede Rechnung beim Ablegen bekommt. Dazu kommt eine Belegliste als CSV: eine Zeile je Rechnung mit Partner, Beträgen nach Steuersatz, Belegart, Zahldatum, Kostenstelle und der Mitteilung des Mandanten. Sie geht zusätzlich ins Archiv und zählt deshalb als ein Dokument — dafür lässt sich die Übergabe über GET /v1/export/{id} jederzeit unverändert wiederholen, falls das ZIP verlorengeht. Die Kontierung nimmt die Buchhaltung in ihrem eigenen System vor; sie trägt die Verantwortung dafür.
Eine Ausgangsrechnung entsteht aus strukturierten Daten – als JSON oder CSV mit EN16931 Business Terms. Der Workflow: XML oder PDF generieren, ins Journal buchen, freigeben, exportieren. Ab Schritt 2 ist der Ablauf identisch zum Rechnungseingang.
POST /v1/render/xml erzeugt eine konforme XML-Rechnung aus Business-Term-Daten und validiert sie unmittelbar. POST /v1/render/pdf tut dasselbe und liefert zusätzlich ein PDF/A-3 mit eingebettetem XML – also eine fertige ZUGFeRD-Datei. Mit archive=vault wird die Rechnung archiviert und automatisch ins Journal übernommen.
Die Response enthält dieselben X-Validation-* Header wie /v1/assessment. Eine Rechnung, die nicht validiert, wird trotzdem generiert und zurückgegeben – das Validierungsergebnis lässt sich im eigenen System auswerten.
Identisch zum Rechnungseingang – Buchungsrichtung (outgoing), Sachkonto und Gegenkonto setzen, Status auf done setzen.
Identisch zum Rechnungseingang. Ein Archiv kann Eingangs- und Ausgangsrechnungen gemeinsam enthalten.
Die vollständige Referenz aller Endpoints, Parameter und Response-Felder findet sich in der API-Dokumentation.