# Fehlenden Beleg vormerken (https://developer.bimetrics.de/reference/bank-transactions/set-receipt-request)

`PUT https://app.bimetrics.de/api/banktransaction/{id}/receipt-request`

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

Merkt einen Umsatz ohne Beleg als „Beleg vorgemerkt“ vor, mit Tag der Wiedervorlage und optionaler Notiz. Ersetzt einen bestehenden Merker. Der Merker gilt nur, solange der Umsatz keine Zuordnung hat: Sobald der Umsatz zugeordnet wird, egal auf welchem Weg, endet der Merker von selbst. Wird die Zuordnung wieder gelöst, gilt er wieder mit seinem Tag. Ab dem Tag der Wiedervorlage zählt der Umsatz auf der Startseite unter `receipt_requests_due`. Keine Buchung, keine Nachricht an Dritte.

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

Wiedervorlage und Notiz

Schema `ReceiptRequestSet`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `followUpOn` | NaiveDate | Tag der Wiedervorlage, heute bis ein Jahr im Voraus (Europe/Berlin). Ohne Angabe in 14 Tagen. |
| `note` | string | Optionale Notiz, eine Zeile, höchstens 300 Zeichen, zum Beispiel „Rechnung per Mail angefragt“. |

### Beispiel

```sh
curl --fail-with-body "https://app.bimetrics.de/api/banktransaction/{id}/receipt-request" \
  -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`: ReceiptRequestResult |
| 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 |
| 404 | Nicht gefunden (`NotFound`). | `application/json`: Error |
| 409 | Der Umsatz hat schon eine Zuordnung (`ReceiptRequestTransactionAssigned`) oder steht nicht in der Umsatzliste, weil er eine Dublette oder sein Konto gelöscht oder deaktiviert ist (`ReceiptRequestTransactionNotListed`). 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 (`ReceiptRequestResult`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `receiptRequest` | ReceiptRequest | Der Merker; `null`, wenn er entfernt wurde oder nicht mehr gilt. |
| `transactionId` | string (uuid) | ID des Umsatzes. |

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