bimetricsEntwickler
Belege

Umrechnung zum Monatskurs prüfen

Als Markdown ansehen

Benötigte Berechtigung:read(Daten lesen)

GET
/api/document/{id}/monthly-rate

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.

Authentifizierung

headerAuthentifizierungBearer <bm_…>

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

Pfadparameter

id*string

ID des Belegs in dieser Firma (UUID).

Formatuuid

Antworten

Erfolg.

application/json
  1. response

Ob und wie ein Beleg in Fremdwährung gerade zum Monatskurs umgerechnet werden kann.

askEuroTax?boolean

Eingangsbeleg 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?string

Bei waiting und late: Ab diesem Zeitpunkt gilt der zuletzt fehlende Monatskurs.

Formatdate-time
bankRateHint?boolean

true, 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?boolean

Eine Leistung endet nach dem Rechnungsmonat; dann gilt der Kurs des Rechnungsmonats.

euroTotalAmount?integer

Bei ready: Euro-Bruttosumme nach der Umrechnung in Cent, bei einer Gutschrift negativ.

exported?boolean

Die 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?boolean

Hochgeladene 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?string

Bei 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?string

Woher referenceRate stammt: monthly (Monatskurs des ersten Eintrags in rates) oder, solange der fehlt, ecb (EZB-Kurs des Rechnungsdatums).

Wert in"monthly""ecb"
referenceRate?string

Mit askEuroTax: der Kurs, mit dem euroTaxAmounts verglichen wird (1 Euro = referenceRate Einheiten, Dezimalzahl als String). Mehr als 3 % Abweichung brauchen acceptRateDeviation.

Muster^-?[0-9]+(\.[0-9]+)?$
Formatdecimal
state?string

ready, waiting, late, noRate oder notEligible.

Wert in"ready""waiting""late""noRate""notEligible"
Beispielanfrage
curl --fail-with-body "https://app.bimetrics.de/api/document/497f6eca-6276-4993-bfeb-53cbbbba6f08/monthly-rate" \  -H "Authorization: Bearer $BIMETRICS_API_KEY"
Beispielantwort
{  "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`.