# DATEV-Export starten und Buchungen festschreiben (https://developer.bimetrics.de/reference/accounting/start-datev-export)

`POST https://app.bimetrics.de/api/export/datev/job`

operationId: `startDatevExport` · Berechtigung (Scope): `datev:export` · Bereich: Buchhaltung

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

> **Achtung:** Ändert Daten der Firma; wird atomar mit Idempotenzbeleg und Herkunft protokolliert.
>
> KI-Agenten fragen vor diesem Aufruf beim Nutzer nach.

### Authentifizierung

`Authorization: Bearer bm_…` (alternativ `X-API-KEY: bm_…`, nie beide zugleich).

### Parameter

| Name | Ort | Pflicht | Typ | Beschreibung |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | ja | 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. |

### Request-Body (`application/json`)

Period, parts and the confirmed number of open bookings

Schema `DatevExportRequest`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `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` | integer, kann null sein | 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. |

### Beispiel

```sh
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 '{"kind":"and","children":[],"limit":50,"offset":0}'
```

### Antworten

| Status | Beschreibung | Inhalt |
| --- | --- | --- |
| 202 | Angenommen: Der Auftrag läuft im Hintergrund. | `application/json`: ExportJob |
| 400 | Ungültige Anfrage, z. B. ein Parameter mit ungültigem Wert wie eine ID, die keine UUID ist; korrigieren statt wiederholen. Mehr unter [Fehler](https://developer.bimetrics.de/errors). | `application/json`: Error |
| 401 | Kein gültiger Schlüssel: fehlt (`Unauthorized`), ist unbekannt, abgelaufen oder widerrufen oder wurde nicht in genau einem Header gesendet (`InvalidAPIKey`). Schlüssel prüfen, nicht wiederholen. Auch eine ID, die zu einer anderen Firma gehört, ergibt `401 Unauthorized`. | `application/json`: Error |
| 403 | Dem Schlüssel fehlt die Berechtigung für diese Route (`APIKeyPermissionDenied`), oder die Firma hat keinen API-Zugang (mehr), etwa nach Ende der Testphase oder des Abos (`APIUnavailable`). | `application/json`: Error |
| 409 | Versionskonflikt (`VersionConflict`), abweichender Inhalt für denselben Idempotency-Key (`IdempotencyConflict`), Dublette (`ContactDuplicate`) oder fachlich gesperrte Änderung. Aktuellen Zustand laden und prüfen; keinen anderen Schlüssel verwenden, um einen Konflikt zu umgehen. | `application/json`: Error |
| 413 | Die Anfrage ist zu groß (`APIRequestTooLarge`), siehe `x-bimetrics-limits`. | `application/json`: Error |
| 429 | Zu viele Anfragen; nach `Retry-After` Sekunden erneut senden. Mehr unter [Fehler](https://developer.bimetrics.de/errors). (Header: Retry-After) | `application/json`: Error |
| 500 | Serverfehler; die Anfrage später wiederholen. Mehr unter [Fehler](https://developer.bimetrics.de/errors). | `application/json`: Error |
| 507 | Für diesen Export ist bei bimetrics gerade nicht genug Speicher frei (`ExportStorageFull`). Nichts ist festgeschrieben. Starte den Export später erneut. | `application/json`: Error |

Verschachtelte Schemas stehen vollständig in der OpenAPI-Beschreibung: https://app.bimetrics.de/api/openapi.json
