# Umsatz als Dublette kennzeichnen (https://developer.bimetrics.de/reference/bank-transactions/mark-transaction-duplicate)

`POST https://app.bimetrics.de/api/banktransaction/{id}/mark-duplicate`

operationId: `markTransactionDuplicate` · Berechtigung (Scope): `matching:write` · Bereich: Umsätze

Der Umsatz im Pfad ist der doppelt importierte Umsatz. keepId bleibt als Original erhalten. Offene Buchungen der Dublette entfallen, festgeschriebene bleiben erhalten und bekommen bei Bedarf ein Storno zum ursprünglichen Buchungsdatum. Nur aktive Inhaber können eine Dublette prüfen oder kennzeichnen. Sende keepId und planHash aus der bestätigten Vorschau. Die Dublette verschwindet aus der Umsatzliste. Du kannst das Kennzeichen nicht selbst zurücknehmen. Bei geändertem Plan erneut prüfen und bestätigen.

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 doppelt importierten Umsatzes. |
| `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`)

Bestätigter Plan

Schema `MarkDuplicateRequest`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `keepId` (Pflicht) | string (uuid) | ID des bleibenden Umsatzes. |
| `planHash` (Pflicht) | string | Hash aus der bestätigten Vorschau. |

### Beispiel

```sh
curl --fail-with-body "https://app.bimetrics.de/api/banktransaction/{id}/mark-duplicate" \
  -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`: MarkedDuplicate |
| 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 diesen Endpunkt (`APIKeyPermissionDenied`, `context.scope` nennt sie; Berechtigungen sind fest: neuen Schlüssel anlegen, austauschen, alten widerrufen), der Endpunkt ist für API-Schlüssel nicht freigegeben (`APIKeyPermissionDenied` ohne `context.scope`), oder die Firma hat keinen API-Zugang (mehr), etwa nach Ende der Testphase oder des Abos (`APIUnavailable`). | `application/json`: Error |
| 409 | Die Umsätze passen nicht zusammen, Buchungen sind gesperrt oder der bestätigte Plan hat sich geändert. Bei `TransactionDuplicatePlanChanged` die Vorschau erneut bestätigen. Bei `IdempotencyConflict` wurde der Schlüssel bereits für eine andere Anfrage verwendet. | `application/json`: Error |
| 413 | Die Anfrage ist zu groß (`APIRequestTooLarge`), siehe `x-bimetrics-limits`. | `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 (`MarkedDuplicate`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `id` | string | ID des doppelt importierten Umsatzes. |
| `keepId` | string | ID des bleibenden Umsatzes. |

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