Eine Zahlung am Beleg — Zwilling von ReceiptPayment in
@kreiseck/kasseneck-api (models/receipt-payment.ts) und der Eintraege,
die functions/gemeinsam/zahlungen-core.js unter payments ablegt.
Das Blatt am Bildschirm -- Zeile fuer Zeile dieselben Zeichen wie am Bon
und im PDF (Zwilling von BelegBlattView im npm-Paket). Eine Zeile ist
zwei Zeichenbreiten hoch, Logo und QR stehen in ihrem Blattanteil. Die
Zeichenbreite wird an der Schrift gemessen, nicht angenommen.
Eine Position fuer die Rechnung. Anders als KasseneckItem darf die Menge
hier ein Bruch sein (0,375 kg) und der Steuersatz jeder Wert, den ein
Beleg tragen kann; ReceiptDueLine.of macht aus einer Position eine Zeile.
Ein Beleg in listReceipts (view: summary): die Zeile einer Liste,
Betraege in ganzen Cent. Fuer Kopf, Layout und Pruefangaben gehoert der
Beleg einzeln ueber getReceipt geholt.
Ein Eintrag aus outputs einer getReceipt-Antwort (/v3), gelesen am
Beleg (KasseneckReceipt.outputs). Eine Art oder ein Ergebnis, das dieses
Paket noch nicht kennt (neuerer Server), bleibt lesbar stehen; die Kasse
zeigt es ohne Beschriftung (receiptOutputLabel gibt dann null).
Registrierdaten fuer den Block „Prüfangaben“ am Nullbeleg (Regelwerk 2):
wann die Signaturkarte und wann die Kasse bei FinanzOnline registriert
wurden. Zwilling von RegistrationInfo in @kreiseck/kasseneck-api 1.0,
Drahtfeld registrationInfo (frueher pruefangaben).
Das Kasseneck-Logo am Belegende, als Rasterbild fest in width x height
Druckpunkten -- diese Masse kommen aus brandMarkRasters, nicht aus einem
Anteil der Blattbreite: das Raster liegt fertig vor (Vertrag), nur welches
der beiden Masse gilt, entscheidet die Papierbreite.
Je Einloesung bzw. Auszahlung der neuen Form die gepruefte Sicht des
Gutscheins (aus checkVoucher), zugeordnet ueber den Code. Zwilling von
VoucherDueInfo im npm-Paket.
Storno-Stand eines Belegs in der Liste (Drahtfeld cancellationStatus,
Katalog STORNO_STAND): none, partial, full. Ein unbekannter
kuenftiger Wert kommt als CancellationState.unknown an und nie als none: die
Kasse bietet dann keinen Storno an (siehe canCancel), der Server
haelt ohnehin die Restmengen.
Ausgang eines gescheiterten Aufrufs. rejected: nichts geschehen.
unknown: der Vorgang kann ausgefuehrt sein (ein Beleg signiert, ein
Storno gebucht, Ware gebucht, eine Rechnung ausgestellt); nie blind
wiederholen. Belege, Stornos und Zahlungen nachlesen; ein Aufruf mit
idempotencyKey nur mit demselben Schluessel erneut senden (wirkt
genau einmal, ein neuer buchte doppelt); ohne Schluessel erst nachlesen.
Ton einer hervorgehobenen Zeile, Drahtwert tone (Katalog LAYOUT_TON):
receipt_type fuer die Belegart (STORNOBELEG …), warning fuer
TESTKASSE/TESTSIGNATUR und den Ausfall der Signatureinheit.
Die Gründe, die das Backend annimmt – Codes wie unter /v3 (Katalog
STORNO_GRUND), Beschriftung für den Bildschirm und den Bon (bleibt
deutsch, sie steht so am Beleg). Reihenfolge wie im Katalog des Backends.
Codes, die das Paket selbst vergibt, nicht der Server: route_missing
(HTML statt Backend, der Aufruf kam nie an) und response_unreadable
(ein signierender Aufruf meldete Erfolg, die Antwort ist aber unlesbar).
dialect_mismatch vergibt das Paket ebenfalls, der Code gehoert aber zum
Rand des Servers.
Warum sich der Zahlbetrag nicht rechnen laesst (ReceiptDueError.reason).
Fest wie ein Backend-Code; dieselbe Liste im npm-Paket
(RECEIPT_DUE_ERROR_REASONS) und in receipt-due-errors.json.
Stabile Fehlercodes von listReceipts unter /v3. Sie kommen als
KasseneckApiError.code an; die Eingabefehler darunter faengt das Paket
schon vor dem Senden ab (KasseneckValidationError, kind: request),
ankommen koennen sie trotzdem (ein Cursor einer anderen Abfrage:
invalid_cursor). Dahinter die Codes von Anmeldung und Rand.
Hoechstens so viele Seiten holt listAllReceipts, dann bricht es mit
einem Fehler ab. Mit 500 je Seite sind das 50.000 Belege in einem Fenster;
mehr deutet auf eine Schleife, nicht auf eine Kasse.
Codes je Eintrag in rejected[].code einer Antwort von
logReceiptOutputs: der Eintrag ist dauerhaft abgelehnt (aus dem Puffer
nehmen, nicht noch einmal senden). validation heisst hier: ein Druck ohne
oder mit unbekanntem Ergebnis.
Arten einer Ausgabe des Belegs (Katalog AUSGABE_ART): print
Erstdruck, reprint Duplikat, email Belegmail, link_shared Link
geteilt, pdf_shared PDF geteilt, opened vom Kunden geoeffnet (Abrufe
je Stunde). Zwilling von RECEIPT_OUTPUT_KINDS.
Die Arten, die eine Kasse selbst meldet (RECEIPT_OUTPUT_LOG_KINDS).
email und opened schreibt das Backend selbst; meldet eine Kasse sie,
lehnt der Server genau diesen Eintrag ab (invalid_output_kind).
Stichtag des 0-%-Topfs fuer Mehrzweck-Verkaeufe (Backend
gutschein-core.NULLTOPF_AB). Solange er in der Zukunft liegt, zaehlt ein
Mehrzweck-Verkauf als Fluss; ab dem Tag als Position im 0-%-Satz. Der
Zahlbetrag bleibt gleich, Toepfe und Fluss verschieben sich.
Codes von createReceipt und getReceipt (ohne die Zahlungscodes, die
stehen in paymentErrorCodes). receipt_outcome_unknown heisst: der
Beleg ist moeglicherweise signiert, nachlesen statt wiederholen.
Codes von logReceiptOutputs, wenn die ganze Anfrage scheitert
(Vokabular errorCodes.registerHandlersByEndpoint.logReceiptOutputs),
dahinter Anmeldung und Rand, zuletzt route_missing. Zwilling von
RECEIPT_OUTPUT_ERROR_CODES.
Kennung der Originalzahlung fuer die Rueckbuchung am Terminal (Hobex
originalTransactionId, SumUp-Transaktion …): providerPaymentId der
Zahlung paymentId des Originals. Die liefert nur der Kassenweg
(kasse.kasseneck.at/api/v3, Kanal app); am oeffentlichen Weg fehlt sie,
und dann wirft dieser Aufruf, statt null an ein Terminal weiterzugeben.
Zwilling von cardRefundReference im npm-Paket.
Stabile Fehlercodes von cancelReceipt unter /v3 – Zwilling von
CANCELLATION_ERROR_CODES in @kreiseck/kasseneck-api 1.0, in derselben
Reihenfolge (siehe receipt/codes.dart). Das Backend legt sie als code
neben die Meldung; sie kommen als KasseneckApiError.code an.
Entscheide am Code, nie am Text. Formfehler an payments selbst melden
die Codes aus paymentErrorCodes. cancellation_outcome_unknown heisst:
der Storno ist moeglicherweise gebucht; nie wiederholen, sondern das
Original nachlesen.
Ist value ein Code aus cancellationErrorCodes? Ein Anzeigetext ist keiner,
ein alter deutscher oder grosser Code aus /v1 auch nicht.
Ist der Ausgang dieses Fehlers unklar? Dann den Aufruf nicht blind
wiederholen: Belege, Stornos und Zahlungen nachlesen; einen Aufruf mit
idempotencyKey nur mit demselben Schluessel erneut senden; ohne
Schluessel erst nachlesen (siehe ErrorOutcome). Gilt fuer jede
Fehlerart; nur KasseneckApiError und KasseneckHttpError koennen unklar
sein.
Die Codes, gleiche Reihenfolge wie PAYMENT_ERROR_CODES.
Ist value ein Code aus paymentErrorCodes? Exakt, wie unter /v3
(klein); ein grosser Code aus /v1 ist keiner. Ein Anzeigetext auch nicht.
Stabile Fehlercodes von sendReceiptEmail unter /v3 – Zwilling von
RECEIPT_EMAIL_ERROR_CODES (siehe receipt/codes.dart). Sie kommen als
KasseneckApiError.code an – entscheide am Code, nie am Text, der
deutsche Satz darf sich jederzeit aendern.
Laedt das Logo unter url und rastert es in die Groesse, die das Blatt
size und paper geben (logoDimensions/logoRaster) -- null ohne Adresse
oder bei jedem Fehler (Netz, Decode, Pixelmass). pixel ersetzt den
Standardweg ueber LogoService/decodePng (Tests, andere Quellen).
Kennzeichnet einen Nachdruck als Belegduplikat (Zwilling von
markAsDuplicate in @kreiseck/kasseneck-api/receipt).
Registrierkassen-Erlass BMF-AV Nr. 2/2026, Abschnitt 4.5.6: „Ein
Belegduplikat ist als solches zu bezeichnen, nicht nochmals zu signieren,
nicht neuerlich im Datenerfassungsprotokoll aufzunehmen und darf zu keiner
Veränderung des Umsatzzählers führen.“ Signatur, DEP und Zähler bleiben
ohnehin unberührt, weil ein Nachdruck den gespeicherten Beleg druckt; diese
Funktion liefert die Bezeichnung.
Bringt einen Beleg in der gespeicherten Form von 9.x (toJson mit 0.x-
Namen: uid, taxnr, logo_skala, testCashregister, testSignatur, kopfId,
Layout mit regelwerk/ton; an Storno-Zeilen und in cancellations[]rueckgabe statt returnDisposition, dazu lagerStandortId, das wegfaellt)
in die Form von /v3, die
KasseneckReceipt.fromJson liest. Fuer lokale Ablagen, die das Update
ueberleben muessen: gelesen wird migriert, verworfen wird nichts. Schon
englische Schluessel bleiben, wie sie sind; ein englischer Schluessel
gewinnt immer gegen seinen deutschen Vorgaenger. stored bleibt unberuehrt.
Der Zahlbetrag des Servers aus einem payments_sum_mismatch
(details.expectedCents), sonst null. Das Paket wiederholt nie selbst mit
diesem Betrag: eine Kartenzahlung ist schon belastet. Die Kasse entscheidet
(Differenz nachkassieren oder erstatten) und schickt dann einen neuen
Verkauf. Zwilling von paymentsExpectedCents im npm-Paket.
Ein gespeichertes Zeilenmodell (layout) in der Form von /v3, wie
ReceiptLayout.fromJson es liest. Zwilling von fromStoredLayout im
npm-Paket: nimmt die Form von 0.x bzw. 9.x (regelwerk, Bannerzeilen mit
tonbelegart/warnung) und die Form 1.0 (ruleset, tonereceipt_type/warning); ein unbekannter Ton geht woertlich durch. Die
Schluessel werden an ihrer Stelle umbenannt, die Reihenfolge bleibt; traegt
ein Objekt beide Namen, gewinnt der englische.
Die Antwort war keine brauchbare Huelle {status, data} oder der HTTP-Weg
scheiterte. Traegt bewusst nichts aus dem Rumpf: dort koennten Werte
stehen, die wir gerade nicht ins Protokoll lassen wollen.
Der Aufrufer hat etwas nicht mitgegeben, oder die Antwort trug nicht, was
der Aufruf zusagt. Die Meldung nennt immer nur das Feld, nie seinen
Wert — sonst stuende ein Geraetegeheimnis im Protokoll.
Der Zahlbetrag laesst sich aus dieser Eingabe nicht rechnen, etwa
Trinkgeld mit Betrag ohne Ware (reasontip_without_goods). Zwilling von
ReceiptDueError im npm-Paket.
