Kasseneck API – Österreichische Registrierkassen-/RKSV-Schnittstelle

Was ist die Kasseneck API?

Die Kasseneck API setzt die österreichische Registrierkassensicherheitsverordnung (RKSV) um (BAO §131, BMF-DEP). Jeder Beleg wird kryptografisch signiert (ES256) und in eine manipulationssichere Kette (DEP – Datenerfassungsprotokoll) eingehängt. Kasseneck ist ein Produkt der Kreiseck.

Offizielle Pakete

Für die Anbindung gibt es zwei gepflegte Pakete – der schnellste Weg ohne manuelle HTTP-Aufrufe. Beide bilden denselben Funktionsumfang ab.

Dart und Flutter: kasseneck_api auf pub.dev.

flutter pub add kasseneck_api

JavaScript und TypeScript: @kreiseck/kasseneck-api auf npm.

npm install @kreiseck/kasseneck-api

Basis-URL

Alle direkten Aufrufe laufen über HTTPS unter der versionierten Basis:

https://api.kasseneck.at/v3/<endpoint>

/v3 ist die aktuelle Fassung aller Endpunkte: englische Feldnamen, Werte und Fehlercodes (Fließtext wie message bleibt deutsch). /v1 und /v2 laufen unverändert weiter, sind aber abgekündigt (Kopfzeilen Deprecation/Sunset/Link, Abschaltung erst nach nachgewiesen null Aufrufen); was sich geändert hat, steht in der OpenAPI je Bereich unter „Migrating from v1“.

Authentifizierung

Geräte-Endpunkte verwenden zwei Merkmale im HTTP-Header:

Header	Beschreibung
`Authorization: Bearer <api_key>`	Geräte-/API-Schlüssel (`kr_live_…` bzw. `kr_test_…`).
`cashregister-token: <token>`	Kassen-Token der Registrierkasse (`cb_live_…` / `cb_test_…`).

Test- und Live-Umgebung

Schlüssel mit dem Präfix kr_test_ arbeiten in einer Sandbox (production:false) mit Testsignatur – strukturell valide, aber keine rechtsgültigen RKSV-Belege. Ideal zum Integrieren. kr_live_ erzeugt echte, rechtsgültige Belege.

Antwortformat

JSON-Endpunkte liefern HTTP 200 mit einem einheitlichen Envelope:

{ "status": "success" | "error", "message": "...", "data": { ... } }

Fachliche Fehler kommen ebenfalls mit HTTP 200 und status: "error".

Endpunkte

POST /v3/createReceipt

Erstellt und signiert einen Beleg. Der erste Beleg einer Kasse muss ein start-Beleg sein, danach folgen standard-Belege. Erfordert das aktive Modul registrierkasse.

receiptType: start, standard, zero, training. Bezahlt wird über die Liste payments (unter /v3 Pflicht, auch mehrere Zahlungen je Beleg); ein Storno läuft über /v3/cancelReceipt.

POST /v3/getReceipt

Ruft einen zuvor erstellten Beleg anhand seiner receiptId ab.

POST /v3/cancelReceipt

Storniert einen Beleg ganz oder teilweise; das Original bleibt unverändert.

GET /v3/downloadReceipt?fullReceiptId=…

Liefert das Beleg-PDF direkt. Autorisierung über den verschlüsselten fullReceiptId-Token aus der createReceipt-Antwort (Capability-Link, kein API-Schlüssel nötig).

Dazu Belegmail, Berichte, Zahlungsterminals und FinanzOnline; alle Endpunkte stehen in der Referenz, Abschnitt Receipts.

Rechnungs-API

Rechnungen nach § 11 UStG (keine Belege) aus Shop, Buchhaltungs- oder Branchensoftware: Kunden, Ausstellen (festgeschrieben, fortlaufend nummeriert), Gutschriften, PDF und E-Rechnung (UBL/CII). Anmeldung mit dem API-Schlüssel des Betriebs, ohne cashregister-token. Alle Endpunkte unter https://api.kasseneck.at/v3/<endpoint> in der Referenz, Abschnitt Invoices.

Lager-API

Artikel, Standorte, Bestand und Lagerbewegungen lesen und jede Bestandsänderung per Webhook erfahren (signiert, mit Wiederholung), etwa um einen Online-Shop mit dem Lager im Geschäft abzugleichen. Anmeldung mit dem API-Schlüssel des Betriebs, nur unter /v3; Mengen als Ganzzahl in Tausendstel, Geld in Cent.

Schreiben ist möglich, sobald Kasseneck „Lager-API schreiben“ für den Betrieb freischaltet: Artikel anlegen, ändern und stilllegen, Wareneingang, Umbuchung, Abgang und Zustand buchen sowie Ware für Bestellungen reservieren – jeder schreibende Aufruf mit idempotencyKey. Der Ablauf einer Bestellung: reservieren (createReservation), dann die Rechnung mit issueInvoice und reservationId je Position ausstellen; beim Buchen der Rechnung wird die Reservierung eingelöst, sonst läuft sie ab oder wird freigegeben. Mindestbestände je Standort melden sich am verfügbaren Bestand (Bestand minus reserviert), per Hinweis an der Buchung und per Webhook stock.below_minimum. Alle Endpunkte und Ereignisse in der Referenz, Abschnitt Inventory.

Varianten (Größe, Farbe, bis zu drei Merkmale) legt ein Shop als Variantengruppe an (createVariantGroup), mit genau den Kombinationen, die er führt, und seiner eigenen Kennung je Variante; jede Variante ist ein gewöhnlicher Artikel mit eigenem Bestand. Eine neue Größe kommt mit updateVariantGroup (addAttributeValues) und addVariant dazu, Änderungen meldet der Webhook variant_group.updated. Grenzen: höchstens 100 Kombinationen je Aufruf, 250 aktive Varianten je Gruppe, 3 Merkmale und 30 Werte je Merkmal.

Inventur je Standort: anlegen (createStocktake, Stichtag oder permanent, standardmäßig blind), von beliebig vielen Geräten zählen (recordStocktakeCount, Zählungen einer Position werden addiert), prüfen (reviewStocktake: erst jetzt gibt es Soll und Differenz, gerechnet zum Zeitpunkt der letzten Zählung je Position), bei Bedarf nachzählen und abschließen (closeStocktake). Der Abschluss bucht die Differenzen im Hintergrund in Teilen und legt ein unveränderliches Protokoll an (getStocktakePdf). Höchstens eine offene Inventur je Standort und 5000 Positionen je Inventur.

Partner-API

Für Partner (Software-Anbieter, Steuerberatungen, Wiederverkäufer), die Betriebe bei Kasseneck anmelden: Anmeldung mit einem Partner-Schlüssel (Authorization: Bearer pk_live_… / pk_test_…) aus dem Partner-Portal, ohne cashregister-token. Ein Betrieb entsteht mit einem Aufruf (createPartnerCustomer, alle Pflichtdaten, Feldfehler mit Pfad, idempotencyKey), danach richtet der Betrieb seinen FinanzOnline-Zugang über einen Link ein; Status und Webhooks (signiert, mit Wiederholung) sagen, wie es weitergeht. Alle Endpunkte, Felder, Fehlercodes, der Statuskatalog und die Signaturprüfung stehen in der Referenz, Abschnitt Partner.

Aktuelle Basis-URL: https://api.kasseneck.at/v3/<endpoint>, englische Feldnamen und Werte durchgehend (Fließtext wie message und note bleibt deutsch). /v1 läuft unverändert weiter, ist aber abgekündigt (siehe oben); die Umstellung steht in der OpenAPI unter „Migrating from v1“.

curl -s https://api.kasseneck.at/v3/getPartnerInfo \
  -H "Authorization: Bearer pk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"params":{}}'

Über die Partner-API laufen auch Signaturantrag (requestCustomerSignature), Kassenanlage und Inbetriebnahme (createCustomerCashregister, activateCashregister) sowie die Zugangsdaten des Betriebs für createReceipt (getCustomerCredentials). Die Referenz ist englisch.

Noch nicht verfügbar: eine laufende Kasse außer Betrieb nehmen und eine defekte Karte ersetzen; beides erledigt Kasseneck. Fragen dazu: hello@kasseneck.at.

Schnellstart

1) Startbeleg (einmalig zuerst pro Kasse):

curl -X POST https://api.kasseneck.at/v3/createReceipt \
  -H "Authorization: Bearer kr_test_…" \
  -H "cashregister-token: cb_test_…" \
  -H "Content-Type: application/json" \
  -d '{"params":{"receiptType":"start"}}'

2) Umsatzbeleg:

curl -X POST https://api.kasseneck.at/v3/createReceipt \
  -H "Authorization: Bearer kr_test_…" \
  -H "cashregister-token: cb_test_…" \
  -H "Content-Type: application/json" \
  -d '{"params":{"receiptType":"standard",
       "items":[{"name":"Kaffee","quantity":2,"unitPriceCents":350,"vatRate":20}],
       "payments":[{"method":"cash","amountCents":700}]}}'

Die Antwort enthält den signierten Beleg (data.receipt.sig, data.receipt.qr) und den fullReceiptId-Token für das PDF.

Vollständige Schemas, alle Felder und Fehlercodes findest du in der interaktiven Referenz und der maschinenlesbaren OpenAPI-Spezifikation. Zugang und Schlüssel auf Anfrage.