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 im gleichen DATEV-Export.
Das Journal ist dabei kein reines Archiv, sondern ein Freigabeworkflow: Eine Rechnung durchläuft die Status new → in_progress → reviewed → exported. Der DATEV-Sammelexport zieht ausschließlich Rechnungen im Status reviewed – das stellt sicher, dass nur sachlich geprüfte und mit Konten versehene Buchungen exportiert werden.
Eine E-Rechnung kommt herein – als XML oder als ZUGFeRD-PDF. Der Workflow: validieren, ins Journal buchen, sachlich prüfen und freigeben, als DATEV-Buchungsstapel exportieren.
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 sowie der Name des Prüfers hinterlegt. Erst wenn alle drei Pflichtfelder gesetzt sind, kann der Status auf reviewed gesetzt werden – das API erzwingt diese Vollständigkeit und antwortet mit einem Fehler, wenn Felder fehlen.
Der Endpunkt POST /v1/datev/export zieht alle Rechnungen im Status reviewed aus dem Journal, erzeugt daraus einen kombinierten DATEV-EXTF-Buchungsstapel und setzt die exportierten Rechnungen automatisch auf den Status exported. Die CSV wird gleichzeitig im Vault archiviert.
Die erzeugte CSV ist eine DATEV-EXTF-Datei im Format windows-1252 mit zwei Kopfzeilen und einer Buchungszeile pro Rechnungsposition. Sie kann direkt in DATEV Unternehmen online oder den DATEV Buchhalter importiert werden.
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, Gegenkonto und Prüfername setzen, Status auf reviewed setzen.
Identisch zum Rechnungseingang. Der Sammelexport verarbeitet Eingangs- und Ausgangsrechnungen gemeinsam in einem Buchungsstapel – die Buchungsrichtung wird je Rechnung aus dem Journal übernommen.
Die vollständige Referenz aller Endpoints, Parameter und Response-Felder findet sich in der API-Dokumentation.