Kursdifferenz einer Zuordnung prüfen
Benötigte Berechtigung:read(Daten lesen)
Sagt, ob sich der offene Betrag einer Zuordnung als Kursdifferenz buchen lässt, wie „Als Kursdifferenz buchen“ in der App, und liefert, was der Nutzer vorher bestätigt: den offenen Betrag, den Anteil jedes Belegs, die Konten, den EZB-Kurs der Wertstellung und wie weit die Zahlung davon abweicht. Es braucht genau einen gebuchten Euro-Umsatz und Belege einer Richtung, mindestens einen mit Euro-Betrag in Fremdwährung, ohne Skonto, Mahnkosten und erfasste Zahlungen. Belege in Euro behalten ihren Betrag, der Rest verteilt sich auf die Belege in Fremdwährung nach ihrem Wert zum EZB-Kurs. Weicht die Zahlung um mehr als 4,5 % zu Lasten oder 1,5 % zu Gunsten der Firma ab (bis 2 € immer direkt) oder fehlt der EZB-Kurs der Wertstellung, ist aboveLimit gesetzt; nennt die Bank den Betrag in Belegwährung (bankAmountMinor), schon dann, wenn er vom Belegbetrag abweicht: Das kann eine Teilzahlung, Skonto oder eine falsche Währung sein, gebucht wird nur mit force. Passt die Zuordnung nicht, antwortet die API mit eligible: false, refusal und refusalReason. Verändert nichts.
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 Objekts in dieser Firma (UUID).
uuidErfolg.
application/json- response
Ob sich der offene Betrag einer Zuordnung als Kursdifferenz buchen lässt, und was das bucht. Speichert nichts.
aboveLimit?booleanTrue, wenn die Zahlung für die Belege in Fremdwährung mehr als 4,5 % zu Lasten oder mehr als 1,5 % zu Gunsten der Firma von ihrem Wert zum EZB-Kurs abweicht und die Differenz über 2 € liegt, oder wenn es keinen EZB-Kurs gibt. Dann vorher klären, ob es eine Teilzahlung, Skonto oder eine falsche Währung ist; gebucht wird nur mit force.
eligible?booleanTrue, wenn settleMatchExchangeDifference die Kursdifferenz jetzt buchen kann, über der Grenze nur mit force.
exchangeDifference?Was bimetrics buchen würde.
expectedVersions?Für settleMatchExchangeDifference, unverändert.
exportedBookings?booleanTrue, wenn beteiligte Buchungen schon an DATEV exportiert sind. Über die API steht eligible dann auf false. In der App kommt die Kursdifferenz mit dem Datum der Zahlung dazu; DATEV bekommt sie, wenn der Monat der Zahlung noch einmal exportiert wird.
finalizedBookings?booleanTrue, wenn beteiligte Buchungen festgeschrieben sind. Sie bleiben stehen, Storno und Neubuchung entstehen nur, wenn sich für DATEV etwas ändert; die Kursdifferenz ist eine neue Buchung im Monat der Zahlung.
refusal?stringBei eligible: false: der Fehlercode, mit dem der Aufruf abgelehnt würde.
refusalReason?stringBei ExchangeDifferenceNotEligible: noForeignDocument kein Beleg mit Euro-Betrag in Fremdwährung, missingEuroValue ein Beleg hat noch keinen Euro-Betrag (erst umrechnen oder eintragen), payment nicht genau ein gebuchter Euro-Umsatz, settled nichts offen oder schon Skonto, Mahnkosten oder Kursdifferenz gebucht, oder erfasste Zahlungen am Beleg, mixed Belege beider Richtungen, Gutschriften oder Belege aus Vorlagen, cashBasis Ausgangsrechnungen bei Ist-Versteuerung (Euro-Betrag aus der Zahlung übernehmen), rest nach den Belegen in Euro bleibt für die Fremdwährung nichts, rate mehrere Fremdwährungen ohne EZB-Kurs.
"noForeignDocument""missingEuroValue""payment""settled""mixed""cashBasis""rest""rate""aboveLimit"curl --fail-with-body "https://app.bimetrics.de/api/match/497f6eca-6276-4993-bfeb-53cbbbba6f08/exchange-difference-preview" \ -H "Authorization: Bearer $BIMETRICS_API_KEY"{ "aboveLimit": false, "eligible": true, "exchangeDifference": { "deviationBasisPoints": 22, "documents": [ { "currency": "USD", "differenceMinor": -141, "documentId": "a129ef0a-da5d-4204-804c-764d751bca95", "ecbRate": "1.08", "euroMinor": 3571, "foreignMinor": 4000, "invoiceNumber": "INV-2026-1021" } ], "expectedMinor": 3704, "gainAccount": 2661, "lossAccount": 2151, "openMinor": -141, "unfavourable": true, "valueDate": { "day": 6, "month": 11, "year": 2026 } }, "expectedVersions": { "e21b3d18-17ea-4318-810c-919ec0a94dcb": "0e8ca8e3db88d8d5b74c965d0e17598a5909240c88376e0b0a4a23e53ee9356f" }, "exportedBookings": false, "finalizedBookings": false}Offenen Betrag einer Zuordnung als Kursdifferenz buchen POST
Bucht den offenen Betrag einer Zuordnung als Kursdifferenz, ohne die Zuordnung vorher aufzuheben. Rufe das erst auf, wenn der Nutzer die Werte aus `previewMatchExchangeDifference` bestätigt hat. bimetrics ersetzt die Zuordnung in einem Schritt durch eine neue über dieselben Belege und denselben Umsatz; `replacedMatchId` nennt die alte. Die Belege behalten ihren gebuchten Euro-Betrag, die Umsatzsteuer bleibt also richtig. Je Beleg in Fremdwährung bucht bimetrics seinen Anteil auf die Konten für Kursdifferenzen nicht nach § 256a HGB (SKR03 2151/2661, SKR04 6881/4847), ohne Steuer, zum Tag der Zahlung. Der offene Betrag ist danach null. `expectedVersions` kommt unverändert aus `previewMatchExchangeDifference`, `force` nur bei `aboveLimit` nach Bestätigung des Nutzers. Eine Wiederholung mit gleichem Schlüssel bucht nichts erneut. Nicht möglich, wenn die Zuordnung nicht passt oder schon ausgeglichen ist (`422 ExchangeDifferenceNotEligible`) und wenn Buchungen schon an DATEV exportiert sind (`409 FinalizedBookingsLocked`). Andere festgeschriebene Buchungen bleiben stehen; storniert und neu gebucht werden sie nur, wenn sich für DATEV etwas ändert. Benötigt einen Schlüssel mit der Berechtigung `matching:write`.
Zuordnung erweitern POST
Fügt einer Zuordnung Belege oder Umsätze hinzu, etwa eine zweite Teilzahlung, wie „Zuordnung erweitern“ in der App. `documentIds` und `transactionIds` nennen die vollständige neue Auswahl: alle bisherigen Einträge und mindestens einen neuen. bimetrics ersetzt die Zuordnung in einem Schritt durch eine neue mit derselben Kategorie und bucht neu; `replacedMatchId` nennt die alte. `expectedVersions` kommt unverändert aus `previewDeleteMatch`. Nicht möglich mit bestätigtem Skonto (`400 CashDiscountNotEligible`), mit gebuchten Mahnkosten (`422 ReminderChargesNotEligible`), mit einem Beleg aus einer Buchungsvorlage (`409 MatchNotExtendable`) und, wie beim Aufheben, wenn Buchungen schon an DATEV exportiert sind (`409 FinalizedBookingsLocked`). Andere festgeschriebene Buchungen bleiben stehen; storniert und neu gebucht werden sie nur, wenn sich für DATEV etwas ändert, etwa bei einer Sammelzahlung. Benötigt einen Schlüssel mit der Berechtigung `matching:write`.