# Anfrage nach fehlendem Beleg vorbereiten (https://developer.bimetrics.de/reference/bank-transactions/preview-receipt-request-mail)

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

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

Zeigt die Mail, mit der du beim Lieferanten die Rechnung zu einer Zahlung ohne Beleg anforderst: Empfänger ist die E-Mail-Adresse eines Kontakts, nie eine freie Adresse. Ohne `contactId` nimmt bimetrics den Kontakt einer früheren Anfrage, sonst den eindeutigen Kontakt mit der IBAN der Gegenpartei, sonst den eindeutigen Kontakt mit ihrem genauen Namen. Der Body ist optional. `contact.match` sagt, wie er gefunden wurde. `blocked` nennt, warum keine Mail rausgehen kann: `no_contact`, `no_email`, `income` (Zahlungseingang), `assigned` (schon zugeordnet), `not_listed`. Antworten gehen an das Belegpostfach der Firma (`replyTo`). Versendet wird nichts.

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

> **Achtung:** Dieser Aufruf ist nicht als rein lesend gekennzeichnet und kann echte Daten in der Firma anlegen oder ändern. Es gibt keine Testumgebung.
>
> 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. |

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

Kontakt

Schema `ReceiptRequestMailPreviewRequest`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `contactId` | string (uuid) | ID des Kontakts; ohne Angabe sucht bimetrics ihn. |

### Beispiel

```sh
curl --fail-with-body "https://app.bimetrics.de/api/banktransaction/{id}/receipt-request/preview" \
  -H "Authorization: Bearer $BIMETRICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"and","children":[],"limit":50,"offset":0}'
```

### Antworten

| Status | Beschreibung | Inhalt |
| --- | --- | --- |
| 200 | Erfolg. | `application/json`: ReceiptRequestMailPreview |
| 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 (`ReceiptRequestMailPreview`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `blocked` | string | Warum keine Mail rausgehen kann: `no_contact`, `no_email`, `income`, `assigned`, `not_listed`; fehlt, wenn sie rausgehen kann. |
| `body` | string | Text ohne Signatur. |
| `contact` | ReceiptRequestContact | Der Kontakt; `null`, wenn keiner sicher passt. |
| `dailyLimit` | integer | Höchstzahl der Anfragen je Tag. |
| `followUp` | ReceiptRequestFollowUp | Vorschlag für die Erinnerung. |
| `html` | string | Die ganze Mail, wie sie versendet würde. |
| `lastRequest` | DocumentMail | Die letzte Anfrage zu diesem Umsatz; fehlt, wenn noch keine gesendet wurde. |
| `replyTo` | string | Das Belegpostfach der Firma: Antworten mit Rechnung landen dort. |
| `sender` | MailSender | Absender und Versandstand der Firma, wie bei den Belegmails. |
| `sentToday` | integer | Heute versendete Anfragen der Firma. |
| `signature` | string | Signatur unter dem Text. |
| `subject` | string | Betreff. |
| `to` | Array<string>, kann null sein | Empfänger, die E-Mail-Adresse des Kontakts; leer, wenn keine Mail rausgehen kann. |
| `transactionId` | string (uuid) | ID des Umsatzes. |
| `values` | object, kann null sein | Werte der Platzhalter. |

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