# Offenen Betrag einer Zuordnung als Kursdifferenz buchen (https://developer.bimetrics.de/reference/matches/settle-match-exchange-difference)

`POST https://app.bimetrics.de/api/match/{id}/exchange-difference`

operationId: `settleMatchExchangeDifference` · Berechtigung (Scope): `matching:write` · Bereich: Zuordnungen

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`.

> **Achtung:** Ändert Daten der Firma; wird atomar mit Idempotenzbeleg und Herkunft protokolliert.
>
> KI-Agenten fragen vor diesem Aufruf beim Nutzer nach.

### Authentifizierung

`Authorization: Bearer bm_…` (alternativ `X-API-KEY: bm_…`, nie beide zugleich).

### Parameter

| Name | Ort | Pflicht | Typ | Beschreibung |
| --- | --- | --- | --- | --- |
| `id` | path | ja | string (uuid) | ID des Objekts in dieser Firma (UUID). |
| `Idempotency-Key` | header | ja | string | Stabiler 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. |

### Request-Body (`application/json`)

Die Versionen aus der Vorschau, force über der Grenze (aboveLimit)

Schema `ExchangeDifferenceRequest`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `expectedVersions` | object, kann null sein | Vollständige Versionsmap aus `previewMatchExchangeDifference`, unverändert. |
| `force` | boolean | Nur bei `aboveLimit`, nachdem der Nutzer bestätigt hat, dass es keine Teilzahlung, kein Skonto und keine falsche Währung ist. |

### Beispiel

```sh
curl --fail-with-body "https://app.bimetrics.de/api/match/{id}/exchange-difference" \
  -H "Authorization: Bearer $BIMETRICS_API_KEY" \
  -H "Idempotency-Key: rechnung-2026-001" \
  -H "Content-Type: application/json" \
  -d '{"kind":"and","children":[],"limit":50,"offset":0}'
```

### Antworten

| Status | Beschreibung | Inhalt |
| --- | --- | --- |
| 200 | Erfolg. | `application/json`: ExtendMatchResult |
| 400 | Ungültige Anfrage, z. B. ein Parameter mit ungültigem Wert wie eine ID, die keine UUID ist; korrigieren statt wiederholen. Mehr unter [Fehler](https://developer.bimetrics.de/errors). | `application/json`: Error |
| 401 | Kein gültiger Schlüssel: fehlt (`Unauthorized`), ist unbekannt, abgelaufen oder widerrufen oder wurde nicht in genau einem Header gesendet (`InvalidAPIKey`). Schlüssel prüfen, nicht wiederholen. Auch eine ID, die zu einer anderen Firma gehört, ergibt `401 Unauthorized`. | `application/json`: Error |
| 403 | Dem Schlüssel fehlt die Berechtigung für diese Route (`APIKeyPermissionDenied`), oder die Firma hat keinen API-Zugang (mehr), etwa nach Ende der Testphase oder des Abos (`APIUnavailable`). | `application/json`: Error |
| 404 | Nicht gefunden (`NotFound`). | `application/json`: Error |
| 409 | Versionskonflikt (`VersionConflict`), abweichender Inhalt für denselben Idempotency-Key (`IdempotencyConflict`), Dublette (`ContactDuplicate`) oder fachlich gesperrte Änderung. Aktuellen Zustand laden und prüfen; keinen anderen Schlüssel verwenden, um einen Konflikt zu umgehen. | `application/json`: Error |
| 413 | Die Anfrage ist zu groß (`APIRequestTooLarge`), siehe `x-bimetrics-limits`. | `application/json`: Error |
| 422 | Der offene Betrag lässt sich nicht als Kursdifferenz buchen, die Zuordnung ist schon ausgeglichen, oder die Abweichung liegt ohne `force` über der Grenze (über 4,5 % zu Lasten oder 1,5 % zu Gunsten der Firma, ohne EZB-Kurs der Wertstellung, bei mehreren Fremdwährungen ohne Kurs gar nicht) (`ExchangeDifferenceNotEligible`). Das Detail nennt den Grund. Die Zuordnung bleibt unverändert. | `application/json`: Error |
| 429 | Zu viele Anfragen; nach `Retry-After` Sekunden erneut senden. Mehr unter [Fehler](https://developer.bimetrics.de/errors). (Header: Retry-After) | `application/json`: Error |
| 500 | Serverfehler; die Anfrage später wiederholen. Mehr unter [Fehler](https://developer.bimetrics.de/errors). | `application/json`: Error |

#### Felder der Antwort 200 (`ExtendMatchResult`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `match` | Match | Die neue Zuordnung. |
| `replacedMatchId` | string (uuid) | ID der ersetzten Zuordnung; sie gibt es danach nicht mehr. |
| `replayed` | boolean | True 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. |

Verschachtelte Schemas stehen vollständig in der OpenAPI-Beschreibung: https://app.bimetrics.de/api/openapi.json
