Buchhaltung (Direct Cloud Connectors)

WICHTIGER HINWEIS: Für die direkten Online-Schnittstellen (insbesondere lexoffice) wurden seitens der Betreiber bisher keine Live-API-Zugangsdaten bereitgestellt. Die Connectoren im Kassensystem wurden vollständig entwickelt und gegen Simulationsumgebungen (Mocks, z. B. MockLexofficeConnector) getestet. Bitte beachten Sie, dass vor der Nutzung in einer Live-Umgebung die jeweiligen API-Schlüssel des Anbieters eingetragen und ein Testlauf durchgeführt werden müssen.

Wozu dient das?#

Das Modul Buchhaltung dient der automatisierten Übertragung von Tagesabschluss-Daten an moderne Cloud-Buchhaltungssysteme wie lexoffice, sevDesk oder Billomat. Statt nach Betriebsschluss manuelle Umsätze aus gedruckten Z-Berichten oder CSV-Dateien per Hand in Ihre Buchhaltungssoftware einzutippen, überträgt das Kassensystem die Tageseinnahmen, aufgeschlüsselt nach Steuersätzen (19 %, 7 %, 0 %) und Zahlungsarten (Bar, Karte, Gutschein), direkt über Schnittstellen an das Zielsystem.

Abgrenzung zu DATEV: Dieses Modul unterscheidet sich vom klassischen DATEV-Export (→ Kapitel 23b). DATEV-CSV-Exporte richten sich primär an den Steuerberater zur Vorbereitung des Jahresabschlusses. Die Cloud-Connectoren dienen der tagesaktuellen Einnahmen-Buchung im eigenen Buchhaltungssystem des Gastronomen.

Rollen#

Administrator / Betriebsleiter (admin): Besitzt die ausschließliche Berechtigung, Buchhaltungs-Connectoren zu konfigurieren, API-Schlüssel einzugeben, Schnittstellen zu aktivieren, manuelle Synchronisationen auszulösen und fehlgeschlagene Übertragungen erneut einzureichen (Replay). Das geschieht über die Schnittstelle, nicht über einen Bildschirm der Kasse.
Kassenpersonal / Servicekräfte (staff, waiter): Haben keinen Zugriff auf die Buchhaltungskonfiguration oder API-Schlüssel. Der Tagesabschluss an der Kasse stößt die Buchungsübertragung im Hintergrund automatisch an.

Voraussetzungen#

Sie besitzen Administrator-Rechte im Kassensystem.
Sie verfügen über ein aktives Benutzerkonto bei einem unterstützten Cloud-Buchhaltungsanbieter (lexoffice, sevDesk, Billomat).
Sie haben im Kundenportal des Anbieters einen API-Schlüssel / Zugangs-Token mit Schreibrechten für Belege generiert.

Schritt für Schritt#

1. Buchhaltungs-Connector: nur über die Schnittstelle#

Für die Cloud-Connectoren (lexoffice, sevDesk, Billomat, zum Testen mock) gibt es in der Kasse keine Bedienoberfläche: keinen Provider-Auswahlschalter, kein Feld für einen API-Schlüssel, keinen Schalter Enable, keine Schaltfläche zum Auslösen einer Synchronisation und kein Synchronisations-Logbuch. Einrichtung, manuelle Übertragung und Protokoll laufen ausschließlich über die Schnittstelle der Plattform (→ Kapitel 37); Ihr Betreuer richtet den Connector ein.

2. Tagesumsatz-Übertragung#

Nach dem regulären Tagesabschluss an der Kasse (Erstellung des Z-Berichts, → Kapitel 12) kann das System den Tagesumsatz über den eingerichteten Connector übertragen. Das Kassensystem prüft, ob für dieses Datum bereits eine erfolgreiche Buchung existiert (GoBD-Einmalbuchungssperre). Eine Schaltfläche Tagesumsatz synchronisieren gibt es im Backoffice nicht.

3. DATEV-Angaben für den Steuerberater eintragen#

Was Sie in der Kasse selbst einstellen, sind die DATEV-Angaben, die der Datenexport für Ihren Steuerberater braucht (→ Kapitel 23b).

Öffnen Sie im Backoffice einen der Einstellungsbereiche, zum Beispiel FISKAL.
Wählen Sie oben im Auswahlfeld Einstellungen den Eintrag Buchhaltung.
Tragen Sie Beraternummer und Mandantennummer ein.
Wählen Sie Beginn des Geschäftsjahres und den Kontenrahmen (SKR03 oder SKR04).
Tippen Sie auf Buchhaltungskonfiguration speichern und bestätigen Sie im Dialog Buchhaltung speichern? mit Speichern. Mit Abbrechen bleibt alles beim Alten.

Bildschirm für Bildschirm#

1. Backoffice Einstellungen, Bereich Buchhaltung#

Der Bereich trägt den Titel Buchhaltung und die Zeile Konfigurieren Sie Identifikatoren für externe Buchhaltungsexporte.

Einstellungen Buchhaltung mit DATEV-Konnektivität und Bestätigungsdialog

1 Das Auswahlfeld Einstellungen wechselt zwischen den Einstellungsbereichen (unter anderem Buchhaltung). Der Bereich hat in der Menüleiste keinen eigenen Eintrag.
2 Beraternummer: die DATEV-Nummer Ihres Steuerberaters.
3 Mandantennummer: Ihre Nummer bei diesem Steuerberater.
4 Beginn des Geschäftsjahres: der Monat, mit dem Ihr Geschäftsjahr beginnt.
5 Kontenrahmen: SKR03 oder SKR04.
6 Der Hinweis Die Konten für Kassenfehlbetrag und Kassenüberschuss sind nicht belegt; der Steuerberater muss sie bestätigen. erscheint nur, solange diese beiden Konten leer sind.
7 Buchhaltungskonfiguration speichern öffnet den Dialog.
8 Der Dialog Buchhaltung speichern? mit dem Text Die Buchhaltungsverbindung wird mit diesen Zugangsdaten gespeichert. und den Knöpfen Abbrechen und Speichern.

Fehlgeschlagene Übertragung erneut senden#

Schlägt die tägliche Übertragung der Buchungen an das Buchhaltungssystem endgültig fehl, landet der Eintrag im Übertragungsprotokoll im Status fehlgeschlagen. Ein Administrator kann einen solchen Eintrag erneut einstellen lassen. Dafür gibt es keine Bedienoberfläche: Es gibt kein Protokoll und keine Schaltfläche zum Wiederholen einer Buchungsübertragung, der Vorgang läuft nur über die Schnittstelle der Plattform (→ Kapitel 37). Beheben Sie zuerst die Ursache, zum Beispiel falsche Zugangsdaten, und bitten Sie dann Ihren Betreuer, den Eintrag erneut zu senden. Im Regelbetrieb brauchen Sie das nicht.

Beispiel einer exportierten Buchung (Payload & Belegstruktur)#

Bei der Synchronisation mit lexoffice wandelt das Kassensystem die Tagesumsätze in ein strukturiertes Beleg-JSON um, das an den lexoffice Vouchers API-Endpunkt (POST /v1/vouchers) übermittelt wird.

Beispiel-Payload einer Tagesumsatz-Buchung:#

{
  "type": "salesvoucher",
  "voucherDate": "2026-08-06T00:00:00.000+02:00",
  "voucherNumber": "POS-20260806-DEMO",
  "remark": "Tagesabschluss Kassensystem Demo-Restaurant",
  "totalGrossAmount": 1428.50,
  "totalNetAmount": 1250.00,
  "taxType": "gross",
  "voucherItems": [
    {
      "category": "Umsatzerlöse 19%",
      "amount": 1190.00,
      "taxRatePercent": 19.0,
      "taxAmount": 190.00
    },
    {
      "category": "Umsatzerlöse 7%",
      "amount": 238.50,
      "taxRatePercent": 7.0,
      "taxAmount": 15.60
    }
  ],
  "paymentPayments": [
    {
      "paymentMethod": "cash",
      "amount": 428.50
    },
    {
      "paymentMethod": "card",
      "amount": 1000.00
    }
  ]
}

Wie Umsätze und Steuer gemappt werden:#

Steuersatz-Splitting: Das System fasst alle Bar- und Kartenzahlungen des Tages exakt nach den von der TSE signierten Steuersätzen zusammen (Normalsteuersatz 19 %, ermäßigter Steuersatz 7 %, steuerfrei 0 %).
Zahlungsarten-Splitting: Die Gegenkontierung erfolgt getrennt nach Barzahlungen (Kassenbuch) und unbaren Zahlungen (EC-/Kreditkarte, Gutscheine).
Exaktheit: Die Beträge werden auf Basis der TSE-Protokolldaten Cent-genau berechnet; Es finden keine pauschalen Schätzungen statt.

Was passiert im Hintergrund#

GoBD-Einmalbuchungs-Prinzip (Single Booking Idempotency): Nach den GoBD ist eine Mehrfachbuchung desselben Tagesumsatzes in der Buchhaltung unzulässig. Das System garantiert die Einmalbuchung auf zwei Ebenen:
1. Datenbank-Ebene: Ein eindeutiger Datenbank-Index über (tenant_id, provider, business_date) in der Tabelle accounting_sync_logs verhindert doppelte Einträge.
2. Anwendungs-Ebene: Bei Auslösung einer Synchronisation setzt das System eine verteilte Redis-Sperre (Distributed Lock). Wird ein Tagesabschluss erneut aufgerufen, gibt das System das bereits existierende Buchungsprotokoll zurück, ohne einen zweiten API-Aufruf an den Buchhaltungsanbieter zu senden.
Fernet-Verschlüsselung der API-Schlüssel: API-Schlüssel gewähren Schreib- und Leserechte auf Finanzdaten. Das Kassensystem speichert API-Schlüssel in der Datenbank verschlüsselt mittels Fernet-Symmetrieverschlüsselung (api_key_encrypted). Bei API-Abfragen wird der Schlüssel niemals im Klartext zurückgegeben, sondern über mask_api_key unleserlich gemacht.
Fehlerbehandlung & Dead-Letter-Warteschlange: Die Verbindung zu externen Cloud-Diensten verwendet Timeout-Grenzen (10 Sekunden) und automatische Wiederholungsversuche bei temporären Störungen. Verläuft die Übertragung wiederholt fehlerhaft, wechselt der Status des Logs in DEAD_LETTER. Nach Korrektur der Einstellungen lässt sich der Beleg über die Schnittstelle erneut übermitteln (Replay).

Häufige Probleme#

Unknown accounting provider
- Ursache: Der übergebene Provider-Name wird vom Kassensystem nicht unterstützt.
- Lösung: Wählen Sie einen der unterstützten Provider (lexoffice, sevdesk, billomat, mock).
Export not ready or failed
- Ursache: Der zugrunde liegende Tagesexport der Kassenbuchungen konnte nicht zusammengestellt werden.
- Lösung: Überprüfen Sie im Backoffice unter DATENEXPORTE, ob der Z-Bericht für diesen Tag ordnungsgemäß abgeschlossen wurde.
Export file missing from storage
- Ursache: Die temporäre Exportdatei für die Belegaufbereitung wurde aus dem Zwischenspeicher gelöscht.
- Lösung: Lassen Sie die Tagesabschluss-Synchronisation erneut auslösen, um das Belegpaket neu zu generieren.
Export job not found
- Ursache: Die angeforderte Export-Job-ID existiert nicht oder gehört zu einem anderen Mandanten.
- Lösung: Starten Sie den Synchronisationsvorgang über die Schnittstelle neu.
A request with this Idempotency-Key is currently in progress. Please retry after completion.
- Ursache: Eine Synchronisation für diesen Tag und Anbieter wird im Hintergrund genau in diesem Moment bereits verarbeitet.
- Lösung: Warten Sie einige Sekunden und prüfen Sie dann das Protokoll.
Idempotency key reservation lost due to timeout
- Ursache: Die externe Buchhaltungsschnittstelle hat innerhalb des Zeitlimits von 10 Sekunden nicht geantwortet, wodurch die Reservierung abgelaufen ist.
- Lösung: Prüfen Sie die Netzwerkanbindung und lassen Sie die Übertragung über die Schnittstelle erneut auslösen (Replay).
Idempotency key reservation conflict contradiction
- Ursache: Konkurrierende Anfragen haben versucht, denselben Buchungs-Schlüssel mit unterschiedlichen Daten zu belegen.
- Lösung: Prüfen Sie das Protokoll über die Schnittstelle und starten Sie die Übertragung neu.
API key has been revoked or deactivated / Invalid or revoked API key
- Ursache: Der bei lexoffice oder sevDesk generierte API-Schlüssel ist ungültig, abgelaufen oder wurde im Kundenportal widerrufen.
- Lösung: Erzeugen Sie im Kundenportal des Anbieters einen neuen API-Schlüssel und lassen Sie ihn über die Schnittstelle neu hinterlegen.

Grenzen#

Das Modul sendet Tagesumsatz-Sammelbelege an die Buchhaltungs-Software; die Übertragung von Einzelbelegen oder Kundenrechnungen für jeden Einzelverkauf ist nicht vorgesehen.
Mangels Live-Zugangsdaten für lexoffice erfolgt der Nachweis der Schnittstellenfunktion in der Testumgebung über das Simulatormodul (mock). Vor einem produktiven Einsatz müssen Live-Schlüssel eingegeben werden.

Dieses Kapitel gehört zum Merkuron-Handbuch für Inhaber und Servicepersonal.