Mehrere Belege zum Monatskurs umrechnen
Benötigte Berechtigung:documents:write(Nicht an DATEV exportierte Belege ändern)
Echte Wirkung
/api/document/bulk/monthly-rateKein Testversand aus der Dokumentation: Dieser Aufruf ist nicht als rein lesend gekennzeichnet. Nutze das Codebeispiel.
Rechnet jeden genannten Beleg in Fremdwährung, dessen Euro-Betrag fehlt, zum Monatskurs des Bundesfinanzministeriums (§ 16 Abs. 6 UStG) um, wie euroAtMonthlyRate: true in PATCH /api/document/{id}; euroTotalMinor nennt je Beleg den Euro-Betrag danach. Wie die App rechnet die Route nur um, was der Beleg ohne eigenen Hinweis umrechnen würde. Übersprungen werden Belege in Euro oder solche, deren Euro-Betrag schon feststeht (notForeignCurrency), Eingangsbelege mit deutscher Umsatzsteuer, bei denen erst die Steuer in Euro laut Rechnung zu klären ist (askEuroTax), eigene Rechnungen mit deutscher Umsatzsteuer (ownTaxHint, § 14c UStG), Belege, die DATEV schon hat (exported), festgeschriebene (finalized), Belege mit Leistung über den Rechnungsmonat hinaus (billedInAdvance), Gutschriften (credit), Belege mit erfasster Zahlung (paid), gelöschte (deleted), und solche, für die es den Monatskurs noch nicht oder nicht gibt (waiting, late, noRate) oder die sich gerade nicht umrechnen lassen (assignedPayment, cashBasisInvoice, noDate, noPositions, notConvertible, wie reason in GET /api/document/{id}/monthly-rate); dazu kommen notFound und notPreviewed. 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.
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 <= 128Belege und Probelauf
application/json- body
Belege in Fremdwährung, die zum Monatskurs umgerechnet werden.
documentIds?array<>|IDs der Belege, 1 bis 50.
dryRun?booleanNur 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).
Erfolg.
application/json- response
Was mit jedem Beleg geschah oder bei dryRun geschähe.
change?array<>|Belege, die sich ändern oder geändert haben.
dryRun?booleanTrue, 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?stringDer 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?integerSumme von change in Cent.
curl --fail-with-body "https://app.bimetrics.de/api/document/bulk/monthly-rate" \ -H "Authorization: Bearer $BIMETRICS_API_KEY" \ -H "Idempotency-Key: rechnung-2026-001" \ -H "Content-Type: application/json" \ -d '{}'{ "change": [ { "amountMinor": 4000, "counterparty": "Beispiel Cloud Inc.", "euroTotalMinor": 3571, "id": "a129ef0a-da5d-4204-804c-764d751bca95", "invoiceNumber": "INV-2026-0931", "version": "v3" } ], "dryRun": true, "failed": [], "skipped": [ { "id": "a2543540-c7ca-413d-8bcc-1ef3427e8aa4", "reason": "askEuroTax" } ], "totalMinor": 4000}Belegtyp für mehrere Belege setzen POST
Setzt den Belegtyp jedes Belegs, `invoice` (Ausgangsrechnung, Einnahme) oder `receipt` (Eingangsbeleg, Ausgabe), wie die Mehrfachauswahl der App und wie `kind` in `PATCH /api/document/{id}`. Das ist eine Entscheidung: Sie beendet „Belegtyp prüfen“ (`kindReview`), auch wenn der Typ gleich bleibt. bimetrics bucht jeden geänderten Beleg sofort neu. Kategorien bleiben; passt eine nicht zum neuen Typ, zeigt der Beleg einen Buchungsfehler. Nur ein Beleg mit „Belegtyp prüfen“, den seit der Erkennung niemand bearbeitet hat, bekommt bei einem Wechsel neue Kategorien. Übersprungen werden festgeschriebene Belege und ausgestellte Rechnungen (`finalized`), an DATEV exportierte (`exported`), Belege aus Dauerbuchungen oder Vorlagen (`linked`), stornierte (`deleted`), mit erfasster Zahlung (`paid`), noch nicht gelesene (`unread`) und Belege, die den Typ schon haben und nicht auf „Belegtyp prüfen“ warten (`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`.
Duplikate lesen GET
Listet die Duplikat-Einträge der Firma, neueste zuerst: Eine Datei wurde erneut hochgeladen, die die Firma schon hat, und es entstand kein zweiter Beleg. Das sind die Zeilen, die die Belegliste der App als Duplikat zeigt. Benötigt einen Schlüssel mit der Berechtigung `read`.