bimetricsEntwickler
Kassenbuch

Tagesabschluss stornieren oder verwerfen

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-imports/{id}/reverse

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

Verwirft einen Entwurf, der noch nicht übernommen ist (reading, read, failed), ohne Grund; er bleibt als discarded erhalten. Hat der Nutzer die Werte eines nicht lesbaren Z-Bons schon eingetragen, schickst du sie in values mit, dann behält bimetrics sie mit Z-Nummer und Tag. Einen übernommenen Tagesabschluss storniert die Route als Ganzes mit Grund: Jeder Eintrag bekommt sein Storno mit eigener Nummer am Kassentag, seine Buchungen werden gespiegelt, danach lässt sich derselbe Z-Bon neu übernehmen. Einzelne Einträge eines Tagesabschlusses storniert reverseCashBookEntry nicht (409 CashBookDayClosingEntry). Abgelehnt wird das Storno, solange einem Geldtransit ein Bankumsatz zugeordnet ist. Stornieren und verwerfen dürfen Inhaber und Nutzer. 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 des Tagesabschlusses (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

Grund, Pflicht beim Storno eines übernommenen Tagesabschlusses, und die eingetragenen Werte eines Z-Bons, den bimetrics nicht lesen konnte

application/json
  1. body

Storno oder Verwerfen.

reason?string

Grund, höchstens 120 Zeichen; Pflicht beim Storno eines übernommenen Tagesabschlusses.

values?

Nur beim Verwerfen eines nicht lesbaren Z-Bons (status: failed): die eingetragenen Werte wie zuletzt an previewCashImport. bimetrics behält sie mit Z-Nummer und Tag. Haben sie Geld bewegt, sind zNumber und day Pflicht, und die fehlende Z-Nummer lässt sich beim Monatsabschluss nur als Korrektur erklären, sonst übernimmt man den Z-Bon neu. Einen day prüft bimetrics wie beim Übernehmen: ein gültiger Tag ab dem Start des Kassenbuchs, nicht in der Zukunft, sonst 400 CashBookRejected. Ohne Werte bleibt die Z-Nummer unbekannt.

Antworten

Erfolg.

application/json
  1. response

Tagesabschluss eines Kassensystems: der Z-Bon und, sobald gelesen, seine Werte.

cashBookId?string

Kassenbuch der Art register.

Formatuuid
createdAt?string

Zeitpunkt des Hochladens.

Formatdate-time
day?

Tag des Tagesabschlusses laut Z-Bon.

duplicateOf?

Bei einem Entwurf: der übernommene Tagesabschluss, den er wiederholt, nach derselben Regel wie die Prüfung duplicate von previewCashImport, bevor die Rückfrage zum Neustart beantwortet ist. Gleich sind dieselbe Z-Nummer am selben Tag, dieselbe Datei, dieselbe Z-Nummer mit derselben Kassen-ID und denselben Summen an einem anderen Tag oder dieselbe Z-Nummer in seiner Z-Folge. Übernehmen lässt sich der Entwurf nicht. Nur in listCashImports.

fileImportId?string

Die Kassendatei, aus der der Tag stammt.

Formatuuid
fileName?string

Name der Datei beim Hochladen.

fileType?string

pdf für ein PDF, photo für ein Foto (JPEG oder PNG), erkannt am Inhalt der Datei; datev oder dsfinvk für einen Tag aus einer Kassendatei.

group?string

Bei einem Entwurf: gleich für Entwürfe, die in allen buchungsrelevanten Werten übereinstimmen (Kassen-ID, Z-Nummer, Tag, Umsatz je Steuersatz, Zahlarten, Gutscheine, Trinkgeld, Bewegungen, Sonderzeilen, Kassendifferenz und Endbestand), etwa zwei Fotos eines Z-Bons. Entwürfe derselben Z-Nummer in anderen Gruppen weichen in einem Wert ab. Nur in listCashImports.

id?string

ID des Tagesabschlusses.

Formatuuid
origin?string

Weg des Hochladens: web, api oder mcp.

readFailure?string

Bei failed der Grund: kein Text erkannt oder die Erkennung hat den Z-Bon abgelehnt (unreadable), keine Z-Nummer (no_z_number), kein Z-Bon (not_a_z_bon) oder die Erkennung war nach drei Versuchen nicht erreichbar (unavailable).

registerId?string

Kassen-ID laut Z-Bon.

sameDay?

Bei einem Entwurf: ein übernommener Tagesabschluss seines Tages mit anderer Z-Nummer, der mit der nächstliegenden Nummer. Es ist ein zweiter Abschluss des Tages oder eine Korrektur; previewCashImport prüft das mit correction bzw. shift. Nur in listCashImports.

sameFile?

Dieselbe Datei wurde schon einmal hochgeladen; fehlt, wenn das Lesen des früheren Uploads gescheitert ist.

sha256?string

SHA-256 der Datei; sie wird nie ersetzt.

sizeBytes?integer

Größe der Datei in Byte.

source?string

zbon für einen Z-Bon, datev für einen Tag aus einem DATEV-Buchungsstapel, dsfinvk für einen Kassenabschluss aus einem DSFinV-K-Export.

Wert in"zbon""datev""dsfinvk"
status?string

reading (wird gelesen), read (gelesen, Werte warten auf die Bestätigung), failed (nicht lesbar), applied (übernommen), reversed (als Ganzes storniert) oder discarded (Entwurf verworfen).

summary?

Summen der übernommenen, sonst der gelesenen Werte; fehlt, solange es keine gibt (reading, failed). Nur in listCashImports.

textSource?string

pdf: Werte aus der Textschicht eines PDFs; vision: bimetrics hat den Text erst aus dem Bild gelesen.

truncated?boolean

true, wenn der Z-Bon mehr Text hat, als bimetrics liest; sein Ende wurde nicht gelesen.

unsure?integer

Zahl der Werte und Arten von Bewegungen, die der Nutzer noch bestätigen muss.

uploadedBy?string

Name der Person, die den Z-Bon hochgeladen hat.

values?

Die gelesenen Werte, sobald status read ist.

zNumber?integer

Z-Nummer laut Z-Bon.

zSeries?integer

Z-Folge eines übernommenen Tagesabschlusses, ab 1; ein bestätigter Neustart der Z-Nummern beginnt die nächste.

Beispielanfrage
curl --fail-with-body "https://app.bimetrics.de/api/cash-imports/497f6eca-6276-4993-bfeb-53cbbbba6f08/reverse" \  -H "Authorization: Bearer $BIMETRICS_API_KEY" \  -H "Idempotency-Key: rechnung-2026-001" \  -H "Content-Type: application/json" \  -d '{}'
Beispielantwort
{  "cashBookId": "7c2e9a41-5b3d-4f08-9e61-2d8a4c7f1b39",  "createdAt": "2026-11-12T19:10:00Z",  "day": {    "day": 12,    "month": 11,    "year": 2026  },  "fileName": "z-bon-1187.jpg",  "fileType": "photo",  "id": "4a8c2e6f-1b3d-4f57-9a0c-2e4f6a8b0c13",  "origin": "web",  "registerId": "1",  "sha256": "9f2c4e6a8b0d1f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f1a",  "sizeBytes": 812345,  "source": "zbon",  "status": "reversed",  "textSource": "pdf",  "unsure": 2,  "uploadedBy": "Jana Kröger",  "values": {    "day": {      "quote": "12.11.2026 19:04",      "sure": true,      "value": "2026-11-12"    },    "movements": [      {        "amount": {          "minor": 950,          "quote": "Entnahme 9,50",          "sure": false        },        "in": false,        "kind": "payout",        "kindSure": false,        "label": "Entnahme",        "text": "Post"      }    ],    "payments": {      "card": [        {          "amount": {            "minor": 80250,            "quote": "EC 802,50",            "sure": true          },          "label": "EC"        }      ],      "cash": {        "minor": 51800,        "quote": "Bar 518,00",        "sure": true      },      "voucher": {        "minor": 6000,        "quote": "Gutschein 60,00",        "sure": true      }    },    "registerId": {      "quote": "Kasse 1",      "sure": true,      "value": "1"    },    "revenue": [      {        "gross": {          "minor": 138050,          "quote": "MwSt 19% 1.380,50",          "sure": true        },        "rate": 19      }    ],    "tips": {},    "zNumber": {      "quote": "Z-Nr. 1187",      "sure": true,      "value": "1187"    }  },  "zNumber": 1187}

Tagesabschluss prüfen POST

Prüft einen gelesenen Tagesabschluss und zeigt, was die Übernahme buchen würde, ohne etwas zu schreiben: die Einträge mit ihren Buchungen am Kassentag, den Bestand danach, zu jedem Wert seine Quelle (`fields`) und die Prüfungen (`checks`). Ohne `values` nimmt die Prüfung die gelesenen Werte. Danach schickst du `values` aus der Antwort mit Änderungen zurück, wählst die Art jeder Bewegung, ergänzt Bewegungen, die der Z-Bon nicht druckt (`source: manual`), und nennst in `confirmedFields` die unsicheren Werte, die der Nutzer so bestätigt hat. `ready` ist `true`, wenn nichts mehr anhält oder fragt; `valuesHash` und `balanceBeforeMinor` gehen dann an `applyCashImport`. Steuersätze kommen nur aus dem Z-Bon, nie aus früheren Belegen. Ist der Tagesabschluss schon übernommen, liefert die Route seine Werte und Einträge. Benötigt einen Schlüssel mit der Berechtigung `read`.

Kassenbuch-Einstellung lesen GET

Sagt, ob die Firma das Kassenbuch verwendet (`enabled`), ob der Schlüssel bzw. die Person es ändern darf (`canChange`, nur Inhaber) und darin buchen darf (`canBook`, nicht die Steuerberatung), wie viele Kassenbücher in Gebrauch sind (`inUse`) und welche Kassenkonten ein neues Kassenbuch nehmen kann (`accounts`, das nächste freie zuerst). `deposit` sagt, wie eine Einlage in die Kasse gebucht wird: `owner` als Privateinlage, `shareholder` über das Gesellschafter-Verrechnungskonto; leer, wenn die Rechtsform fehlt oder keine Einlage kennt. Benötigt einen Schlüssel mit der Berechtigung `read`.