bimetricsEntwickler
Forderungen und Mahnungen

Mehrere Rechnungen auf einmal mahnen

Als Markdown ansehen

Benötigte Berechtigung:invoices:draft(Rechnungsentwürfe verwalten)

Echte Wirkung

Ändert Daten der Firma; wird atomar mit Idempotenzbeleg und Herkunft protokolliert.
post/api/reminder/bulk

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

Stellt für bis zu 25 überfällige Rechnungen je eine Mahnung der nächsten Stufe aus, wie der Mahnlauf in der App: Frist, Text und Mahngebühr aus den Einstellungen der Stufe, Verzugszinsen und Pauschale nach den Schaltern der Firma, Ausstellungsdatum heute. Jede Mahnung bekommt Nummer, Original-PDF und Forderungssnapshot wie bei issueReminder. Keine Buchung, kein Versand. Übersprungen werden stornierte Rechnungen (cancelled), solche mit ungeklärter Zahlung (payment_unknown), bezahlte (settled), mit Mahnsperre (reminder_hold), ohne Fälligkeit (due_date_missing), nicht überfällige (not_overdue), mit laufender Frist einer ausgestellten Mahnung (active_reminder), in den 3 Tagen danach (reminder_wait, siehe remindAgainOn), nach der 3. Mahnung (levels_done) und mit offenem Mahnungsentwurf (open_draft). Dazu not_found und not_previewed. Höchstens 25 Rechnungen je Aufruf (400 BulkLimitExceeded). Die Antwort nennt je Rechnung, was geschah: change ausgestellt, skipped mit Grund übersprungen, failed mit Code abgelehnt. Das ist ein Teilerfolg wie in der App, die Route antwortet mit 200. Mit dryRun stellt sie nichts aus und zeigt Stufe, Frist und Beträge mit einer version je Rechnung. Zum Ausstellen gibst du diese als expectedVersions zurück, sonst antwortet die Route mit 400 ExpectedVersionRequired. Es wird nur ausgestellt, was unter change stand und noch so aussieht: Hat sich eine Rechnung seit dem dryRun geändert, oder wären ihre Beträge heute andere (etwa nach Mitternacht), kommt sie mit VersionConflict in failed; die übrigen laufen. Jede Rechnung läuft als eigener Befehl mit eigenem Eintrag im Protokoll und zählt einzeln auf die Tagesgrenzen der Firma und der Testphase. Ein Idempotency-Key gilt für den ganzen Lauf, auch über mehrere Aufrufe: Eine Wiederholung stellt nichts doppelt aus und erledigt, was noch offen ist. OutcomeUnknown heißt, die Mahnung kann schon ausgestellt sein; eine Wiederholung mit demselben Key klärt das.

Benötigt einen Schlüssel mit der Berechtigung invoices:draft.

Authentifizierung

headerAuthentifizierungBearer <bm_…>

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

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

Rechnungen und Probelauf

application/json
  1. body

Rechnungen, die je eine Mahnung der nächsten Stufe bekommen.

dryRun?boolean

Nur zeigen, was ausgestellt würde; nichts ändern.

expectedVersions?

Ohne dryRun Pflicht: die version aus change eines dryRun je Rechnungs-ID. Ausgestellt wird nur, was noch so aussieht; eine Rechnung ohne Eintrag bleibt (not_previewed).

sourceDraftIds?array<>|

IDs der Rechnungen (sourceDraftId der Forderung), 1 bis 25.

Antworten

Erfolg.

application/json
  1. response

Was mit jeder Rechnung geschah oder bei dryRun geschähe, in der Reihenfolge der Anfrage.

change?array<>|

Mahnungen, die ausgestellt würden oder wurden.

dryRun?boolean

True, wenn nichts ausgestellt wurde.

failed?array<>|

Rechnungen, die der Server abgelehnt hat oder ablehnen würde oder deren Stand er nicht bestätigen konnte. Eine Ablehnung stellt nichts aus.

notice?string

Der Satz zu einer Grenze, die Rechnungen aufgehalten hat, falls es einen gibt.

openMinor?integer

Summe der offenen Beträge von change in Cent.

skipped?array<>|

Rechnungen ohne Mahnung, mit Grund.

totalMinor?integer

Summe der Gesamtbeträge von change in Cent.

Beispielanfrage
curl --fail-with-body "https://app.bimetrics.de/api/reminder/bulk" \  -H "Authorization: Bearer $BIMETRICS_API_KEY" \  -H "Idempotency-Key: rechnung-2026-001" \  -H "Content-Type: application/json" \  -d '{}'
Beispielantwort
{  "change": [    {      "chargesMinor": 528,      "customerName": "Brauhaus Elbwiese GmbH",      "dueDate": {        "day": 15,        "month": 9,        "year": 2026      },      "email": "buchhaltung@example.com",      "feeMinor": 250,      "flatRateMinor": 0,      "hasEmail": true,      "interestMinor": 278,      "issueDate": {        "day": 8,        "month": 10,        "year": 2026      },      "level": 1,      "number": "RE-2026-0142",      "openMinor": 107100,      "paymentDeadline": {        "day": 18,        "month": 10,        "year": 2026      },      "reminderId": "c58b1bf1-a4d7-45a8-944c-c97d54954314",      "reminderNumber": "MA-2026-0012",      "sourceDraftId": "821c3664-640a-4e10-b120-a4ff713532f8",      "title": "1. Mahnung",      "totalMinor": 107628    }  ],  "dryRun": false,  "failed": [],  "openMinor": 107100,  "skipped": [    {      "customerName": "Beispiel Handwerk GmbH",      "number": "RE-2026-0140",      "reason": "reminder_wait",      "sourceDraftId": "4f0d2c9e-7b1a-4e3c-9a5d-8c2b6e1f0a37"    }  ],  "totalMinor": 107628}