bimetricsEntwickler
Belege

Kostenstelle für mehrere Belege setzen

Als Markdown ansehen

Benötigte Berechtigung:documents:write(Nicht an DATEV exportierte Belege ändern)

Echte Wirkung

Ändert Daten der Firma; wird atomar mit Idempotenzbeleg und Herkunft protokolliert.
post/api/document/bulk/cost-center

Kein Testversand aus der Dokumentation: Dieser Aufruf ist nicht als rein lesend gekennzeichnet. Nutze das Codebeispiel.

Setzt an jedem genannten Beleg eine Kostenstelle oder Verteilung wie der Button „Kostenstelle“ in der Mehrfachauswahl der App; ein leerer String entfernt sie, ohne costCenterId antwortet die Route mit 400. Weil sich kein Betrag ändert, geht das auch bei ausgestellten und bezahlten Belegen. bimetrics bucht jeden geänderten Beleg sofort neu. Übersprungen werden festgeschriebene (finalized), an DATEV exportierte (exported), gelöschte (deleted) und noch nicht gelesene Belege (unread) sowie Belege, die sie schon haben (unchanged); dazu kommen notFound und notPreviewed. Die Kostenstelle festgeschriebener Belege lässt sich einzeln mit PATCH /api/document/{id} trotzdem ändern, solange sie nicht an DATEV exportiert sind; dann storniert bimetrics die Buchungen und bucht sie neu. Eine archivierte oder unbekannte Kostenstelle lehnt die Route für alle Belege ab (409 CostCenterRejected bzw. 404 CostCenterNotFound). Höchstens 50 Belege je Aufruf (400 BulkLimitExceeded). Die Antwort nennt je Beleg, was geschah: change geändert, skipped mit Grund übersprungen, failed mit Code abgelehnt. Das ist ein Teilerfolg wie in der App: Ein abgelehnter Beleg hält die anderen nicht auf, und die Route antwortet mit 200. Mit dryRun ändert sie nichts und zeigt, was geschähe, mit einer version je Beleg. Zum Ausführen gibst du diese als expectedVersions zurück, sonst antwortet die Route mit 400 ExpectedVersionRequired. Es ändert sich nur, was unter change stand und seitdem unverändert ist: Ein geänderter Beleg kommt mit VersionConflict in failed, die übrigen laufen, und ein Beleg ohne Eintrag bleibt mit notPreviewed in skipped. Jeder Beleg läuft als eigener Befehl mit eigenem Eintrag im Protokoll und zählt einzeln auf die Tagesgrenzen der Firma und der Testphase. Der ganze Aufruf zählt einmal auf die Grenzen je Minute. Eine Wiederholung mit gleichem Idempotency-Key ändert nichts doppelt und erledigt, was noch offen ist. Sie klärt auch den Stand, wenn ein Aufruf abbricht: OutcomeUnknown heißt, der Beleg kann schon gebucht sein.

Benötigt einen Schlüssel mit der Berechtigung documents:write.

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

Belege, Kostenstelle und Probelauf

application/json
  1. body

Belege und die Kostenstelle oder Verteilung, die sie bekommen.

costCenterId?|

Pflicht: ID einer Kostenstelle oder Verteilung der Firma, die nicht archiviert ist; ein leerer String entfernt sie.

Muster^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})?$
documentIds?array<>|

IDs der Belege, 1 bis 50.

dryRun?boolean

Nur zeigen, was geschähe; nichts ändern.

expectedVersions?

Ohne dryRun Pflicht: die version aus change eines dryRun je Beleg-ID. Es ändert sich nur, was seitdem unverändert ist; ein Beleg ohne Eintrag bleibt (notPreviewed).

Antworten

Erfolg.

application/json
  1. response

Was mit jedem Beleg geschah oder bei dryRun geschähe.

change?array<>|

Belege, die sich ändern oder geändert haben.

dryRun?boolean

True, wenn nichts geändert wurde.

failed?array<>|

Belege, die der Server abgelehnt hat oder ablehnen würde oder deren Stand er nicht bestätigen konnte. Eine Ablehnung ändert nichts.

notice?string

Der Satz zu einer Grenze, die Belege aufgehalten hat, falls es einen gibt.

reversedFinalizedMonths?array<string>

Monate (YYYY-MM), in denen bimetrics festgeschriebene Buchungen storniert und mit geändertem Datum, Leistungszeitraum, Konto, Steuerkennzeichen oder Betrag neu gebucht hat. Ändert sich nur der Buchungstext oder die Zuordnung, fehlt der Monat. Hast du die Umsatzsteuer-Voranmeldung für einen dieser Monate oder, bei geändertem Datum, für den neuen Monat schon abgegeben, musst du sie womöglich berichtigen. Fehlt, wenn nichts storniert wurde, und bei einer Wiederholung mit demselben Idempotency-Key.

skipped?array<>|

Belege, die bleiben, wie sie sind.

totalMinor?integer

Summe von change in Cent.

Beispielanfrage
curl --fail-with-body "https://app.bimetrics.de/api/document/bulk/cost-center" \  -H "Authorization: Bearer $BIMETRICS_API_KEY" \  -H "Idempotency-Key: rechnung-2026-001" \  -H "Content-Type: application/json" \  -d '{}'
Beispielantwort
{  "change": [    {      "amountMinor": 11900,      "costCenterBefore": "5b0f8c3e-2a71-4d9e-8f16-7c4a9e2d3b58",      "counterparty": "Beispiel Bürobedarf GmbH",      "id": "a129ef0a-da5d-4204-804c-764d751bca95",      "invoiceNumber": "RE-2026-0142"    }  ],  "dryRun": false,  "failed": [],  "skipped": [    {      "id": "a2543540-c7ca-413d-8bcc-1ef3427e8aa4",      "reason": "finalized"    }  ],  "totalMinor": 11900}

Kategorie für mehrere Belege setzen POST

Setzt eine Kategorie auf alle Positionen jedes Belegs, samt dem Steuersatz, den die Kategorie vorgibt, wie „Kategorie setzen“ in der Mehrfachauswahl der App. bimetrics bucht jeden geänderten Beleg sofort neu. Übersprungen werden wie in der App festgeschriebene Belege und ausgestellte Rechnungen (`finalized`), Belege mit mehreren Kategorien (`multiple`), aus Dauerbuchungen oder Vorlagen (`linked`), stornierte (`deleted`), mit erfasster Zahlung (`paid`), noch nicht gelesene (`unread`), Belege, zu deren Art die Kategorie nicht passt (`otherKind`), und Belege ohne Positionen (`other`). Dazu `unchanged`, `notFound` und `notPreviewed`. Ein Beleg kommt in `failed`, wenn `PATCH /api/document/{id}` ihn ablehnen würde, etwa bei einem Steuersatz, den die Kategorie nicht erlaubt. Höchstens 50 Belege je Aufruf (`400 BulkLimitExceeded`). Die Antwort nennt je Beleg, was geschah: `change` geändert, `skipped` mit Grund übersprungen, `failed` mit Code abgelehnt. Das ist ein Teilerfolg wie in der App: Ein abgelehnter Beleg hält die anderen nicht auf, und die Route antwortet mit `200`. Mit `dryRun` ändert sie nichts und zeigt, was geschähe, mit einer `version` je Beleg. Zum Ausführen gibst du diese als `expectedVersions` zurück, sonst antwortet die Route mit `400 ExpectedVersionRequired`. Es ändert sich nur, was unter `change` stand und seitdem unverändert ist: Ein geänderter Beleg kommt mit `VersionConflict` in `failed`, die übrigen laufen, und ein Beleg ohne Eintrag bleibt mit `notPreviewed` in `skipped`. Jeder Beleg läuft als eigener Befehl mit eigenem Eintrag im Protokoll und zählt einzeln auf die Tagesgrenzen der Firma und der Testphase. Der ganze Aufruf zählt einmal auf die Grenzen je Minute. Eine Wiederholung mit gleichem Idempotency-Key ändert nichts doppelt und erledigt, was noch offen ist. Sie klärt auch den Stand, wenn ein Aufruf abbricht: `OutcomeUnknown` heißt, der Beleg kann schon gebucht sein. Benötigt einen Schlüssel mit der Berechtigung `documents:write`.

Kontakt für mehrere Belege setzen POST

Verschiebt Belege zu einem anderen Kontakt, wie „Kontakt ändern“ in der Mehrfachauswahl der App, etwa wenn die Erkennung sie dem falschen Kontakt zugeordnet hat. Jeder Beleg bekommt Name, USt-IdNr., IBAN, Adresse und Nummer des Kontakts wie bei `counterparty.contactId` in `PATCH /api/document/{id}`, und bimetrics bucht ihn sofort auf das Personenkonto des Kontakts um. Liegt eine Buchung in einem festgeschriebenen Monat, storniert bimetrics sie dort und bucht sie neu; `reversedFinalizedMonths` nennt die Monate. Ist ein Beleg einem Bankumsatz zugeordnet, bucht bimetrics die ganze Zuordnung neu. Trägt der Beleg genau die Kostenstelle, die am alten Kontakt für neue Belege hinterlegt ist (`defaultCostCenterId`), oder hat er keine, bekommt er die des neuen Kontakts oder keine. Jede andere bleibt. Übersprungen werden ausgestellte Rechnungen (`issued`, sie bleiben bei dem Kunden, an den sie gingen), an DATEV exportierte Belege, auch über eine Zuordnung (`exported`), Belege aus Dauerbuchungen (`contract`) oder Buchungsvorlagen (`linked`), Belege einer Zuordnung mit weiteren Belegen (`collective`, erst die Zuordnung lösen), Belege mit erfasster Bar- oder Privatzahlung (`paid`), Belege unter „Belegtyp prüfen“ (`kindReview`), Belege, die danach einen Buchungsfehler hätten, etwa Reverse Charge ohne USt-IdNr. am Kontakt (`issues`), noch nicht gelesene (`reading`), stornierte (`deleted`), Belege, die keine Rechnung und kein Eingangsbeleg sind (`otherKind`), und Belege, die schon beim Zielkontakt sind (`unchanged`). Dazu `notFound` und `notPreviewed`. Ein Beleg kommt in `failed`, wenn `PATCH /api/document/{id}` ihn ablehnen würde. Höchstens 50 Belege je Aufruf (`400 BulkLimitExceeded`). Die Antwort nennt je Beleg, was geschah: `change` geändert, `skipped` mit Grund übersprungen, `failed` mit Code abgelehnt. Das ist ein Teilerfolg wie in der App: Ein abgelehnter Beleg hält die anderen nicht auf, und die Route antwortet mit `200`. Mit `dryRun` ändert sie nichts und zeigt, was geschähe, mit einer `version` je Beleg. Zum Ausführen gibst du diese als `expectedVersions` zurück, sonst antwortet die Route mit `400 ExpectedVersionRequired`. Es ändert sich nur, was unter `change` stand und seitdem unverändert ist: Ein geänderter Beleg kommt mit `VersionConflict` in `failed`, die übrigen laufen, und ein Beleg ohne Eintrag bleibt mit `notPreviewed` in `skipped`. Jeder Beleg läuft als eigener Befehl mit eigenem Eintrag im Protokoll und zählt einzeln auf die Tagesgrenzen der Firma und der Testphase. Der ganze Aufruf zählt einmal auf die Grenzen je Minute. Eine Wiederholung mit gleichem Idempotency-Key ändert nichts doppelt und erledigt, was noch offen ist. Sie klärt auch den Stand, wenn ein Aufruf abbricht: `OutcomeUnknown` heißt, der Beleg kann schon gebucht sein. Benötigt einen Schlüssel mit der Berechtigung `documents:write`.