bimetricsEntwickler
Buchhaltung

DATEV-Export starten und Buchungen festschreiben

Als Markdown ansehen

Benötigte Berechtigung:datev:export(DATEV-Export starten und Buchungen festschreiben)

Echte Wirkung

Ändert Daten der Firma; wird atomar mit Idempotenzbeleg und Herkunft protokolliert.
post/api/export/datev/job

Kein 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.

Authentifizierung

headerAuthentifizierungBearer <bm_…>

Empfohlen: Authorization: Bearer bm_…. Der Schlüssel wird nur einmal angezeigt; nie in URLs, Logs oder Frontend-Code ablegen.

Header-Parameter

Idempotency-Key*string

Stabiler 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.

Muster^[!-~]+$
Länge1 <= length <= 128

Request-Body

Period, parts and the confirmed number of open bookings

application/json
  1. body

Zeitraum und Umfang des DATEV-Exports.

all?boolean

Statt open: festschreiben, was beim Lauf des Exports offen ist, ohne Vergleich mit einer gezählten Zahl. Nur bewusst einsetzen.

bookings?boolean

Buchungsstapel (EXTF): schreibt die offenen Buchungen des Zeitraums fest. Das lässt sich nicht rückgängig machen.

documents?boolean

Belege des Zeitraums als Dateien.

from?string

Erster Tag, YYYY-MM-DD.

onlyNew?boolean

Nur, 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?string

Letzter Tag, YYYY-MM-DD, nicht vor from und im selben Kalenderjahr.

Antworten

Angenommen: Der Auftrag läuft im Hintergrund.

application/json
  1. response

Ein DATEV-Export im Hintergrund.

canCancel?boolean

Ob er sich in der App abbrechen lässt. Per API geht das nur bei waiting.

canDownload?boolean

Ob es eine Datei zum Laden gibt.

createdAt?string

Auftrag gestartet am.

Formatdate-time
downloads?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.

Formatdate-time
files?array<>|

Dateien des fertigen Exports.

finishedAt?|

Beendet am, sonst null.

Formatdate-time
id?string

ID des Exports.

Formatuuid
kind?string

Immer export_datev.

label?unknown

Was exportiert wird: from, to, bookings, documents, protocol, onlyNew und open, die bestätigte Zahl offener Buchungen.

phase?string

Schritt 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.

Formatdate-time
startedBy?|

Wer ihn gestartet hat.

status?string

waiting, 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.

Beispielanfrage
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 '{}'
Beispielantwort
{  "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"}