6.10. QRK API
Funktion
Das Plugin „QRK API“ stellt eine kleine Schnittstelle für externe Programme bereit (z. B. Rechnungssoftware): ein HTTP-Dienst auf der Kassa, standardmäßig Port 8643. Alle Abfragen brauchen den Header Authorization: Bearer <Token> – nur der Erreichbarkeitstest nicht.
- GET /api/v1/ping – Erreichbarkeitstest, ohne Token.
- GET /api/v1/info – Kassen-ID, Programmversion, Edition, Lizenzstatus und ob die Signaturerstellung aktiv ist.
- GET /api/v1/receipts/last – die letzte Belegnummer mit Zeitstempel, Zahlungsart und Summe.
- POST /api/v1/receipts – bucht einen Beleg (siehe „Beleg buchen“).
Beispiel (Linux):
curl -H "Authorization: Bearer <Token>" http://kassa-ip:8643/api/v1/receipts/last
Antwort (Beispiel):
{"status":"ok","receiptNumber":1042,"timestamp":"2026-11-04T17:23:01","paymentMethod":"cash","total":"45.55"}
Die letzte Belegnummer ist immer die neueste Belegnummer der Kassa – auch ein Tages- oder Zwischenabschluss ist ein echter Beleg.
Beleg buchen
POST /api/v1/receipts bucht einen Beleg. Anders als beim Datei-Import wird hier vorher am Bezahlterminal kassiert und dessen Ergebnis ausgewertet; in Deutschland wird der Beleg über die TSE signiert (ohne aktive TSE keine Buchung). Ein Beleg pro Anfrage, beliebig viele Positionen.
Anfrage (JSON):
{
"receipt": {
"reference": "R-2026-0815",
"payedBy": "0",
"given": "25.00",
"userId": 3,
"items": [
{ "count": "1", "name": "Menü 2", "gross": "12.50", "tax": "10", "unit": "Stk" },
{ "count": "2", "name": "Bier", "gross": "4.20", "tax": "20", "discount": "10", "discounttype": "0" }
]
}
}
Felder:
reference– Pflicht. Rechnungsnummer des externen Programms. Sie darf sich wiederholen (Teilzahlungen zu einer Rechnung); eine bereits gebuchte Nummer wird nicht doppelt gebucht.items– Pflicht, mindestens eine Position.count,name,gross,tax– je Position Pflicht.grossist der Einzelpreis brutto,taxder Steuersatz in Prozent.productIdbzw.itemnum– optional. Fehlt beides, legt die Kassa den Artikel über den Namen an bzw. verwendet den vorhandenen.discountmitdiscounttype– optional;discounttypeals Text: „0“ = Prozent, „1“ = Betrag. Andere Werte lehnt die API ab (400).description– optional. Notiz, die auf dem Bestellbon erscheint.unit– optional. Einheit für den Export, sonst „Stk“.payedBy– Zahlart als Text: „0“ Bar (Standard), „1“ Bankomat, „2“ Kreditkarte, „3“ Gutschein. Andere Werte werden mit 400 abgelehnt, einen stillen Rückfall auf Bar gibt es nicht.secondPayedBy– optional, zweite Zahlart für Mischzahlungen („1“, „2“ oder „3“). Nur zusammen mitpayedBy„0“ (Bar) oder „3“ (Gutschein):givenist dann der Baranteil, der Rest geht auf die zweite Zahlart.given– Betrag für die Kartenzahlung am Terminal, bei Mischzahlung der Baranteil. Fehlt er, nimmt die Kassa die Summe der Positionen (bzw.total).userId– optional. Ordnet den Beleg einem Benutzer zu; sonst gilt der an der Kassa angemeldete.
Ablauf:
- Prüfung: „Nur lesen“ abgeschaltet, Kassa im Importmodus, in Deutschland aktive TSE,
referencenoch nicht gebucht. - Kartenzahlung: Betrag geht ans Bezahlterminal, die Kassa wartet auf das Ergebnis (Zeitüberschreitung 504, Abbruch oder Ablehnung 409). Bei einer Mischzahlung (Bar + Karte) wird der Kartenanteil nicht ans Terminal übergeben – er wird gebucht wie beim Datei-Import, die Karte wird also am Terminal separat gezogen.
- Buchung wie an der Kassa: Positionen, Signatur, Zahlung; der Beleg wird gedruckt.
- Antwort mit Belegnummer und Signatur.
Antwort (Beispiel):
{"status":"ok","duplicate":false,"receiptNum":1043,"signature":"…"}
Mögliche Fehlerantworten: 400 (unlesbares JSON, fehlende Pflichtfelder, ungültige Zahlart, Rabattart oder Betrag), 403 (Schnittstelle auf „Nur lesen“), 409 (Kassa nicht im Importmodus), 409 (am Terminal abgelehnt oder abgebrochen), 422 (Beleg konnte nicht gebucht werden), 423 (es läuft bereits eine Buchung), 500 (am Terminal abgebucht, Beleg fehlgeschlagen – dann Storno am Terminal), 503 (in Deutschland ohne aktive TSE), 504 (Terminal antwortet nicht).
Einrichtung
Aktivierung, Port und Zugriffs-Token werden in den Plugin-Einstellungen gesetzt (Einstellungen → Plug-ins → QRK API); der Token wird beim ersten Öffnen vorgeschlagen und erst mit „Speichern“ übernommen – der Dienst startet danach automatisch neu.
Die Schnittstelle ist standardmäßig auf „Nur lesen“ gestellt: die Abfragen funktionieren, Belege werden nicht angelegt. Erst wenn „Nur lesen“ abgeschaltet ist, bucht die API; solange sie bucht, bleibt der Datei-Import der Kassa gesperrt – und umgekehrt.
Hinweis: Die Schnittstelle überträgt den Token im Klartext (kein TLS), sie ist daher für das lokale Netzwerk bzw. „Nur lokal (Loopback)“ gedacht; ein Request pro Verbindung (kein Keep-Alive).
