Offenen Betrag einer Zuordnung als Kursdifferenz buchen
Benötigte Berechtigung:matching:write(Belege und Zahlungen zuordnen)
Echte Wirkung
/api/match/{id}/exchange-differenceKein Testversand aus der Dokumentation: Dieser Aufruf ist nicht als rein lesend gekennzeichnet. Nutze das Codebeispiel.
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.
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).
uuidIdempotency-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 <= 128Die Versionen aus der Vorschau, force über der Grenze (aboveLimit)
application/json- body
Bucht die Kursdifferenz genau so, wie die Vorschau sie zeigt.
expectedVersions?|Vollständige Versionsmap aus previewMatchExchangeDifference, unverändert.
force?booleanNur bei aboveLimit, nachdem der Nutzer bestätigt hat, dass es keine Teilzahlung, kein Skonto und keine falsche Währung ist.
Erfolg.
application/json- response
Die neue Zuordnung und die ersetzte.
match?|Die neue Zuordnung.
replacedMatchId?stringID der ersetzten Zuordnung; sie gibt es danach nicht mehr.
uuidreplayed?booleanTrue bei sicherer Wiederholung eines bereits erfolgreichen Aufrufs.
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.
curl --fail-with-body "https://app.bimetrics.de/api/match/497f6eca-6276-4993-bfeb-53cbbbba6f08/exchange-difference" \ -H "Authorization: Bearer $BIMETRICS_API_KEY" \ -H "Idempotency-Key: rechnung-2026-001" \ -H "Content-Type: application/json" \ -d '{}'{ "match": { "amountOpen": 0, "autoMatch": true, "bankTransactions": [ { "bankTransactionId": "a1ba4b85-5bd8-4cef-bbbd-16eaa2c46033", "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5", "createdAt": "2026-09-12T07:30:15Z", "id": "840529df-2d2a-42ea-afa3-3704d855634f", "matchId": "e21b3d18-17ea-4318-810c-919ec0a94dcb", "updatedAt": "2026-09-12T07:30:15Z" } ], "category": "payment", "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5", "createdAt": "2026-09-12T07:30:15Z", "documents": [ { "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5", "createdAt": "2026-09-12T07:30:15Z", "documentId": "3026096b-614f-40d3-8749-8acf9b529480", "id": "3432135f-5b01-4288-9764-e1ff7d061777", "matchId": "e21b3d18-17ea-4318-810c-919ec0a94dcb", "updatedAt": "2026-09-12T07:30:15Z" } ], "id": "e21b3d18-17ea-4318-810c-919ec0a94dcb", "matchingRule": null, "matchingRuleId": null, "updatedAt": "2026-09-12T07:30:15Z" }, "replacedMatchId": "e21b3d18-17ea-4318-810c-919ec0a94dcb", "replayed": false}Euro-Betrag aus der Zahlung prüfen GET
Sagt, ob sich für den Beleg einer Zuordnung, der in einer Fremdwährung ist und dessen Euro-Betrag fehlt (`documentCurrency` ohne `euroAmountSource`), der Euro-Betrag aus der Zahlung übernehmen lässt, und liefert, was der Nutzer vorher bestätigt: Belegwährung, Betrag vom Beleg, Euro-Betrag der Zahlungen und jede Position vorher und nachher. Nötig sind genau ein Beleg und mindestens ein gebuchter Euro-Umsatz, kein Skonto an der Zuordnung und keine erfassten Zahlungen am Beleg. Passt die Zuordnung nicht, antwortet die API mit `eligible: false`, `refusal` nennt den Code und `refusalReason` den Grund. Verändert nichts. Benötigt einen Schlüssel mit der Berechtigung `read`.
Kursdifferenz einer Zuordnung prüfen GET
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`.