bimetricsEntwickler
Kassenbuch

Kassentage übernehmen

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-import-files/{id}/apply

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

Übernimmt die in der Dateivorschau als bereit markierten Kassentage in Datumsfolge bis zum ersten Halt. Inhaber und Nutzer bestätigen mit batchHash und expectedBalanceMinor aus der Vorschau. Eine Änderung erfordert eine neue Vorschau. Für eine Wiederholung gilt derselbe Idempotency-Key. Ein übernommener Tag lässt sich nur als Ganzes stornieren.

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 Kassendatei (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

Hash und Bestand aus der Dateivorschau

application/json
  1. body

Bestätigung der geprüften Kassentage.

batchHash?string

Prüfsumme aus der Dateivorschau.

expectedBalanceMinor?integer

Bestand aus der Dateivorschau in Cent.

Antworten

Erfolg.

application/json
  1. response

Eine Kassendatei: was bimetrics aus ihr gelesen hat, die Rollen ihrer Konten und ihre Kassentage.

accounts?array<>|

Die Gegenkonten der Datei mit Bezeichnung und Rolle.

balanceBeforeMinor?integer

Bestand vor dem ersten Tag in Cent.

batchHash?string

Prüfsumme der gemeinsam übernehmbaren Tage. Fehlt, wenn kein Tag bereit ist.

cashAccount?integer

Kassenkonto der Datei; 0 bei DSFinV-K.

cashBookId?string

Kassenbuch der Art register.

Formatuuid
chart?string

Kontenrahmen der Datei: SKR03 oder SKR04; fehlt bei DSFinV-K.

Wert in"SKR03""SKR04"
confirmedAt?string

Zeitpunkt, zu dem der Inhaber die Rollen der Konten bestätigt hat.

Formatdate-time
confirmedBy?string

Name des Inhabers, der die Rollen bestätigt hat.

createdAt?string

Zeitpunkt des Hochladens.

Formatdate-time
days?array<>|

Die Kassentage der Datei; ein Tag ohne Buchungen steht nicht darin.

fileKey?string

Kennung der Kasse aus Kassensystem und Kostenstelle (KOST1), etwa „belbo · KOST1 30“; bei DSFinV-K die Seriennummer der Kasse. Berater- und Mandantennummer gehören der Steuerkanzlei und zählen nicht.

fileName?string

Name der Datei beim Hochladen.

format?string

datev: DATEV-Buchungsstapel; dsfinvk: DSFinV-K-Export.

Wert in"datev""dsfinvk"
id?string

ID der Kassendatei.

Formatuuid
known?integer

Zahl der Tage, die mit denselben Zeilen schon übernommen sind und deshalb keinen Entwurf bekommen.

origin?string

Weg des Hochladens: web, api oder mcp.

periodFrom?

Beginn des Zeitraums laut Kopf der Datei.

periodTo?

Ende des Zeitraums laut Kopf der Datei.

sameFile?

Dieselbe Datei wurde schon einmal hochgeladen und nicht verworfen.

sha256?string

SHA-256 der Datei; sie wird nie ersetzt.

sizeBytes?integer

Größe der Datei in Byte.

status?string

mapping (die Konten warten auf ihre Rollen, beim ersten DSFinV-K-Export die Kasse auf ihre Bestätigung), read (jeder Kassentag ist ein Tagesabschluss) oder discarded (verworfen).

Wert in"mapping""read""discarded"
uploadedBy?string

Name der Person, die die Datei hochgeladen hat.

vendor?string

Kassensystem laut Kopf der Datei, etwa belbo.

Beispielanfrage
curl --fail-with-body "https://app.bimetrics.de/api/cash-import-files/497f6eca-6276-4993-bfeb-53cbbbba6f08/apply" \  -H "Authorization: Bearer $BIMETRICS_API_KEY" \  -H "Idempotency-Key: rechnung-2026-001" \  -H "Content-Type: application/json" \  -d '{}'
Beispielantwort
{  "accounts": [    {      "account": 1360,      "label": "EC-Karte",      "lines": 6,      "role": "transit"    },    {      "account": 1363,      "label": "Kauf auf Rechnung",      "lines": 1,      "role": "on_account"    },    {      "account": 1718,      "label": "Behandlungspakete",      "lines": 4,      "role": "prepaid"    },    {      "account": 4980,      "label": "Sonstiger Betriebsbedarf",      "lines": 3,      "role": "payout"    },    {      "account": 8400,      "label": "Umsatzerlöse 19 %",      "lines": 17,      "role": "revenue"    }  ],  "balanceBeforeMinor": 105925,  "cashAccount": 1000,  "cashBookId": "7c2e9a41-5b3d-4f08-9e61-2d8a4c7f1b39",  "chart": "SKR03",  "confirmedAt": "2026-04-02T09:24:00Z",  "confirmedBy": "Jana Kröger",  "createdAt": "2026-04-02T09:20:00Z",  "days": [    {      "cashMinor": 4185,      "day": {        "day": 3,        "month": 3,        "year": 2026      },      "importId": "6e2a4c8b-3d5f-4b79-9c1e-4a6b8d0f2c35",      "lines": 10,      "revenueMinor": 34075,      "status": "applied",      "unsupported": 0    },    {      "cashMinor": 5980,      "day": {        "day": 4,        "month": 3,        "year": 2026      },      "importId": "7f3b5d9c-4e6a-4c8a-8d2f-5b7c9e1a3d46",      "lines": 11,      "revenueMinor": 69495,      "status": "applied",      "unsupported": 0    }  ],  "fileKey": "belbo · KOST1 30",  "fileName": "belbo-export-2026-03.csv",  "format": "datev",  "id": "5d1f3b7a-2c4e-4a68-8b0d-3f5a7c9e1b24",  "known": 0,  "origin": "web",  "periodFrom": {    "day": 1,    "month": 3,    "year": 2026  },  "periodTo": {    "day": 31,    "month": 3,    "year": 2026  },  "sha256": "3b5d7f9a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d",  "sizeBytes": 18597,  "status": "read",  "uploadedBy": "Jana Kröger",  "vendor": "belbo"}

Kontenrollen einer Kassendatei ändern PATCH

Ändert die bestätigten Rollen der Konten einer gelesenen Kassendatei (`status: read`) an ihrer Kasse. Die Kasse ist der führende Stand für alle ihre Dateien: Ein Konto in `accounts` bekommt seine neue Rolle, eine leere Rolle entfernt sie, und ein Konto, das fehlt, behält die Rolle der Kasse. Jede Änderung steht mit Person bzw. API-Schlüssel, Zeit, Kanal, Konto, alter und neuer Rolle im Protokoll. Jede Kassendatei der Kasse übernimmt die Rollen, und jeder Entwurf eines Tagesabschlusses aus den Kassendateien der Kasse, der noch nicht übernommen ist, wird mit den neuen Rollen neu gelesen, außer in einem abgeschlossenen Monat. Übernommene Tage bleiben, wie sie gebucht sind: Zum Korrigieren stornierst du den Tag (`reverseCashImport`) und lädst die Datei noch einmal hoch, dann kommt er als Entwurf mit den neuen Rollen zurück. Erlös passt nur zu einem Konto für Umsatzerlöse oder Erlösschmälerungen oder einem Erlöskonto mit Steuerautomatik, eine Anzahlung nur zu einem Konto mit Steuerautomatik, und ein Umsatzsteuerkonto bekommt keine Rolle; sonst `400 CashBookRejected` mit dem Konto im Satz. Wartet die Datei noch auf ihre Zuordnung, bestätigst du sie zuerst mit `confirmRegisterFileAccounts` (`409`); auch eine verworfene Datei gibt `409`. Gebucht wird nichts. Nur Inhaber (`403 CashBookOwnerOnly`). Bei einer Wiederholung schickst du denselben Idempotency-Key. Benötigt einen Schlüssel mit der Berechtigung `company:write`.

Kassendatei verwerfen POST

Verwirft die Datei und ihre offenen Tagesentwürfe. Das Original und das Protokoll bleiben erhalten. Sobald ein Kassentag aus der Datei gebucht wurde, ist das Verwerfen gesperrt. Inhaber und Nutzer dürfen verwerfen. Verwende bei einer Wiederholung denselben Idempotency-Key. Benötigt einen Schlüssel mit der Berechtigung `matching:write`.