# Fehlenden Beleg beim Lieferanten anfordern (https://developer.bimetrics.de/reference/bank-transactions/send-receipt-request-mail)

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

operationId: `sendReceiptRequestMail` · Berechtigung (Scope): `mail:send` · Bereich: Umsätze

Sendet die Anfrage an die E-Mail-Adresse des Kontakts, nur nach Bestätigung der Vorschau durch einen Menschen. Absender ist bimetrics mit dem Namen der Firma, Antworten gehen an das Belegpostfach, darunter stehen Signatur und Pflichtangaben, kein Anhang. Betreff und Text gehen genau so raus, wie du sie schickst. Der Umsatz bekommt den Merker (`receiptRequest`) mit der Anfrage, in der App „Beleg angefordert“. Hat der Kontakt keine E-Mail-Adresse, geht keine Mail raus: Der Umsatz ist dann nur vorgemerkt, der Merker bekommt den Hinweis `no_email`, `documentMail` ist `null`. Mit `followUpDays` (7 oder 14) geht danach einmal zwischen 9 und 18 Uhr deutscher Zeit die Erinnerung mit `followUpSubject` und `followUpBody`, solange der Umsatz keine Zuordnung hat, die Anfrage nicht abgewiesen, fehlgeschlagen oder als Spam gemeldet wurde, keine Antwort des Empfängers im Belegpostfach liegt, der Kontakt noch dieselbe E-Mail-Adresse trägt und der Absender aktives Mitglied ist. Je Firma gehen höchstens 10 Anfragen am Tag raus, innerhalb der 20 Empfänger aller Belegmails, in der Testphase 3 (`429 DocumentMailLimitExceeded`, `context.scope` `receipt_request_day` bzw. `company_day`). Ohne eingerichteten Versand antwortet die Route mit `409 DocumentMailNotConfigured`, in der Testphase vor Bestätigung der E-Mail-Adresse mit `403 MailNotConfirmed`. Unumkehrbar. Eine Wiederholung mit gleichem Idempotency-Key sendet nichts doppelt.

Benötigt einen Schlüssel mit der Berechtigung `mail:send`.

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

Bestätigte Anfrage

Schema `ReceiptRequestMailSendRequest`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `body` | string | Text, höchstens 6000 Zeichen. |
| `contactId` | string (uuid) | ID des Kontakts, an dessen E-Mail-Adresse die Anfrage geht. |
| `followUpBody` | string | Text der Erinnerung, wie in der Vorschau bestätigt. |
| `followUpDays` | integer | 0 ohne Erinnerung, sonst 7 oder 14. |
| `followUpOn` | NaiveDate | Tag der Wiedervorlage des Merkers; ohne Angabe der Tag der Erinnerung, ohne Erinnerung in 14 Tagen. |
| `followUpSubject` | string | Betreff der Erinnerung, wie in der Vorschau bestätigt. |
| `subject` | string | Betreff, eine Zeile, höchstens 300 Zeichen. |

### Beispiel

```sh
curl --fail-with-body "https://app.bimetrics.de/api/banktransaction/{id}/receipt-request/send" \
  -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`: ReceiptRequestMailSent |
| 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 | Die Anfrage geht nicht raus: Der Umsatz ist ein Zahlungseingang, schon zugeordnet, nicht in der Liste oder die Funktion ist vorübergehend ausgeschaltet (`ReceiptRequestMailNotPossible`, Grund in `context.reason`), der Kontakt gehört nicht zur Firma (`ReceiptRequestMailContact`), der E-Mail-Versand ist nicht freigeschaltet oder nicht eingerichtet (`DocumentMailDisabled`, `DocumentMailNotConfigured`), oder derselbe `Idempotency-Key` wurde bereits für eine andere Anfrage verwendet (`IdempotencyConflict`). | `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 (`ReceiptRequestMailSent`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `documentMail` | DocumentMail | Die versendete Anfrage im Versandverlauf; `null`, wenn keine Mail rausging. |
| `hint` | string | `no_email`, wenn der Kontakt keine E-Mail-Adresse hat. |
| `receiptRequest` | ReceiptRequest | Der Merker des Umsatzes. |
| `transactionId` | string (uuid) | ID des Umsatzes. |

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