Sicherheitseinbehalt jetzt fällig stellen
Benötigte Berechtigung:invoices:draft(Rechnungsentwürfe verwalten)
Echte Wirkung
/api/receivable/{id}/retention-releaseKein Testversand aus der Dokumentation: Dieser Aufruf ist nicht als rein lesend gekennzeichnet. Nutze das Codebeispiel.
Stellt den Sicherheitseinbehalt der Rechnung ab heute fällig, etwa wenn die Firma eine Bürgschaft stellt. Rechnung, PDF und E-Rechnung bleiben unverändert, nur der Zahlstand folgt: Der Einbehalt zählt ab heute zum fälligen Betrag und lässt sich mahnen. Mit expectedReceivableVersion aus getReceivable, sonst 409 ReceivablePreviewChanged. Ohne Einbehalt 409 RetentionMissing; ein schon fälliger oder bezahlter bleibt, wie er ist. Der Grund steht im Protokoll.
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.
id*stringID des Objekts dieser Firma (UUID); bei Forderungsständen und neuen Korrekturen die Quellentwurfs-ID.
uuidIdempotency-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 <= 128application/json- body
Sicherheitseinbehalt ab heute fällig stellen.
expectedReceivableVersion?stringreceivableVersion aus getReceivable, unverändert.
reason?stringOptionaler Grund fürs Protokoll, eine Zeile, höchstens 200 Zeichen, zum Beispiel „Bürgschaft gestellt“.
Erfolg.
application/json- 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?booleanFür das Original ist eine weitere Rechnungskorrektur möglich.
canRemind?booleanAktuelle Forderung darf gemahnt werden. Eine laufende Mahnung (activeReminder) sperrt nicht, eine Mahnsperre (reminderHold) schon.
cancellationBlockReason?stringMaschinenlesbarer 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?integerNoch korrigierbarer Bruttobetrag in Cent, unabhängig vom Zahlungsstand.
correctedMinor?integerSumme ausgestellter, nicht aufgehobener Korrekturen in Cent.
correctionBlockReason?stringMaschinenlesbarer 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?stringWährung EUR.
customerName?stringName 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?stringID der Banktransaktion dieser Zahlung; fehlt bei einer erfassten Zahlung.
uuidnextReminderLevel?integerDie vorgeschlagene nächste Stufe, solange canRemind gilt: eins über der höchsten ausgestellten, zurückgezogene zählen nicht. Fehlt nach Stufe 3.
number?stringNummer der Originalrechnung.
openMinor?integerAktuell offener Betrag in Cent; nur bei paymentKnown=true aussagekräftig.
originalGrossMinor?integerUrsprünglicher Bruttobetrag in Cent.
paidMinor?integerEindeutig zugeordnete bzw. dokumentierte Zahlung in Cent; nur bei paymentKnown=true aussagekräftig.
paymentKnown?booleanZahlungen sind eindeutig zuordenbar. Bei false keine zahlungsabhängigen Nullwerte als tatsächlichen Nullbetrag interpretieren.
receivableVersion?stringDigest des aktuellen Forderungsstands; unverändert als expectedReceivableVersion senden.
refundDueMinor?integerGuthaben 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?stringMaschinenlesbarer Grund einer gesperrten Mahnung: cancelled, payment_unknown, settled, reminder_hold, retention_not_due (offen ist nur der Sicherheitseinbehalt, noch nicht fällig), due_date_missing oder not_overdue.
reminderHold?Mahnsperre, die heute gilt; fehlt ohne.
retention?Sicherheitseinbehalt der Rechnung; fehlt ohne. Sein heldMinor gehört zu openMinor, Mahnungen fordern nur den Rest.
sourceDocumentId?stringID des ausgestellten Originalbelegs.
uuidsourceDraftId?stringID des Originalrechnungsentwurfs.
uuidsourceLayoutId?stringGespeichertes Layout der Originalrechnung: modern oder classic. Ältere Rechnungen ohne Layoutangabe verwenden modern.
sourceVersion?stringAktueller updatedAt-Wert des Originalentwurfs.
date-timecurl --fail-with-body "https://app.bimetrics.de/api/receivable/497f6eca-6276-4993-bfeb-53cbbbba6f08/retention-release" \ -H "Authorization: Bearer $BIMETRICS_API_KEY" \ -H "Idempotency-Key: rechnung-2026-001" \ -H "Content-Type: application/json" \ -d '{}'{ "canCorrect": true, "canRemind": true, "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, "retention": { "amountMinor": 59500, "dueOn": { "day": 30, "month": 10, "year": 2030 }, "heldMinor": 0 }, "sourceDocumentId": "3026096b-614f-40d3-8749-8acf9b529480", "sourceDraftId": "821c3664-640a-4e10-b120-a4ff713532f8", "sourceLayoutId": "classic", "sourceVersion": "2026-09-01T08:01:02.123456Z"}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`.
Mahnungen und Entwürfe suchen GET
Liefert Mahnungsentwürfe, ausgestellte und zurückgezogene Mahnungen. status=all schließt den unveränderlichen Verlauf ein. Ein dokumentierter externer Versand ist kein Versandauftrag oder Zustellnachweis. Benötigt einen Schlüssel mit der Berechtigung `sales:read` oder `read`.