bimetricsEntwickler
Umsätze

Fehlenden Beleg beim Lieferanten anfordern

Als Markdown ansehen

Benötigte Berechtigung:mail:send(E-Mails senden)

Echte Wirkung

Ändert Daten der Firma; wird atomar mit Idempotenzbeleg und Herkunft protokolliert.
post/api/banktransaction/{id}/receipt-request/send

Kein Testversand aus der Dokumentation: Dieser Aufruf ist nicht als rein lesend gekennzeichnet. Nutze das Codebeispiel.

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.

Authentifizierung

headerAuthentifizierungBearer <bm_…>

Empfohlen: Authorization: Bearer bm_…. Der Schlüssel wird nur einmal angezeigt; nie in URLs, Logs oder Frontend-Code ablegen.

Pfadparameter

id*string

ID des Umsatzes.

Formatuuid

Header-Parameter

Idempotency-Key*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.

Muster^[!-~]+$
Länge1 <= length <= 128

Request-Body

Bestätigte Anfrage

application/json
  1. body

Die bestätigte Anfrage.

body?string

Text, höchstens 6000 Zeichen.

contactId?string

ID des Kontakts, an dessen E-Mail-Adresse die Anfrage geht.

Formatuuid
followUpBody?string

Text der Erinnerung, wie in der Vorschau bestätigt.

followUpDays?integer

0 ohne Erinnerung, sonst 7 oder 14.

followUpOn?

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.

Antworten

Erfolg.

application/json
  1. response

Das Ergebnis.

documentMail?|

Die versendete Anfrage im Versandverlauf; null, wenn keine Mail rausging.

hint?string

no_email, wenn der Kontakt keine E-Mail-Adresse hat.

receiptRequest?|

Der Merker des Umsatzes.

transactionId?string

ID des Umsatzes.

Formatuuid
Beispielanfrage
curl --fail-with-body "https://app.bimetrics.de/api/banktransaction/497f6eca-6276-4993-bfeb-53cbbbba6f08/receipt-request/send" \  -H "Authorization: Bearer $BIMETRICS_API_KEY" \  -H "Idempotency-Key: rechnung-2026-001" \  -H "Content-Type: application/json" \  -d '{}'
Beispielantwort
{  "documentMail": {    "attachments": [],    "body": "Guten Tag,\n\nzu unserer Zahlung vom 02.11.2026 über 119,00 € liegt uns noch keine Rechnung vor.\n\nViele Grüße\nMuster Studio",    "cc": [],    "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5",    "createdAt": "2026-11-21T09:30:00Z",    "createdByUserCompanyId": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",    "customerName": "Demodruckerei",    "documentKind": "receipt_request",    "id": "3e0c7a52-1f4b-4c8d-9e2a-6b7c8d9e0f1b",    "number": "",    "recipientCount": 1,    "recipients": [      {        "address": "rechnung@demodruckerei.example",        "channel": "to",        "status": "queued"      }    ],    "replyTo": "a1b2c3d4@mail.bimetrics.de",    "senderAddress": "versand@rechnungen.bimetrics.de",    "senderName": "Muster Studio",    "status": "queued",    "subject": "Rechnung zu unserer Zahlung vom 02.11.2026",    "targetId": "a1ba4b85-5bd8-4cef-bbbd-16eaa2c46033",    "targetKind": "receipt_request",    "to": [      "rechnung@demodruckerei.example"    ],    "updatedAt": "2026-11-21T09:30:00Z"  },  "receiptRequest": {    "due": false,    "followUpOn": {      "day": 28,      "month": 11,      "year": 2026    },    "requestMail": {      "contactName": "Demodruckerei",      "followUp": "scheduled",      "followUpOn": {        "day": 28,        "month": 11,        "year": 2026      },      "id": "3e0c7a52-1f4b-4c8d-9e2a-6b7c8d9e0f1b",      "sentAt": "2026-11-21T09:30:00Z",      "status": "queued",      "to": [        "rechnung@demodruckerei.example"      ]    },    "requestedAt": "2026-11-21T09:30:00Z"  },  "transactionId": "a1ba4b85-5bd8-4cef-bbbd-16eaa2c46033"}