bimetricsEntwickler
Kassenbuch

Z-Bon hochladen

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

Kein Testversand aus der Dokumentation: Jeder Aufruf legt einen echten Beleg an. Nutze das Codebeispiel mit einer Datei, die wirklich in die Firma gehört.

Speichert den Z-Bon eines Kassensystems unverändert und mit seiner SHA-256-Prüfsumme in einer Kasse der Art register. Im Hintergrund liest bimetrics ihn dann: erst den Text, dann die Werte, jeden mit der Textstelle, aus der er stammt. Die Antwort kommt mit status: reading; getCashImport liefert die Werte, sobald status read ist, meist nach 10 bis 30 Sekunden. Gebucht wird noch nichts. Hochladen dürfen Inhaber und Nutzer, nicht die Steuerberatung. 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 Kassenbuchs (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

multipart/form-data
  1. body
file*unknown

Der Z-Bon als Foto (JPEG oder PNG) oder als PDF, höchstens 30 MB.

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-books/497f6eca-6276-4993-bfeb-53cbbbba6f08/imports" \  -H "Authorization: Bearer $BIMETRICS_API_KEY" \  -H "Idempotency-Key: rechnung-2026-001" \  -F "auto[]=@rechnung.pdf"
Beispielantwort
{  "cashBookId": "7c2e9a41-5b3d-4f08-9e61-2d8a4c7f1b39",  "createdAt": "2026-11-12T19:10:00Z",  "fileName": "z-bon-1187.jpg",  "fileType": "photo",  "id": "4a8c2e6f-1b3d-4f57-9a0c-2e4f6a8b0c13",  "origin": "web",  "sha256": "9f2c4e6a8b0d1f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f1a",  "sizeBytes": 812345,  "source": "zbon",  "status": "reading",  "unsure": 0,  "uploadedBy": "Jana Kröger"}

Tagesabschlüsse eines Monats GET

Listet die Tagesabschlüsse einer Kasse für den angefragten Monat auf, dazu alle Entwürfe, die noch gelesen werden oder auf Bestätigung warten. Die neuesten stehen oben. Die Werte liefert nur `getCashImport`. Benötigt einen Schlüssel mit der Berechtigung `read`.

Monat abschließen POST

Schließt einen Monat des Kassenbuchs endgültig ab, wenn alle Prüfungen von `POST /api/cash-books/{id}/months/{month}/close/preview` erfüllt sind; sonst `409 CashBookRejected`. Monate schließen streng nacheinander, nie der laufende. Der Abschluss merkt sich die maßgebliche Zählung (`countId`). `expectedClosingMinor` und `expectedEntries` sind Pflicht: Endbestand und Zahl der Einträge aus der Prüfung. Hat sich der Monat seitdem geändert, antwortet die Route mit `409 CashBookRejected` und schließt nichts ab. Auch ein stillgelegtes Kassenbuch schließt seine Monate ab, denn der Abschluss bewegt kein Geld. Danach geht keine Buchung und keine Barzahlung am Beleg mehr in diesen Monat (`400 CashBookRejected`, Feld `entryDate`). Ein Storno einer Buchung aus dem Monat kommt mit heutigem Datum und einer Nummer seines Jahres in den laufenden Monat und verweist auf das Original. Alle noch offenen Buchungen der Einträge des Monats werden festgeschrieben (`finalizedBy` `cashbook`), auch die der Barzahlungen an Belegen. Zurücknehmen lässt sich der Abschluss nicht. Bei einem Kassenbuch der Art `register` gehen `lastZConfirmed`, `zSeriesEnds`, `zGapReasons` und in einem Monat mit Kassendateien `registerCountConfirmed` mit `registerCountNote` wie in der Prüfung mit; der Abschluss hält sie in `zCheck`, und das Protokoll nennt Person, Zeit und Kanal. Bestätigen darf, wer abschließen darf. Abschließen dürfen Inhaber und Steuerberatung, nicht der Nutzer (`403 CashBookOwnerOnly`). Bei einer Wiederholung schickst du denselben Idempotency-Key und bekommst den geschriebenen Abschluss. Benötigt einen Schlüssel mit der Berechtigung `matching:write`.