bimetricsEntwickler
Kassenbuch

Beleg einer Auszahlung zuordnen

Als Markdown ansehen

Benötigte Berechtigung:matching:write(Belege und Zahlungen zuordnen)

Echte Wirkung

Ändert Daten der Firma; wird atomar mit Idempotenzbeleg und Herkunft protokolliert.
post/api/cash-book-entries/{id}/document

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

Ordnet einer Auszahlung aus einem Tagesabschluss (receiptMissing) ihren Beleg zu, wie „Zuordnen“ und „Eigenbeleg erstellen“ in der App. Mit documentId bucht bimetrics die Barzahlung eines offenen Eingangsbelegs, Kreditor an Kasse, wie POST /api/match/payment; expectedVersion und expectedAmountOpenMinor sind die zuletzt gelesenen Werte. Der offene Betrag muss die Auszahlung decken. Ohne Beleg bucht ein Eigenbeleg (category und ownReceipt) die Ausgabe ohne Vorsteuer, wie eine Ausgabe ohne Beleg. Beides zusammen oder keins ergibt 400 CashBookRejected. Betrag und Tag kommen aus der Auszahlung: Gebucht wird am Kassentag, ein neuer Eintrag entsteht nicht. Eine Auszahlung hat höchstens einen Beleg. Nur im offenen Monat, auch in einem stillgelegten Kassenbuch. Lohn und ausgezahltes Trinkgeld brauchen keinen Beleg. Zuordnen dürfen Inhaber und Nutzer, nicht die Steuerberatung (403 CashBookOwnerOnly). Bei einer Wiederholung schickst du denselben Idempotency-Key.

Benötigt einen Schlüssel mit der Berechtigung matching:write.

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 der Auszahlung (UUID).

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

the receipt or the own receipt

application/json
  1. body

Beleg oder Eigenbeleg einer Auszahlung, nie beides.

category?string

Ohne Beleg Pflicht: eine Kategorie für Eingangsbelege, wie bei einer Ausgabe ohne Beleg; gesperrt sind Kategorien, für die es immer einen Beleg oder Bescheid gibt.

documentId?string

Ein offener Eingangsbeleg, dessen offener Betrag die Auszahlung deckt.

Formatuuid
expectedAmountOpenMinor?integer

Mit documentId: zuletzt gelesener offener Betrag in Cent.

expectedVersion?string

Mit documentId: zuletzt gelesene Version des Belegs.

ownReceipt?

Ohne Beleg Pflicht: Empfänger, Zweck und Grund, je höchstens 100 Zeichen ohne doppelte Anführungszeichen.

Antworten

Erfolg.

application/json
  1. response

Die Auszahlung mit ihrem Beleg.

bookings?array<>|

Die Buchungen des Belegs am Kassentag; leer nach der Rücknahme.

entry?

Die Auszahlung mit settlement, nach der Rücknahme mit receiptMissing.

replayed?boolean

true bei einer Wiederholung.

Beispielanfrage
curl --fail-with-body "https://app.bimetrics.de/api/cash-book-entries/497f6eca-6276-4993-bfeb-53cbbbba6f08/document" \  -H "Authorization: Bearer $BIMETRICS_API_KEY" \  -H "Idempotency-Key: rechnung-2026-001" \  -H "Content-Type: application/json" \  -d '{}'
Beispielantwort
{  "bookings": [    {      "account": 1600,      "accountContra": 6800,      "amountMinor": -950,      "flags": "v-none",      "text": "Z-1186 Porto, Deutsche Post"    }  ],  "entry": {    "amountMinor": -950,    "cashBookId": "7c2e9a41-5b3d-4f08-9e61-2d8a4c7f1b39",    "cashImportId": "6d2f8b1c-3e5a-4c7d-9f20-8b4e1a6c3d57",    "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5",    "createdAt": "2026-11-13T09:05:00Z",    "entryDate": {      "day": 12,      "month": 11,      "year": 2026    },    "id": "3f1d2c7a-8b9e-4a51-b6c2-0e4f8a9d7b13",    "kind": "expense",    "number": "KB-2026-0007",    "origin": "api",    "settlement": {      "category": "postage",      "createdAt": "2026-11-13T10:00:00Z",      "id": "2c8e4a6f-1b3d-4f5e-8a7c-9d0b2e4f6a18",      "ownReceipt": {        "purpose": "Porto",        "reason": "Automat ohne Quittung",        "recipient": "Deutsche Post"      }    },    "text": "Auszahlung aus Z-1186: Porto",    "updatedAt": "2026-11-13T09:05:00Z",    "year": 2026  }}

Korrektur eines Kassenbuch-Eintrags prüfen POST

Prüft eine Korrektur wie `correctCashBookEntry` und zeigt das Storno und den richtigen Eintrag mit ihren Buchungen und dem Bestand danach, ohne etwas zu schreiben. Eine Nummer haben beide erst beim Buchen. Korrigieren lässt sich ein eigener Eintrag ohne Beleg: Ausgabe, Privateinlage, Privatentnahme und Geld von oder zur Bank. Eine Barzahlung zu einem Beleg (auch jede Einnahme), eine Zeile eines Tagesabschlusses, ein Anfangsbestand, eine Kassendifferenz und ein Storno nicht (`409 CashBookRejected`); dort bleibt das Storno. Das Storno trägt den Kassentag des Eintrags, nach dem Monatsabschluss den heutigen Tag. Der richtige Eintrag nimmt den Tag aus `entry`, nur in einem offenen Monat. Auch nach beiden darf der Bestand nirgends unter 0 € fallen. Abrufen dürfen es alle Rollen. Benötigt einen Schlüssel mit der Berechtigung `read`.

Beleg einer Auszahlung zurücknehmen POST

Nimmt den Beleg einer Auszahlung mit Grund zurück, wie „Beleg zurücknehmen“ in der App: Die Barzahlung des Belegs oder die Buchungen des Eigenbelegs werden am Kassentag gespiegelt, die ursprünglichen bleiben sichtbar. Danach steht die Auszahlung wieder mit `receiptMissing`. Ist der Monat abgeschlossen, antwortet die Route mit `409 CashBookRejected`; die Berichtigung klärt dann die Steuerberatung. `POST /api/match/payment/reverse` nimmt die Barzahlung eines solchen Belegs nicht zurück, nur diese Route. Zurücknehmen dürfen Inhaber und Nutzer, nicht die Steuerberatung (`403 CashBookOwnerOnly`). Bei einer Wiederholung schickst du denselben Idempotency-Key. Benötigt einen Schlüssel mit der Berechtigung `matching:write`.