Mehrere Rechnungen auf einmal mahnen
Benötigte Berechtigung:invoices:draft(Rechnungsentwürfe verwalten)
Echte Wirkung
/api/reminder/bulkKein 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.
AuthentifizierungBearer <bm_…>Empfohlen: Authorization: Bearer bm_…. Der Schlüssel wird nur einmal angezeigt; nie in URLs, Logs oder Frontend-Code ablegen.
Idempotency-Key*stringStabiler 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.
^[!-~]+$1 <= length <= 128Rechnungen und Probelauf
application/json- body
Rechnungen, die je eine Mahnung der nächsten Stufe bekommen.
dryRun?booleanNur 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.
Erfolg.
application/json- 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?booleanTrue, 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?stringDer Satz zu einer Grenze, die Rechnungen aufgehalten hat, falls es einen gibt.
openMinor?integerSumme der offenen Beträge von change in Cent.
skipped?array<>|Rechnungen ohne Mahnung, mit Grund.
totalMinor?integerSumme der Gesamtbeträge von change in Cent.
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 '{}'{ "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}Mahnungsentwurf erstellen POST
Erstellt payment_reminder (Zahlungserinnerung) oder dunning (Mahnung) für eine geeignete ausgestellte Rechnung. expectedReceivableVersion muss dem zuletzt geprüften Forderungsstand entsprechen. Mahngebühr, Verzugszinsen und Pauschale kommen nach den Einstellungen der Firma hinzu, erst ab Verzug und je Mahnung abwählbar. Keine Buchungen oder Nachrichten. Benötigt einen Schlüssel mit der Berechtigung `invoices:draft`.
Mehrere Mahnungs-PDFs als ZIP laden GET
Liefert die gespeicherten Original-PDFs von bis zu 50 ausgestellten oder zurückgezogenen Mahnungen in einer ZIP-Datei, mit denselben Bytes wie downloadReminderPDF. Mehr als 50 IDs: `400 BulkLimitExceeded`. Ist eine Mahnung ein Entwurf, antwortet die Route mit `400`; fehlt eine oder gehört sie zu einer anderen Firma, mit `404`. Dann gibt es keine ZIP-Datei. Es wird nichts versendet. Benötigt einen Schlüssel mit der Berechtigung `sales:read` oder `read`.