API-Referenz

Kasseneck API v2.0.0

Österreichische Registrierkassen-/RKSV-API für Belegerstellung und -abruf.

Interaktive API-Referenz öffnen ↗ OpenAPI-Spec

Basis-URL https://api.kasseneck.at empfohlen: /v2

Antwort-Envelope { status, message, data }

Die Kasseneck API ist eine HTTPS-Schnittstelle für österreichische Registrierkassen nach RKSV (Registrierkassensicherheitsverordnung, BAO §131, BMF-DEP). Damit erstellst du signierte Belege (Startbeleg, Umsatzbeleg, Storno, Training, Nullbeleg), rufst Belege ab und lädst Beleg-PDFs.

Kasseneck ist ein Produkt der Kreiseck und richtet sich an POS-/Kassensysteme, Kassenhersteller und Integrationspartner in Österreich.

Für Flutter/Dart gibt es das offizielle Paket kasseneck_api auf pub.dev.

Authentifizierung

Geräte-Endpunkte nutzen zwei Merkmale:

Authorization: Bearer <api_key> — der Geräte-/API-Schlüssel (Format kr_live_… bzw. kr_test_… für die Testumgebung).
cashregister-token: <token> — der Kassen-Token (Format cb_live_… /cb_test_…), identifiziert die konkrete Registrierkasse.

Umgebungen

Live: echte, rechtsgültige RKSV-Belege (Schlüssel kr_live_…).
Test: Sandbox mit Testsignatur (kr_test_…), production:false — strukturell valide, aber keine rechtsgültigen Signaturen. Ideal zum Integrieren ohne echte steuerliche Wirkung.

Antwortformat

Alle JSON-Endpunkte liefern HTTP 200 mit einem Envelope: { "status": "success" | "error", "message": string, "data": object }. Fachliche Fehler kommen ebenfalls mit HTTP 200 und status: "error".

Versionen

Empfohlen ist v2 (/v2/…) mit der Positionsform { name, quantity, unitPriceCents, vatRate } — Preise in ganzen Cent (keine Fließkommazahlen). Die v1-Endpunkte (/v1/…) und die v1-Positionsform (amount, priceOne, vat) bleiben aus Kompatibilität gültig (deprecated).

Technischer Kontakt · IT & Integration +43 670 301 5780 Direkt bei Integrations- und Anbindungsfragen

In drei Schritten produktiv

API-Key anfordern — Sandbox-Zugang (kr_test_…) sofort, ohne Vertrag.

Startbeleg signieren — der erste Aufruf von createReceipt muss receiptType: start sein.

Umsatzbelege signieren — danach jeder Barbeleg per createReceipt, signiert samt QR-Code-Daten zurück.

# Startbeleg (einmalig zuerst)

curl -X POST https://api.kasseneck.at/v2/createReceipt \

-H "Authorization: Bearer kr_test_…" \

-H "cashregister-token: cb_test_…" \

-d '{"params":{"receiptType":"start"}}'

→ status: "success" · signatureSuccess: true

# Umsatzbeleg (bar)

curl -X POST https://api.kasseneck.at/v2/createReceipt \

-d '{"params":{"receiptType":"standard","paymentMethod":"cash","items":[{"name":"Kaffee","quantity":2,"unitPriceCents":350,"vatRate":20},{"name":"Brot","quantity":1,"unitPriceCents":220,"vatRate":10}]}}'

→ data.receipt.qr: "…"

Endpunkte

POST /v2/createReceipt

Beleg erstellen und RKSV-signieren

Erstellt einen Beleg und signiert ihn (ES256, verkettete RKSV-Signatur → DEP). Der erste Beleg einer Kasse muss ein start-Beleg sein und erfolgreich signiert werden; danach standard-Belege usw.

Voraussetzung: aktives Modul registrierkasse für das Konto.

Hinweis: receiptId und Zeitstempel werden serverseitig vergeben.

Auth

ApiKeyAuth: Geräte-/API-Schlüssel im Bearer-Header (kr_live_… / kr_test_…).

CashregisterToken: Kassen-Token der Registrierkasse (cb_live_… / cb_test_…).

Alle Felder werden innerhalb von params gesendet: { "params": { … } }

Feld	Typ	Pflicht	Beschreibung
`receiptType`	string (`start` \| `standard` \| `zero` \| `cancellation` \| `training`)	Pflicht	`start` = Startbeleg (einmalig zuerst, ohne Positionen). `standard` = Umsatzbeleg. `cancellation` = Storno. `training` = Trainingsbeleg (kein Umsatz). `zero` = Nullbeleg.
`paymentMethod`	string (`cash` \| `creditCard` \| `online` \| `uberApp` \| `uberCard` \| `uberCash` \| `boltApp` \| `boltCash` \| `boltCard`)	optional	Zahlungsart. Pflicht bei `standard`, `cancellation`, `training`.
`items`	ReceiptItem[]	optional	Belegpositionen (Pflicht bei `standard`/`cancellation`/`training`).
`vouchers`	Voucher[]	optional	Optionale Gutschein-Vorgänge (Verkauf/Einlösung).
`customerDetails`	string	optional	Optionale Kundenangabe auf dem Beleg.
`legalMessage`	string	optional	Optionaler rechtlicher Hinweistext.
`customProjectId`	string	optional	Optionale eigene Projekt-/Referenz-ID.

Startbeleg (einmalig zuerst)

{
  "params": {
    "receiptType": "start"
  }
}

Standard-Umsatzbeleg (bar)

{
  "params": {
    "receiptType": "standard",
    "paymentMethod": "cash",
    "items": [
      {
        "name": "Kaffee",
        "quantity": 2,
        "unitPriceCents": 350,
        "vatRate": 20
      },
      {
        "name": "Brot",
        "quantity": 1,
        "unitPriceCents": 220,
        "vatRate": 10
      }
    ]
  }
}

Antwort

Code	Typ	Beschreibung
`200`	ReceiptEnvelope	Envelope mit signiertem Beleg oder Fehler.

POST /v2/getReceipt

Beleg abrufen

Liefert einen zuvor erstellten Beleg der Kasse anhand seiner receiptId.

Auth

ApiKeyAuth: Geräte-/API-Schlüssel im Bearer-Header (kr_live_… / kr_test_…).

CashregisterToken: Kassen-Token der Registrierkasse (cb_live_… / cb_test_…).

Alle Felder werden innerhalb von params gesendet: { "params": { … } }

Feld	Typ	Pflicht	Beschreibung
`receiptId`	string	Pflicht	ID des Belegs (aus der createReceipt-Antwort).

{
  "params": {
    "receiptId": "abc123"
  }
}

Antwort

Code	Typ	Beschreibung
`200`	ReceiptEnvelope	Envelope mit dem Beleg oder Fehler.

GET /v2/downloadReceipt

Beleg-PDF laden (Capability-Link)

Liefert das Beleg-PDF direkt (application/pdf). Autorisierung erfolgt ausschließlich über den verschlüsselten fullReceiptId-Token aus der createReceipt-Antwort — kein API-Schlüssel nötig. Der Token ist ein Capability-Link (wer ihn hat, sieht das PDF).

Auth

Kein API-Schlüssel nötig.

Feld	Ort	Typ	Pflicht	Beschreibung
`fullReceiptId`	Query	string	Pflicht	Verschlüsselter Beleg-Token aus `data.receipt.fullReceiptId`.

Antwort

Code	Typ	Beschreibung
`200`	PDF (binär)	PDF-Datei.
`400`	—	Beleg-Link unvollständig.
`404`	—	User oder Beleg nicht gefunden.

Schema-Referenz

Die vollständigen Felder der Objekte, die in den Endpunkten oben verwendet werden.

CreateReceiptParams

Feld	Typ	Pflicht	Beschreibung
`receiptType`	string (`start` \| `standard` \| `zero` \| `cancellation` \| `training`)	Pflicht	`start` = Startbeleg (einmalig zuerst, ohne Positionen). `standard` = Umsatzbeleg. `cancellation` = Storno. `training` = Trainingsbeleg (kein Umsatz). `zero` = Nullbeleg.
`paymentMethod`	string (`cash` \| `creditCard` \| `online` \| `uberApp` \| `uberCard` \| `uberCash` \| `boltApp` \| `boltCash` \| `boltCard`)	optional	Zahlungsart. Pflicht bei `standard`, `cancellation`, `training`.
`items`	ReceiptItem[]	optional	Belegpositionen (Pflicht bei `standard`/`cancellation`/`training`).
`vouchers`	Voucher[]	optional	Optionale Gutschein-Vorgänge (Verkauf/Einlösung).
`customerDetails`	string	optional	Optionale Kundenangabe auf dem Beleg.
`legalMessage`	string	optional	Optionaler rechtlicher Hinweistext.
`customProjectId`	string	optional	Optionale eigene Projekt-/Referenz-ID.

ReceiptItem

Empfohlene v2-Form. Die v1-Felder (amount, priceOne, vat) werden aus Kompatibilität weiterhin akzeptiert, sind aber deprecated.

Feld	Typ	Pflicht	Beschreibung
`name`	string	Pflicht	Bezeichnung der Position.
`quantity`	number	Pflicht	Menge.
`unitPriceCents`	integer	Pflicht	Einzelpreis (brutto) in ganzen Cent — keine Fließkommazahlen (vermeidet Rundungsfehler).
`vatRate`	number (`20` \| `10` \| `13` \| `0` \| `19` \| `4.9`)	Pflicht	USt-Satz in Prozent (österreichische Sätze inkl. Sonder-/Grundnahrungssätze).
`amount`veraltet	number	optional	v1 (deprecated): Menge — nutze stattdessen quantity.
`priceOne`veraltet	number	optional	v1 (deprecated): Einzelpreis in Euro (Fließkomma) — nutze stattdessen unitPriceCents.
`vat`veraltet	number	optional	v1 (deprecated): USt-Satz — nutze stattdessen vatRate.

Voucher

Feld	Typ	Pflicht	Beschreibung
`action`	string (`sell` \| `redeem`)	Pflicht
`type`	string (`value` \| `promo`)	Pflicht
`code`	string	optional	Gutscheincode (Default "no-code").
`value`	number	optional	Wert (>0). Pflicht bei type=value.
`name`	string	optional
`valueCents`	integer	optional	Wert in Cent (Vorrang).

ReceiptEnvelope

Feld	Typ	Pflicht	Beschreibung
`status`	string (`success` \| `error`)	optional
`message`	string	optional
`data`	object	optional
`data.receipt`	Receipt	optional
`data.company`	string	optional	Firmenname des Unternehmers.
`data.uid`	string \| null	optional	USt-IdNr des Unternehmers.
`data.taxnr`	string \| null	optional
`data.is_small_business`	boolean	optional

Receipt

Der gespeicherte, signierte Beleg.

Feld	Typ	Pflicht	Beschreibung
`counter`	integer	optional	Fortlaufender Zähler der Kasse.
`receiptType`	string	optional
`receiptId`	string	optional
`cashregisterId`	string	optional
`timeStamp`	string	optional	Beleg-Zeitstempel (Europe/Vienna).
`amountRateStandard`	number	optional
`amountRateReduced1`	number	optional
`amountRateReduced2`	number	optional
`amountRateZero`	number	optional
`amountRateSpecial`	number	optional
`certificateSerialNumber`	string	optional
`signaturePreviousReceipt`	string	optional	Verkettung zum Vorbeleg (RKSV).
`fullReceiptId`	string	optional	Verschlüsselter Token für den PDF-Download.
`sig`	string	optional	JWS ES256: header.payload.signature.
`signatureSuccess`	boolean	optional
`qr`	string	optional	Maschinenlesbarer QR-Text des Belegs.

Mehr

Kasseneck ist ein Produkt der Kreiseck.