Umrechnung zum Monatskurs prüfen
Benötigte Berechtigung:read(Daten lesen)
Sagt für einen Beleg in Fremdwährung mit „Euro-Betrag fehlt“, ob euroAtMonthlyRate in PATCH /api/document/{id} ihn jetzt zum Monatskurs des BMF umrechnen kann, und ändert nichts. ready nennt die Kurse je Monat und die Euro-Summe danach. waiting heißt, der Kurs gilt ab availableFrom: Das BMF gibt ihn am ersten Arbeitstag des Folgemonats bekannt. late: Der Kurs ist überfällig. noRate: Für die Währung gibt es keinen Monatskurs, dann den Euro-Betrag mit euroTotalAmount eintragen. notEligible mit reason, etwa settledPayment (die Zuordnung hat schon Skonto, Mahnkosten oder eine Kursdifferenz gebucht). Ist eine Bankzahlung ohne solchen Ausgleich zugeordnet, rechnet euroAtMonthlyRate trotzdem um; den Rest zur Zahlung bucht danach POST /api/match/{id}/exchange-difference als Kursdifferenz. askEuroTax: Bei deutscher Umsatzsteuer auf einem Eingangsbeleg erst fragen, ob er die Steuer in Euro ausweist; wenn ja, euroTaxAmounts statt euroAtMonthlyRate. exported heißt, die Buchungen sind schon an DATEV gegangen; beim Umrechnen storniert bimetrics dann wie in der App und bucht neu, als Nachtrag (addendaMonths; ein API-Schlüssel braucht dafür documents:correct).
Benötigt einen Schlüssel mit der Berechtigung read.
AuthentifizierungBearer <bm_…>Empfohlen: Authorization: Bearer bm_…. Der Schlüssel wird nur einmal angezeigt; nie in URLs, Logs oder Frontend-Code ablegen.
id*stringID des Belegs in dieser Firma (UUID).
uuidErfolg.
application/json- response
Ob und wie ein Beleg in Fremdwährung gerade zum Monatskurs umgerechnet werden kann.
askEuroTax?booleanEingangsbeleg mit deutscher Umsatzsteuer einer Firma mit Vorsteuerabzug: Erst fragen, ob der Beleg die Steuer in Euro ausweist. Ja: euroTaxAmounts in PATCH /api/document/{id} rechnet zum Kurs der Rechnung um; Nein: der Monatskurs.
availableFrom?stringBei waiting und late: Ab diesem Zeitpunkt gilt der zuletzt fehlende Monatskurs.
date-timebankRateHint?booleantrue, wenn ein Euro-Betrag zum Kurs der Bank hier die Umsatzsteuer ändert: Eingangsbeleg mit deutscher Umsatzsteuer einer Firma mit Vorsteuerabzug oder Eingangsbeleg mit Reverse Charge einer Firma ohne Vorsteuerabzug. Der Kurs der Bank gilt dafür nur, wenn das Finanzamt ihn erlaubt hat (§ 16 Abs. 6 Satz 3 UStG), sonst der Monatskurs. Im zweiten Fall lehnt POST /api/match/{id}/euro-amount mit reverseChargeWithoutInputTax ab.
billedInAdvance?booleanEine Leistung endet nach dem Rechnungsmonat; dann gilt der Kurs des Rechnungsmonats.
euroTotalAmount?integerBei ready: Euro-Bruttosumme nach der Umrechnung in Cent, bei einer Gutschrift negativ.
exported?booleanDie Buchungen des Belegs sind schon an DATEV gegangen. Beim Umrechnen storniert bimetrics dann wie in der App und bucht neu, als Nachtrag; ein API-Schlüssel braucht dafür documents:correct. Es zählen nur die Buchungen des Belegs selbst: Ist nur die zugeordnete Zahlung schon bei DATEV, steht hier false, ein API-Schlüssel braucht fürs Umrechnen aber trotzdem documents:correct.
ownTaxHint?booleanHochgeladene eigene Rechnung mit deutscher Umsatzsteuer: Es gilt der Monatskurs. Steht auf der Rechnung ein höherer Steuerbetrag in Euro, schuldet die Firma diesen (§ 14c Abs. 1 UStG); dann den Bruttobetrag zum Kurs der Rechnung mit euroTotalAmount eintragen.
rates?array<>Bei ready: Kurse je Monat.
reason?stringBei notEligible: notForeignCurrency (kein „Euro-Betrag fehlt“), settledPayment (die Zuordnung zur Bankzahlung hat schon Skonto, Mahnkosten oder eine Kursdifferenz gebucht), cashBasisInvoice (eigene Rechnung bei Ist-Versteuerung), noDate (kein Rechnungs- oder Leistungsdatum), notConvertible (eine Position würde 0 €).
reference?stringWoher referenceRate stammt: monthly (Monatskurs des ersten Eintrags in rates) oder, solange der fehlt, ecb (EZB-Kurs des Rechnungsdatums).
"monthly""ecb"referenceRate?stringMit askEuroTax: der Kurs, mit dem euroTaxAmounts verglichen wird (1 Euro = referenceRate Einheiten, Dezimalzahl als String). Mehr als 3 % Abweichung brauchen acceptRateDeviation.
^-?[0-9]+(\.[0-9]+)?$decimalstate?stringready, waiting, late, noRate oder notEligible.
"ready""waiting""late""noRate""notEligible"curl --fail-with-body "https://app.bimetrics.de/api/document/497f6eca-6276-4993-bfeb-53cbbbba6f08/monthly-rate" \ -H "Authorization: Bearer $BIMETRICS_API_KEY"{ "euroTotalAmount": 812355, "rates": [ { "month": "2026-10", "rate": "1.1202" } ], "state": "ready"}Löschen eines Belegs prüfen GET
Sagt, was `DELETE /api/document/{id}` gerade tun würde, und ändert nichts: `outcome` `deleted` (Beleg, Datei und offene Buchungen verschwinden aus bimetrics, es gibt keinen Papierkorb), `cancelled` (festgeschriebene Buchungen bleiben und werden in ihren Monaten storniert, `reversedFinalizedMonths`, der Beleg bleibt als storniert stehen) oder `retained_copy` (eine hochgeladene Kopie derselben Datei übernimmt, Beleg, Buchungen und Zuordnung bleiben). Geht es nicht, nennt `refusedBecause` den Grund. Sende `version`, `outcome` und `currentRepresentativeId` beim Löschen unverändert mit. Benötigt einen Schlüssel mit der Berechtigung `read`.
Beleg erneut lesen POST
Startet die Erkennung eines Belegs neu, dessen Lesen fehlgeschlagen ist (`ocrStatus` `failed`), wie „Erneut lesen“ in der App. Der Beleg wartet danach sofort wieder (`ocrStatus` `pending`), die Antwort ist der Beleg in diesem Stand. Die Datei bleibt dieselbe, du lädst nichts neu hoch. Das erneute Lesen zählt im Tarif als weiterer Beleg ins Kontingent. Ist der Beleg schon gelesen, wartet er oder wird er gerade gelesen, antwortet die Route mit `409 DocumentReadingNotFailed`, auch beim zweiten Aufruf. Einen von Hand erfassten Beleg lehnt sie mit `409 DocumentReadingManual` ab, einen mit festgeschriebenen Buchungen mit `409 DocumentReadingFinalized` und eine in bimetrics ausgestellte Rechnung mit `409 DocumentReadingIssued`. Idempotency-Key bei Wiederholung unverändert senden. Benötigt einen Schlüssel mit der Berechtigung `upload`.