DATEV-Export starten und Buchungen festschreiben
Benötigte Berechtigung:datev:export(DATEV-Export starten und Buchungen festschreiben)
Echte Wirkung
/api/export/datev/jobKein Testversand aus der Dokumentation: Dieser Aufruf ist nicht als rein lesend gekennzeichnet. Nutze das Codebeispiel.
Startet den DATEV-Export eines Zeitraums wie in der App, als Auftrag im Hintergrund. Die Antwort ist 202 mit dem Auftrag; getExportJob zeigt, wie weit er ist.
Mit bookings: true schreibt der Export die offenen Buchungen des Zeitraums fest, die er an DATEV gibt. Das lässt sich nicht rückgängig machen: Festgeschriebene Buchungen ändert danach niemand mehr, auch nicht in der App. Eine Korrektur geht nur noch per Storno und Neubuchung. Beide liegen im Monat der alten Buchung und gehen erst an DATEV, wenn dieser Monat noch einmal mit onlyNew: true exportiert wird; ein Export späterer Monate nimmt sie nicht mit. bimetrics sendet nichts an die Kanzlei: Sie bekommt die Buchungen mit der Datei, die du lädst und weitergibst.
Mit bookings: true ist open Pflicht: die Zahl aus countDatevOpenBookings. Stimmt sie beim Start nicht mehr, antwortet bimetrics mit 409 DatevExportChanged. Dieser Aufruf hat nichts festgeschrieben; context.open nennt die neue Zahl. Ist sie kleiner als gezählt, hat vielleicht ein anderer Export des Zeitraums inzwischen festgeschrieben, auch dein eigener früherer Aufruf. Nach einem Netzwerkfehler wiederholst du immer mit demselben Idempotency-Key. Willst du die neue Zahl übernehmen, startest du mit ihr neu, mit einem neuen Idempotency-Key. all: true statt open schreibt fest, was beim Lauf des Exports offen ist, ohne Vergleich mit einer gezählten Zahl.
Läuft schon ein DATEV-Export mit Buchungen, wartet der neue und startet danach von selbst. Startet derselbe Inhaber dasselbe noch einmal, bevor der Auftrag festgeschrieben hat, mit einem seiner Schlüssel oder in der App, kommt dieser Auftrag zurück. Beide Tage liegen im selben Kalenderjahr, sonst antwortet die Route mit 400 DatevExportYears, wie die App. Teile so einen Zeitraum am Jahreswechsel und starte je Kalenderjahr einen eigenen Export. Der Idempotency-Key ist Pflicht (400 IdempotencyKeyRequired); eine Wiederholung mit demselben Key startet nichts doppelt.
Benötigt einen Schlüssel mit der Berechtigung datev:export.
AuthentifizierungBearer <bm_…>Empfohlen: Authorization: Bearer bm_…. Der Schlüssel wird nur einmal angezeigt; nie in URLs, Logs oder Frontend-Code ablegen.
Idempotency-Key*stringStabiler Schlüssel für genau diese Änderung: 1–128 druckbare ASCII-Zeichen ohne Leerzeichen. Bei Wiederholungen denselben Schlüssel und unveränderten Inhalt senden; das Ergebnis wird nicht nochmals erzeugt.
^[!-~]+$1 <= length <= 128Period, parts and the confirmed number of open bookings
application/json- body
Zeitraum und Umfang des DATEV-Exports.
all?booleanStatt open: festschreiben, was beim Lauf des Exports offen ist, ohne Vergleich mit einer gezählten Zahl. Nur bewusst einsetzen.
bookings?booleanBuchungsstapel (EXTF): schreibt die offenen Buchungen des Zeitraums fest. Das lässt sich nicht rückgängig machen.
documents?booleanBelege des Zeitraums als Dateien.
from?stringErster Tag, YYYY-MM-DD.
onlyNew?booleanNur, was DATEV noch nicht bekommen hat, wie „Nur noch nicht exportierte“ in der App, dort vorgewählt. Fehlt onlyNew oder ist es false, enthält der Export alle Buchungen des Zeitraums, auch schon exportierte. Importiert die Kanzlei beide Dateien, stehen sie in DATEV doppelt. Nimm false nur, wenn die Kanzlei den alten Stapel verworfen hat.
open?|Mit bookings Pflicht beim Start, außer mit all: die Zahl offener Buchungen aus countDatevOpenBookings. Beim Zählen ohne Bedeutung.
protocol?booleanÄnderungsprotokoll als CSV (Aenderungsprotokoll.csv): alle Änderungen an den exportierten Belegen, Umsätzen und Zuordnungen.
to?stringLetzter Tag, YYYY-MM-DD, nicht vor from und im selben Kalenderjahr.
Angenommen: Der Auftrag läuft im Hintergrund.
application/json- response
Ein DATEV-Export im Hintergrund.
canCancel?booleanOb er sich in der App abbrechen lässt. Per API geht das nur bei waiting.
canDownload?booleanOb es eine Datei zum Laden gibt.
createdAt?stringAuftrag gestartet am.
date-timedownloads?array<>|Wer welche Datei wann geladen hat.
errorCode?|Bei failed oder cancelled: datev_interrupted heißt, die Buchungen sind festgeschrieben, die Datei aber nicht fertig. Jeder andere Code heißt, nichts ist festgeschrieben, etwa datev_changed (die offenen Buchungen haben sich geändert), storage_full (zu wenig Speicher), tax_rebook_running (bimetrics bucht nach einem Wechsel der Versteuerung neu) oder starter_inactive (wer ihn gestartet hat, gehört nicht mehr zur Firma).
expiresAt?|Tag, an dem die Datei gelöscht wird, sonst null.
date-timefiles?array<>|Dateien des fertigen Exports.
finishedAt?|Beendet am, sonst null.
date-timeid?stringID des Exports.
uuidkind?stringImmer export_datev.
label?unknownWas exportiert wird: from, to, bookings, documents, protocol, onlyNew und open, die bestätigte Zahl offener Buchungen.
phase?stringSchritt eines laufenden Exports: book (bucht, was fehlt), plan (bereitet das Festschreiben vor; erst sein Ende schreibt fest), write (schreibt die Datei; die Buchungen sind festgeschrieben).
progress?Fortschritt des Schritts, sofern er sich zählen lässt.
startedAt?|Lauf begonnen am, sonst null.
date-timestartedBy?|Wer ihn gestartet hat.
status?stringwaiting, running, done, failed, cancelled oder expired (Datei gelöscht).
waitReason?|Warum er wartet: datev_running oder lock:bookings (ein anderer DATEV-Export der Firma läuft), tax_rebook (bimetrics bucht nach einem Wechsel der Versteuerung neu) oder slot (er wartet auf einen freien Platz). Er startet von selbst. Sonst null.
curl --fail-with-body "https://app.bimetrics.de/api/export/datev/job" \ -H "Authorization: Bearer $BIMETRICS_API_KEY" \ -H "Idempotency-Key: rechnung-2026-001" \ -H "Content-Type: application/json" \ -d '{}'{ "canCancel": true, "canDownload": false, "createdAt": "2026-11-03T09:15:00Z", "downloads": [], "errorCode": null, "expiresAt": null, "files": [], "finishedAt": null, "id": "3b9e6f1c-2d4a-4c8e-9f7b-5a1d0e2c4b68", "kind": "export_datev", "label": {}, "phase": "", "progress": { "done": 0, "total": 0 }, "startedAt": null, "startedBy": { "name": "Erika Beispiel", "self": true }, "status": "waiting", "waitReason": "slot"}Zahlungen vor dem DATEV-Export prüfen (Ist-Versteuerung) GET
Nennt für eine Firma mit Ist-Versteuerung die Zahlungen eines Zeitraums, bei denen DATEV die Umsatzsteuer keiner Rechnung zuordnen kann: Zahlungseingänge ohne Zuordnung auf 1590 (SKR03) bzw. 1370 (SKR04) und Zahlungen ohne Rechnungsnummer in Belegfeld 1, weil sie mehrere Rechnungen betreffen. Der Export läuft trotzdem und nennt sie in der `Meldungen.csv`. Bei Soll-Versteuerung, dem Standard, ist `applies` `false` und beide Listen sind leer. Benötigt einen Schlüssel mit der Berechtigung `read`.
Offene Buchungen vor dem DATEV-Export zählen POST
Zählt die offenen, also noch nicht festgeschriebenen Buchungen, die ein DATEV-Export dieses Zeitraums festschreiben würde. Das Zählen selbst schreibt nichts fest. Vorher bucht bimetrics, was noch nicht gebucht ist, so wie der Export selbst. Die Zahl gibst du beim Start als `open` mit. Ändert sich bis dahin etwas, schreibt `startDatevExport` nichts fest und antwortet mit der neuen Zahl. Gezählt wird immer für den Buchungsstapel; `documents`, `protocol`, `open` und `all` sind beim Zählen ohne Bedeutung. Beide Tage liegen im selben Kalenderjahr (sonst `400 DatevExportYears`). Benötigt einen Schlüssel mit der Berechtigung `datev:export`.