bimetricsEntwickler
Forderungen und Mahnungen

Mahnsperre setzen

Als Markdown ansehen

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

Echte Wirkung

Ändert Daten der Firma; wird atomar mit Idempotenzbeleg und Herkunft protokolliert.
put/api/receivable/{id}/reminder-hold

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

Sperrt die Rechnung für Mahnungen, mit optionalem Grund und letztem Tag (until, einschließlich, Europe/Berlin). Ersetzt eine bestehende Sperre. Solange sie gilt: canRemind=false, reminderBlockReason=reminder_hold, nicht in review=reminders; Anlegen und Ausstellen einer Mahnung antworten mit 409 ReminderNotAllowed. Keine Buchung, keine Nachricht; Verzug und Zinsen laufen weiter.

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.

Pfadparameter

id*string

ID des Objekts dieser Firma (UUID); bei Forderungsständen und neuen Korrekturen die Quellentwurfs-ID.

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

application/json
  1. body

Mahnsperre setzen oder ersetzen.

reason?string

Optionaler Grund, eine Zeile, höchstens 200 Zeichen, zum Beispiel „Kunde zahlt bis 20.11.“.

until?

Optionaler letzter Tag der Sperre, heute oder später (Europe/Berlin). Ohne Angabe gilt sie, bis du sie aufhebst.

Antworten

Erfolg.

application/json
  1. response

Abgeleiteter Forderungsstand der Originalrechnung; kein zweites Buchungsmodell. Geldwerte in EUR-Cent.

activeReminder?

Ausgestellte Mahnung, deren Zahlungsfrist noch läuft; fehlt, wenn keine läuft. Solange sie läuft, steht die Rechnung nicht in der Prüfliste review=reminders.

canCorrect?boolean

Für das Original ist eine weitere Rechnungskorrektur möglich.

canRemind?boolean

Aktuelle Forderung darf gemahnt werden. Eine laufende Mahnung (activeReminder) sperrt nicht, eine Mahnsperre (reminderHold) schon.

cancellationBlockReason?string

Maschinenlesbarer Grund, warum ein Storno abgelehnt wird: cancelled (schon storniert), corrected (per Gutschrift gemindert), paid (bezahlt) oder matched (eine Zahlung ist zugeordnet). Fehlt, solange ein Storno möglich ist.

correctableMinor?integer

Noch korrigierbarer Bruttobetrag in Cent, unabhängig vom Zahlungsstand.

correctedMinor?integer

Summe ausgestellter, nicht aufgehobener Korrekturen in Cent.

correctionBlockReason?string

Maschinenlesbarer Grund, wenn canCorrect false ist: cancelled, fully_corrected, no_amount (Rechnung über 0 € oder weniger), cash_discount, reminder_charges oder booking_error. Fehlt, solange eine Gutschrift möglich ist.

currency?string

Währung EUR.

customerName?string

Name des Rechnungsempfängers.

dueDate?|

Fälligkeitsdatum; null, falls nicht vorhanden.

invoiceDate?|

Rechnungsdatum des Originals.

lastPaymentOn?

Datum der jüngsten Zahlung: Wertstellung der zugeordneten Banktransaktion oder Datum einer erfassten Zahlung; fehlt ohne Zahlung.

lastPaymentTransactionId?string

ID der Banktransaktion dieser Zahlung; fehlt bei einer erfassten Zahlung.

Formatuuid
nextReminderLevel?integer

Die vorgeschlagene nächste Stufe, solange canRemind gilt: eins über der höchsten ausgestellten, zurückgezogene zählen nicht. Fehlt nach Stufe 3.

number?string

Nummer der Originalrechnung.

openMinor?integer

Aktuell offener Betrag in Cent; nur bei paymentKnown=true aussagekräftig.

originalGrossMinor?integer

Ursprünglicher Bruttobetrag in Cent.

paidMinor?integer

Eindeutig zugeordnete bzw. dokumentierte Zahlung in Cent; nur bei paymentKnown=true aussagekräftig.

paymentKnown?boolean

Zahlungen sind eindeutig zuordenbar. Bei false keine zahlungsabhängigen Nullwerte als tatsächlichen Nullbetrag interpretieren.

receivableVersion?string

Digest des aktuellen Forderungsstands; unverändert als expectedReceivableVersion senden.

refundDueMinor?integer

Guthaben des Kunden bei Überzahlung in Cent, keine ausgeführte Auszahlung; nur bei paymentKnown=true aussagekräftig.

remindAgainOn?

Erster Tag, an dem die Prüfliste review=reminders die Rechnung wieder vorschlägt: späteste Zahlungsfrist ihrer ausgestellten Mahnungen plus 3 Tage, weil Zahlungen nachlaufen (Europe/Berlin). Fehlt ab diesem Tag und ohne ausgestellte Mahnung. Nur aussagekräftig, solange die Rechnung offen und mahnbar ist (canRemind): bezahlte, stornierte oder gesperrte Rechnungen schlägt die Prüfliste nicht vor. canRemind bleibt davon unberührt.

reminderBlockReason?string

Maschinenlesbarer Grund einer gesperrten Mahnung: cancelled, payment_unknown, settled, reminder_hold, due_date_missing oder not_overdue.

reminderHold?

Mahnsperre, die heute gilt; fehlt ohne.

sourceDocumentId?string

ID des ausgestellten Originalbelegs.

Formatuuid
sourceDraftId?string

ID des Originalrechnungsentwurfs.

Formatuuid
sourceLayoutId?string

Gespeichertes Layout der Originalrechnung: modern oder classic. Ältere Rechnungen ohne Layoutangabe verwenden modern.

sourceVersion?string

Aktueller updatedAt-Wert des Originalentwurfs.

Formatdate-time
Beispielanfrage
curl --fail-with-body "https://app.bimetrics.de/api/receivable/497f6eca-6276-4993-bfeb-53cbbbba6f08/reminder-hold" \  -H "Authorization: Bearer $BIMETRICS_API_KEY" \  -H "Idempotency-Key: rechnung-2026-001" \  -H "Content-Type: application/json" \  -d '{}'
Beispielantwort
{  "canCorrect": true,  "canRemind": false,  "correctableMinor": 178500,  "correctedMinor": 0,  "currency": "EUR",  "customerName": "Brauhaus Elbwiese GmbH",  "dueDate": {    "day": 15,    "month": 9,    "year": 2026  },  "invoiceDate": {    "day": 1,    "month": 9,    "year": 2026  },  "number": "RE-2026-0142",  "openMinor": 107100,  "originalGrossMinor": 178500,  "paidMinor": 71400,  "paymentKnown": true,  "receivableVersion": "0e8ca8e3db88d8d5b74c965d0e17598a5909240c88376e0b0a4a23e53ee9356f",  "refundDueMinor": 0,  "reminderBlockReason": "reminder_hold",  "reminderHold": {    "reason": "Kunde zahlt bis 20.11.",    "source": "invoice",    "until": {      "day": 20,      "month": 11,      "year": 2026    }  },  "sourceDocumentId": "3026096b-614f-40d3-8749-8acf9b529480",  "sourceDraftId": "821c3664-640a-4e10-b120-a4ff713532f8",  "sourceLayoutId": "classic",  "sourceVersion": "2026-09-01T08:01:02.123456Z"}

Mahnsperre aufheben DELETE

Hebt die eigene Sperre der Rechnung auf; ohne Sperre bleibt alles unverändert. Steht der Kontakt auf „Nicht mahnen“ (noReminders), bleibt die Rechnung gesperrt. Benötigt einen Schlüssel mit der Berechtigung `invoices:draft`.

Nächste Mahnung einer Rechnung als PDF ansehen GET

Zeigt die Mahnung, die runReminders für diese Rechnung jetzt ausstellen würde, als PDF und Bildseiten. Stufe, Frist, Text und Mahngebühr kommen aus den Einstellungen der Stufe, Verzugszinsen und Pauschale aus den Schaltern der Firma. Ausstellungsdatum ist heute, das Layout ist das für neue Mahnungen. Die Nummer fehlt noch, sie entsteht beim Ausstellen; das PDF trägt den Vermerk ENTWURF. `item` ist die Zeile wie in `change` eines `dryRun`, mit derselben `version`. Bekäme die Rechnung im Lauf keine Mahnung, antwortet die Route mit `409 ReminderNotAllowed`, `context.reason` nennt den Grund wie `skipped.reason`. Speichert nichts, keine Buchung, kein Versand. Benötigt einen Schlüssel mit der Berechtigung `sales:read` oder `read`.