@kreiseck/kasseneck-api 1.21.0 → 1.22.0

package/CHANGELOG.md

@@ -4,6 +4,22 @@ Was vor 0.7.0 geschah, steht in der Commit-Historie (`git log`); ab hier wird
 es hier geführt. Ein Eintrag nennt die Änderung **und ihren Grund** —
 nur der Grund überlebt den nächsten Umbau.
 
+## 1.22.0 - 2026-10-31
+
+Idempotent sales: `createReceipt` can carry an `idempotencyKey` (the backend evaluates it under `/v3` since 26.10.2026). Additive; without a key the request stays byte for byte as before.
+
+- **`idempotencyKey?: string` on `sellReceipt`, `sellReceiptWithCompany` and `createReceipt`** (in `ReceiptCommonOptions`, so also on `createKasseneckApi().sellReceipt…`), sent as `params.idempotencyKey`. Per register: the same request with the same key returns the receipt already signed (no second receipt, no counter step; the plain codes of newly sold vouchers only the first time); the same key with other content is rejected with `idempotency_conflict` and nothing is written. Use a stable id of your own transaction (order number, number of the paper replacement receipt), never one made up per attempt. When recording a paper receipt (`manualReceipt`) the server also refuses the same paper number on the same day with `manual_receipt_duplicate`, a second, independent lock. Reason: after a lost answer (`outcome: 'unknown'`) a sale could only be looked up, never resent; with a key the same request can go out again unchanged.
+- **Checked before sending like the server** (`beleg-idempotenz-core`): a string of 1 to 120 characters (`String.length`), not only whitespace. Empty, whitespace, longer or not a string throws `KasseneckValidationError` (`scope: 'request'`) before anything is sent; the key is never shortened or trimmed, because the server recognises the repeat by the key as it arrives. Missing or `null` sends no field.
+- **`ReceiptWithCompany.replayed?: true`**: set by `sellReceiptWithCompany` when the server answered with `replayed: true` (the receipt of the first attempt). Missing otherwise, also on the first sale with a key, so the result keeps its shape. `sellReceipt` returns the `Receipt` alone and does not show it.
+- `cancelReceipt` takes no key: the backend's cancellation endpoint does not evaluate one; after `cancellation_outcome_unknown` look the original up as before. `zeroReceipt` is unchanged.
+
+## 1.21.1 - 2026-10-31
+
+Paying out a voucher that is no longer active names its status (twin of the backend rule `gutschein-core.darfAuszahlen`, keck, same day). Nothing else changes.
+
+- **A payout checks `cancelled` and `blocked` first.** `receiptDueCents` and `receiptDueBreakdown` with a `payout` wish reject a cancelled voucher with `voucher_cancelled` and a blocked one with `voucher_blocked`, before the balance and before `payout: 'never'`. Reason: cancelling a voucher sale sets its balance to 0, so the register told the cashier "already used up" (`voucher_used_up`) for a cancelled voucher. Used up and paid out stay `voucher_used_up`.
+- `fixtures/receipt-due-voucher-generated.json` regenerated from the backend with that rule (486 cases): four fixed payout cases at the end (`gen_voucher_482` to `485`: cancelled, cancelled with `never`, blocked with `never`, used up). The generator now maps the stored status into the check (`STATUS`); the random cases stay `active` and keep their bytes.
+
 ## 1.21.0 - 2026-10-31
 
 DEP export at the cash register (*Kassennachschau*, stage 2): the five DEP calls now also run on the register path, for the manager only, plus the words and the folder name both registers use. Additive.

package/README.md

@@ -514,14 +514,15 @@ transaction by its `transactionId`, the Stripe session).
 
 **With an `idempotencyKey`** (inventory writes and reservations, `issueInvoice`,
 `cancelInvoice`, `createCreditNote`, `recordInvoicePayment`, `createCustomer`
-and `createPartnerCustomer` with a key) the safe retry after `'unknown'` is the
+and `createPartnerCustomer` with a key, and since 1.22.0 `sellReceipt` and
+`sellReceiptWithCompany` with a key) the safe retry after `'unknown'` is the
 same request with the **same** key: it takes effect exactly once and returns
-the stored answer (invoices and partner customers mark it with
-`replayed: true`; inventory writes return the stored answer unchanged). Never a
-new key: that books a second time. `createInvoiceItem` has no key; the server recognises a repeat by
+the stored answer (invoices, partner customers and `sellReceiptWithCompany`
+mark it with `replayed: true`; inventory writes return the stored answer
+unchanged). Never a new key: that books a second time. `createInvoiceItem` has no key; the server recognises a repeat by
 `source` + `reference`, so the same request with the same values is safe
 (`replayed: true`; other data gives `item_reference_conflict`). Without a key
-(receipts, cancellations, money calls, settings, webhooks, `updateCustomer`,
+(receipts without one, cancellations, money calls, settings, webhooks, `updateCustomer`,
 `createCustomer` and `createPartnerCustomer` without one, `updateInvoiceItem`,
 `withdrawInvoiceItem`, `setCustomerMandate`, `revokeCustomerMandate`) read the
 state first (for invoice items `getInvoiceItem`) and only then decide.
@@ -545,6 +546,21 @@ try {
 }
 ```
 
+**A sale with a key of your own** (since 1.22.0): pass a stable id of the
+transaction, for example the order number or the number of the paper
+replacement receipt, never one made up per attempt. The key holds per
+register, has at most 120 characters and goes out unchanged. After
+`isOutcomeUnknown(error)` the same request with the same key returns the
+receipt of the first attempt instead of signing a second one; the same key
+with other content gives `idempotency_conflict`, and nothing is written. When
+recording a paper receipt (`manualReceipt`) the server also refuses the same
+paper number on the same day (`manual_receipt_duplicate`).
+
+```ts
+const result = await api.sellReceiptWithCompany({ items, payments, idempotencyKey: `order-${orderNumber}` });
+if (result.replayed) showAlreadyIssued(result.receipt); // the receipt of the first attempt
+```
+
 ## Receipts
 
 The facade from `createKasseneckApi` offers `sellReceipt` and

package/dist/cjs/client/receipts.d.ts

@@ -26,7 +26,10 @@ import type { SheetLogoSize } from '../receipt/blatt.js';
  * (`receipt_outcome_unknown`, `cancellation_outcome_unknown`, Netz- oder
  * Serverfehler nach dem Senden) erst nachlesen, und bei
  * `payments_sum_mismatch` nennt [paymentsExpectedCents] den Betrag des
- * Servers; auch dann wiederholt das Paket nie selbst.
+ * Servers; auch dann wiederholt das Paket nie selbst. Ausnahme fuer den
+ * Aufrufer: ein Verkauf mit `idempotencyKey` darf nach einem unklaren Ausgang
+ * unveraendert mit **demselben** Schluessel erneut hinaus (siehe
+ * [ReceiptCommonOptions.idempotencyKey]).
  *
  * **Kassen-Benutzer-Weg (`registerUserAuth`, Browser-Kasse):** Von den
  * Endpunkten dieser Datei setzen [listMyReceipts], [getReceipt],
@@ -62,6 +65,27 @@ export interface ReceiptCommonOptions {
      * Hauptlade der Kasse. Leer oder kein Text: wirft vor dem Senden.
      */
     drawerId?: string;
+    /**
+     * Schutz vor einem zweiten Beleg, wenn die Antwort verloren geht (Netzabbruch,
+     * Zeitablauf, `outcome: 'unknown'`). Gilt je Kasse: dieselbe Anfrage mit
+     * demselben Schluessel liefert den schon signierten Beleg zurueck, ohne neuen
+     * Beleg, ohne Zaehlerschritt (beim `…WithCompany`-Aufruf mit `replayed: true`;
+     * Klartext-Codes neu verkaufter Gutscheine nur beim ersten Mal). Derselbe
+     * Schluessel mit anderem Inhalt wird mit `idempotency_conflict` abgewiesen,
+     * geschrieben wird dann nichts.
+     *
+     * Empfohlen ist eine eigene, stabile Kennung des Vorgangs (Bestellnummer,
+     * Nummer des Ersatzbelegs), nie eine je Versuch neu erzeugte: nach einem
+     * unklaren Ausgang geht dieselbe Anfrage mit **demselben** Schluessel erneut
+     * hinaus; ein neuer Schluessel waere ein zweiter Beleg. Bei der Nacherfassung
+     * ([manualReceipt]) sperrt der Server dieselbe Handbeleg-Nummer am selben Tag
+     * zusaetzlich mit `manual_receipt_duplicate`.
+     *
+     * Text mit 1 bis 120 Zeichen (Laenge wie `String.length`), geht unveraendert
+     * hinaus. Leer, nur Leerraum, laenger oder kein Text: wirft vor dem Senden,
+     * nie gekuerzt. Ohne Angabe (oder `null`) bleibt der Aufruf wie bisher.
+     */
+    idempotencyKey?: string;
 }
 /** Trinkgeld mit eigener Zahlart und/oder Empfaengern (Kassen-Benutzer-IDs, Summe = cents). */
 export interface TipOptions {
@@ -231,6 +255,12 @@ export interface ReceiptWithCompany {
      * faellt weg, der Beleg bleibt lesbar.
      */
     outputs?: ReceiptOutput[];
+    /**
+     * Nur nach einem Verkauf mit `idempotencyKey`: `true`, wenn der Server den
+     * schon signierten Beleg zu diesem Schluessel zurueckgab (Wiederholung, kein
+     * neuer Beleg). Fehlt sonst, auch beim ersten Verkauf mit Schluessel.
+     */
+    replayed?: true;
 }
 /**
  * Das Zeilenmodell zum Drucken und Anzeigen eines Belegs aus einer Antwort.

package/dist/cjs/client/receipts.js

@@ -209,8 +209,25 @@ function createReceiptParams(options) {
     if (options.drawerId !== undefined) {
         params['drawerId'] = ladeKennung('createReceipt', options.drawerId);
     }
+    if (options.idempotencyKey != null) {
+        params['idempotencyKey'] = belegSchluessel(options.idempotencyKey);
+    }
     return params;
 }
+/** Hoechstlaenge des `idempotencyKey` am Beleg, wie am Server (beleg-idempotenz-core `SCHLUESSEL_MAX`). */
+const BELEG_SCHLUESSEL_MAX = 120;
+/**
+ * Der Idempotenz-Schluessel eines Belegs: dieselbe Regel wie am Server (Text,
+ * nicht nur Leerraum, hoechstens 120 Zeichen). Er geht unveraendert hinaus:
+ * der Server erkennt die Wiederholung am Schluessel, wie er ankommt, ein
+ * gekuerzter oder getrimmter waere ein anderer.
+ */
+function belegSchluessel(wert) {
+    if (typeof wert !== 'string' || wert.trim() === '' || wert.length > BELEG_SCHLUESSEL_MAX) {
+        throw eingabefehler(`idempotencyKey muss ein Text mit 1 bis ${BELEG_SCHLUESSEL_MAX} Zeichen sein (oder weglassen); er wird nie gekuerzt.`);
+    }
+    return wert;
+}
 /** Die Lade eines Belegs: ein nicht leerer Text, sonst wirft der Aufruf vor dem Senden. */
 function ladeKennung(name, wert) {
     if (typeof wert !== 'string' || wert.trim() === '') {
@@ -1027,6 +1044,8 @@ function belegMitFirmaAusHuelle(daten, functionName) {
         registrationInfo: angaben,
         logoScale: d.logo_scale === 'S' || d.logo_scale === 'M' || d.logo_scale === 'L' || d.logo_scale === 'XL' ? d.logo_scale : 'M',
         ...(outputs !== undefined ? { outputs } : {}),
+        // Nur genau true: ohne Wiederholung bleibt die Form des Ergebnisses wie bisher.
+        ...(d.replayed === true ? { replayed: true } : {}),
     };
 }
 /**

package/dist/cjs/models/receipt-errors.d.ts

@@ -5,7 +5,9 @@ import { KasseneckApiError } from '../client/errors.js';
  * [PAYMENT_ERROR_CODES] und die des Rands (`validation`, `dialect_mismatch`, …).
  *
  * `receipt_outcome_unknown` heisst: der Beleg ist moeglicherweise signiert
- * (`outcome: 'unknown'`). Nie wiederholen, sondern die Belegliste nachlesen.
+ * (`outcome: 'unknown'`). Ohne `idempotencyKey` nie wiederholen, sondern die
+ * Belegliste nachlesen; mit Schluessel dieselbe Anfrage mit demselben
+ * Schluessel erneut senden.
  *
  * Dahinter (ab 1.0) die Codes, die Anmeldung und Rand auf diesem Endpunkt
  * erzeugen koennen: `errorCodes.auth` ohne die sieben des Partner-Zugangs und

package/dist/cjs/models/receipt-errors.js

@@ -12,7 +12,9 @@ const fehlercodes_js_1 = require("../client/fehlercodes.js");
  * [PAYMENT_ERROR_CODES] und die des Rands (`validation`, `dialect_mismatch`, …).
  *
  * `receipt_outcome_unknown` heisst: der Beleg ist moeglicherweise signiert
- * (`outcome: 'unknown'`). Nie wiederholen, sondern die Belegliste nachlesen.
+ * (`outcome: 'unknown'`). Ohne `idempotencyKey` nie wiederholen, sondern die
+ * Belegliste nachlesen; mit Schluessel dieselbe Anfrage mit demselben
+ * Schluessel erneut senden.
  *
  * Dahinter (ab 1.0) die Codes, die Anmeldung und Rand auf diesem Endpunkt
  * erzeugen koennen: `errorCodes.auth` ohne die sieben des Partner-Zugangs und
@@ -29,8 +31,8 @@ exports.RECEIPT_ERROR_CODES = Object.freeze([
     'cashregister_decommissioned',
     'final_receipt_expired',
     'final_receipt_not_allowed',
-    // Seit 1.15.0 (Vertrag): derselbe idempotencyKey mit anderem Inhalt, nichts geschrieben. Der Server nimmt den
-    // Schluessel optional an; dieses Paket sendet (noch) keinen, der Code bleibt damit nur lesbar.
+    // Seit 1.15.0 (Vertrag): derselbe idempotencyKey mit anderem Inhalt, nichts geschrieben. Seit 1.22.0 sendet
+    // dieses Paket den Schluessel, wenn der Aufrufer ihn angibt (`idempotencyKey` an sellReceipt/createReceipt).
     'idempotency_conflict',
     'module_inactive',
     'not_permitted',

package/dist/cjs/receipt/gutschein-plan.js

@@ -325,7 +325,12 @@ function planeGutscheine(kunde, vouchers, art, o) {
         if ('fehler' in check)
             return check;
         if (v.action === 'payout') {
-            // `gutschein-core.darfAuszahlen`: Auszahlung nicht gesperrt, aktiv oder abgelaufen bis zum Ende der Rueckzahlbarkeit.
+            // `gutschein-core.darfAuszahlen`: storniert und gesperrt zuerst (der Storno setzt den Saldo auf 0, die Kasse soll
+            // „storniert“ sagen, nicht „aufgebraucht“), dann Auszahlung nicht gesperrt, aktiv oder abgelaufen bis zum Ende der
+            // Rueckzahlbarkeit.
+            if (check.status === 'cancelled' || check.status === 'blocked') {
+                return nein(STATUS_FEHLER[check.status] ?? 'voucher_invalid', `Gutschein ${i + 1}: Status ${check.status}.`);
+            }
             if (check.payout === 'never')
                 return nein('voucher_payout_not_allowed', `Gutschein ${i + 1}: dieser Gutschein wird nie ausgezahlt.`);
             if (!((check.balanceCents ?? 0) > 0))

package/dist/cjs/version.d.ts

@@ -4,4 +4,4 @@
  * Client-Version, Nachtrag §6). Ein Test haelt sie gleich mit `package.json`;
  * beim Anheben der Version beide Stellen aendern.
  */
-export declare const PACKAGE_VERSION = "1.21.0";
+export declare const PACKAGE_VERSION = "1.22.0";

package/dist/cjs/version.js

@@ -7,4 +7,4 @@ exports.PACKAGE_VERSION = void 0;
  * Client-Version, Nachtrag §6). Ein Test haelt sie gleich mit `package.json`;
  * beim Anheben der Version beide Stellen aendern.
  */
-exports.PACKAGE_VERSION = '1.21.0';
+exports.PACKAGE_VERSION = '1.22.0';

package/dist/esm/client/receipts.d.ts

@@ -26,7 +26,10 @@ import type { SheetLogoSize } from '../receipt/blatt.js';
  * (`receipt_outcome_unknown`, `cancellation_outcome_unknown`, Netz- oder
  * Serverfehler nach dem Senden) erst nachlesen, und bei
  * `payments_sum_mismatch` nennt [paymentsExpectedCents] den Betrag des
- * Servers; auch dann wiederholt das Paket nie selbst.
+ * Servers; auch dann wiederholt das Paket nie selbst. Ausnahme fuer den
+ * Aufrufer: ein Verkauf mit `idempotencyKey` darf nach einem unklaren Ausgang
+ * unveraendert mit **demselben** Schluessel erneut hinaus (siehe
+ * [ReceiptCommonOptions.idempotencyKey]).
  *
  * **Kassen-Benutzer-Weg (`registerUserAuth`, Browser-Kasse):** Von den
  * Endpunkten dieser Datei setzen [listMyReceipts], [getReceipt],
@@ -62,6 +65,27 @@ export interface ReceiptCommonOptions {
      * Hauptlade der Kasse. Leer oder kein Text: wirft vor dem Senden.
      */
     drawerId?: string;
+    /**
+     * Schutz vor einem zweiten Beleg, wenn die Antwort verloren geht (Netzabbruch,
+     * Zeitablauf, `outcome: 'unknown'`). Gilt je Kasse: dieselbe Anfrage mit
+     * demselben Schluessel liefert den schon signierten Beleg zurueck, ohne neuen
+     * Beleg, ohne Zaehlerschritt (beim `…WithCompany`-Aufruf mit `replayed: true`;
+     * Klartext-Codes neu verkaufter Gutscheine nur beim ersten Mal). Derselbe
+     * Schluessel mit anderem Inhalt wird mit `idempotency_conflict` abgewiesen,
+     * geschrieben wird dann nichts.
+     *
+     * Empfohlen ist eine eigene, stabile Kennung des Vorgangs (Bestellnummer,
+     * Nummer des Ersatzbelegs), nie eine je Versuch neu erzeugte: nach einem
+     * unklaren Ausgang geht dieselbe Anfrage mit **demselben** Schluessel erneut
+     * hinaus; ein neuer Schluessel waere ein zweiter Beleg. Bei der Nacherfassung
+     * ([manualReceipt]) sperrt der Server dieselbe Handbeleg-Nummer am selben Tag
+     * zusaetzlich mit `manual_receipt_duplicate`.
+     *
+     * Text mit 1 bis 120 Zeichen (Laenge wie `String.length`), geht unveraendert
+     * hinaus. Leer, nur Leerraum, laenger oder kein Text: wirft vor dem Senden,
+     * nie gekuerzt. Ohne Angabe (oder `null`) bleibt der Aufruf wie bisher.
+     */
+    idempotencyKey?: string;
 }
 /** Trinkgeld mit eigener Zahlart und/oder Empfaengern (Kassen-Benutzer-IDs, Summe = cents). */
 export interface TipOptions {
@@ -231,6 +255,12 @@ export interface ReceiptWithCompany {
      * faellt weg, der Beleg bleibt lesbar.
      */
     outputs?: ReceiptOutput[];
+    /**
+     * Nur nach einem Verkauf mit `idempotencyKey`: `true`, wenn der Server den
+     * schon signierten Beleg zu diesem Schluessel zurueckgab (Wiederholung, kein
+     * neuer Beleg). Fehlt sonst, auch beim ersten Verkauf mit Schluessel.
+     */
+    replayed?: true;
 }
 /**
  * Das Zeilenmodell zum Drucken und Anzeigen eines Belegs aus einer Antwort.

package/dist/esm/client/receipts.js

@@ -188,8 +188,25 @@ export function createReceiptParams(options) {
     if (options.drawerId !== undefined) {
         params['drawerId'] = ladeKennung('createReceipt', options.drawerId);
     }
+    if (options.idempotencyKey != null) {
+        params['idempotencyKey'] = belegSchluessel(options.idempotencyKey);
+    }
     return params;
 }
+/** Hoechstlaenge des `idempotencyKey` am Beleg, wie am Server (beleg-idempotenz-core `SCHLUESSEL_MAX`). */
+const BELEG_SCHLUESSEL_MAX = 120;
+/**
+ * Der Idempotenz-Schluessel eines Belegs: dieselbe Regel wie am Server (Text,
+ * nicht nur Leerraum, hoechstens 120 Zeichen). Er geht unveraendert hinaus:
+ * der Server erkennt die Wiederholung am Schluessel, wie er ankommt, ein
+ * gekuerzter oder getrimmter waere ein anderer.
+ */
+function belegSchluessel(wert) {
+    if (typeof wert !== 'string' || wert.trim() === '' || wert.length > BELEG_SCHLUESSEL_MAX) {
+        throw eingabefehler(`idempotencyKey muss ein Text mit 1 bis ${BELEG_SCHLUESSEL_MAX} Zeichen sein (oder weglassen); er wird nie gekuerzt.`);
+    }
+    return wert;
+}
 /** Die Lade eines Belegs: ein nicht leerer Text, sonst wirft der Aufruf vor dem Senden. */
 function ladeKennung(name, wert) {
     if (typeof wert !== 'string' || wert.trim() === '') {
@@ -1006,6 +1023,8 @@ export function belegMitFirmaAusHuelle(daten, functionName) {
         registrationInfo: angaben,
         logoScale: d.logo_scale === 'S' || d.logo_scale === 'M' || d.logo_scale === 'L' || d.logo_scale === 'XL' ? d.logo_scale : 'M',
         ...(outputs !== undefined ? { outputs } : {}),
+        // Nur genau true: ohne Wiederholung bleibt die Form des Ergebnisses wie bisher.
+        ...(d.replayed === true ? { replayed: true } : {}),
     };
 }
 /**

package/dist/esm/models/receipt-errors.d.ts

@@ -5,7 +5,9 @@ import { KasseneckApiError } from '../client/errors.js';
  * [PAYMENT_ERROR_CODES] und die des Rands (`validation`, `dialect_mismatch`, …).
  *
  * `receipt_outcome_unknown` heisst: der Beleg ist moeglicherweise signiert
- * (`outcome: 'unknown'`). Nie wiederholen, sondern die Belegliste nachlesen.
+ * (`outcome: 'unknown'`). Ohne `idempotencyKey` nie wiederholen, sondern die
+ * Belegliste nachlesen; mit Schluessel dieselbe Anfrage mit demselben
+ * Schluessel erneut senden.
  *
  * Dahinter (ab 1.0) die Codes, die Anmeldung und Rand auf diesem Endpunkt
  * erzeugen koennen: `errorCodes.auth` ohne die sieben des Partner-Zugangs und

package/dist/esm/models/receipt-errors.js

@@ -5,7 +5,9 @@ import { bekannterCode, feldfehlerVon } from '../client/fehlercodes.js';
  * [PAYMENT_ERROR_CODES] und die des Rands (`validation`, `dialect_mismatch`, …).
  *
  * `receipt_outcome_unknown` heisst: der Beleg ist moeglicherweise signiert
- * (`outcome: 'unknown'`). Nie wiederholen, sondern die Belegliste nachlesen.
+ * (`outcome: 'unknown'`). Ohne `idempotencyKey` nie wiederholen, sondern die
+ * Belegliste nachlesen; mit Schluessel dieselbe Anfrage mit demselben
+ * Schluessel erneut senden.
  *
  * Dahinter (ab 1.0) die Codes, die Anmeldung und Rand auf diesem Endpunkt
  * erzeugen koennen: `errorCodes.auth` ohne die sieben des Partner-Zugangs und
@@ -22,8 +24,8 @@ export const RECEIPT_ERROR_CODES = Object.freeze([
     'cashregister_decommissioned',
     'final_receipt_expired',
     'final_receipt_not_allowed',
-    // Seit 1.15.0 (Vertrag): derselbe idempotencyKey mit anderem Inhalt, nichts geschrieben. Der Server nimmt den
-    // Schluessel optional an; dieses Paket sendet (noch) keinen, der Code bleibt damit nur lesbar.
+    // Seit 1.15.0 (Vertrag): derselbe idempotencyKey mit anderem Inhalt, nichts geschrieben. Seit 1.22.0 sendet
+    // dieses Paket den Schluessel, wenn der Aufrufer ihn angibt (`idempotencyKey` an sellReceipt/createReceipt).
     'idempotency_conflict',
     'module_inactive',
     'not_permitted',

package/dist/esm/receipt/gutschein-plan.js

@@ -316,7 +316,12 @@ export function planeGutscheine(kunde, vouchers, art, o) {
         if ('fehler' in check)
             return check;
         if (v.action === 'payout') {
-            // `gutschein-core.darfAuszahlen`: Auszahlung nicht gesperrt, aktiv oder abgelaufen bis zum Ende der Rueckzahlbarkeit.
+            // `gutschein-core.darfAuszahlen`: storniert und gesperrt zuerst (der Storno setzt den Saldo auf 0, die Kasse soll
+            // „storniert“ sagen, nicht „aufgebraucht“), dann Auszahlung nicht gesperrt, aktiv oder abgelaufen bis zum Ende der
+            // Rueckzahlbarkeit.
+            if (check.status === 'cancelled' || check.status === 'blocked') {
+                return nein(STATUS_FEHLER[check.status] ?? 'voucher_invalid', `Gutschein ${i + 1}: Status ${check.status}.`);
+            }
             if (check.payout === 'never')
                 return nein('voucher_payout_not_allowed', `Gutschein ${i + 1}: dieser Gutschein wird nie ausgezahlt.`);
             if (!((check.balanceCents ?? 0) > 0))

package/dist/esm/version.d.ts

@@ -4,4 +4,4 @@
  * Client-Version, Nachtrag §6). Ein Test haelt sie gleich mit `package.json`;
  * beim Anheben der Version beide Stellen aendern.
  */
-export declare const PACKAGE_VERSION = "1.21.0";
+export declare const PACKAGE_VERSION = "1.22.0";

package/dist/esm/version.js

@@ -4,4 +4,4 @@
  * Client-Version, Nachtrag §6). Ein Test haelt sie gleich mit `package.json`;
  * beim Anheben der Version beide Stellen aendern.
  */
-export const PACKAGE_VERSION = '1.21.0';
+export const PACKAGE_VERSION = '1.22.0';

package/fixtures/hobex-hps-codes.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.21.0",
+  "version": "1.22.0",
   "measuredOn": {
     "tid": "3600335",
     "hpsVersion": "1.10.0",

package/fixtures/invoice-api.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "Kasseneck Rechnungs-API",
   "version": 2,
-  "package": "1.21.0",
+  "package": "1.22.0",
   "endpoints": {
     "createCustomer": {
       "request": {

package/fixtures/invoice-texts.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.21.0",
+  "version": "1.22.0",
   "languages": [
     "de",
     "en"

package/fixtures/pos-texts.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.21.0",
+  "version": "1.22.0",
   "messages": {
     "network.no_connection": {
       "text": "Keine Verbindung zum Server. Bitte die Internetverbindung prüfen und erneut versuchen."

package/fixtures/receipt-due-voucher-generated.json

@@ -3,7 +3,7 @@
   "_source": {
     "beleg-toepfe.js": "60630493a589469d1cdfeea6fef667d20feb8f3a156819ba4d90b21501fdc4ea",
     "gutschein-beleg.js": "36750aa4eec8d94f57c2eebce0d34d13c7ffb3f0f5ea558fac1f56f15ff50004",
-    "gutschein-core.js": "8eeb04a12f771c6b70b23ab7a361354745182ab18235213d3c2f1f9191ebadef",
+    "gutschein-core.js": "b4d3188c666a43e3be8cc1c2c54e5b8de24e10db785e33bb2ce81aa38ae47929",
     "tip-core.js": "2d5b65c3cbe96935c8537d35f02b30906a7477afa340e18325b60bd60af1c7d9",
     "vat-buckets.js": "92c69632c0120dbb09a22cef5a36b052e81605d99907eeda7289b0d3db78454c",
     "zahlungen-core.js": "7ea8b07dfd222741049a47bec0149953d5696b0e1e089bf9919d4bd2cafff530"
@@ -491,6 +491,10 @@
     {"name":"gen_voucher_478_single_purpose_exempt","input":{"receiptType":"standard","items":[{"name":"P","quantity":1,"priceCents":2521,"vatRate":4.9,"articleId":"item_mani"},{"name":"P","quantity":2.75,"priceCents":2266,"vatRate":13},{"name":"P","quantity":2,"priceCents":64,"vatRate":10,"articleId":"item_mani"},{"name":"Discount","quantity":1,"priceCents":-146,"vatRate":13,"kind":"discount"}],"vouchers":[{"type":"single_purpose","action":"redeem","code":"DTD5-9ECF-5KNZ","amountCents":58}],"today":"2026-10-19","voucherInfo":[{"code":"DTD5-9ECF-5KNZ","check":{"type":"single_purpose","status":"active","codeSuffix":"5KNZ","balanceCents":2402,"vatRateBp":0,"exempt":true}}]},"expected":{"dueCents":8677,"counterDeltaCents":8677,"valueVoucherFlowCents":0,"bucketsCents":{"amountRateStandard":0,"amountRateReduced1":127,"amountRateReduced2":6046,"amountRateZero":0,"amountRateSpecial":2504,"amountRatOthers":0}}},
     {"name":"gen_voucher_479_sell_multi_purpose","input":{"receiptType":"standard","items":[{"name":"P","quantity":3,"priceCents":80,"vatRate":4.9}],"vouchers":[{"action":"sell","type":"multi_purpose","typeId":"vt_mehrzweck_479","amountCents":7217}],"today":"2100-01-04","voucherTypes":[{"id":"vt_mehrzweck_479","kind":"multi_purpose","vatRateBp":null,"amount":{"mode":"fixed","cents":7217}}],"smallBusiness":true},"expected":{"dueCents":7457,"counterDeltaCents":7457,"valueVoucherFlowCents":0,"bucketsCents":{"amountRateStandard":0,"amountRateReduced1":0,"amountRateReduced2":0,"amountRateZero":7217,"amountRateSpecial":240,"amountRatOthers":0}}},
     {"name":"gen_voucher_480_redeem_wrong_kind","input":{"receiptType":"standard","items":[{"name":"P","quantity":1,"priceCents":2000,"vatRate":20}],"vouchers":[{"type":"single_purpose","action":"redeem","code":"DTD5-9ECF-5KNZ","amountCents":1000}],"today":"2026-10-19","voucherInfo":[{"code":"DTD5-9ECF-5KNZ","check":{"type":"multi_purpose","status":"active","codeSuffix":"5KNZ","balanceCents":5000}}]},"expected":{"voucherError":"voucher_invalid"}},
-    {"name":"gen_voucher_481_redeem_wrong_kind","input":{"receiptType":"standard","items":[{"name":"P","quantity":1,"priceCents":2000,"vatRate":20}],"vouchers":[{"type":"multi_purpose","action":"redeem","code":"DTD5-9ECF-5KNZ","amountCents":1000}],"today":"2026-10-19","voucherInfo":[{"code":"DTD5-9ECF-5KNZ","check":{"type":"single_purpose","status":"active","codeSuffix":"5KNZ","balanceCents":5000,"vatRateBp":2000}}]},"expected":{"voucherError":"voucher_invalid"}}
+    {"name":"gen_voucher_481_redeem_wrong_kind","input":{"receiptType":"standard","items":[{"name":"P","quantity":1,"priceCents":2000,"vatRate":20}],"vouchers":[{"type":"multi_purpose","action":"redeem","code":"DTD5-9ECF-5KNZ","amountCents":1000}],"today":"2026-10-19","voucherInfo":[{"code":"DTD5-9ECF-5KNZ","check":{"type":"single_purpose","status":"active","codeSuffix":"5KNZ","balanceCents":5000,"vatRateBp":2000}}]},"expected":{"voucherError":"voucher_invalid"}},
+    {"name":"gen_voucher_482_payout_multi_purpose_cancelled","input":{"receiptType":"standard","items":[],"vouchers":[{"type":"multi_purpose","action":"payout","code":"DTD5-9ECF-5KNZ","amountCents":1000,"reason":"Goodwill"}],"today":"2026-10-19","voucherInfo":[{"code":"DTD5-9ECF-5KNZ","check":{"type":"multi_purpose","status":"cancelled","codeSuffix":"5KNZ","balanceCents":0}}]},"expected":{"voucherError":"voucher_cancelled"}},
+    {"name":"gen_voucher_483_payout_single_purpose_cancelled","input":{"receiptType":"standard","items":[],"vouchers":[{"type":"single_purpose","action":"payout","code":"DTD5-9ECF-5KNZ","amountCents":1000,"reason":"Goodwill"}],"today":"2026-10-19","voucherInfo":[{"code":"DTD5-9ECF-5KNZ","check":{"type":"single_purpose","status":"cancelled","codeSuffix":"5KNZ","payout":"never","balanceCents":0,"vatRateBp":2000}}]},"expected":{"voucherError":"voucher_cancelled"}},
+    {"name":"gen_voucher_484_payout_multi_purpose_blocked","input":{"receiptType":"standard","items":[],"vouchers":[{"type":"multi_purpose","action":"payout","code":"DTD5-9ECF-5KNZ","amountCents":1000,"reason":"Goodwill"}],"today":"2026-10-19","voucherInfo":[{"code":"DTD5-9ECF-5KNZ","check":{"type":"multi_purpose","status":"blocked","codeSuffix":"5KNZ","payout":"never","balanceCents":5000}}]},"expected":{"voucherError":"voucher_blocked"}},
+    {"name":"gen_voucher_485_payout_multi_purpose_used_up","input":{"receiptType":"standard","items":[],"vouchers":[{"type":"multi_purpose","action":"payout","code":"DTD5-9ECF-5KNZ","amountCents":1000,"reason":"Goodwill"}],"today":"2026-10-19","voucherInfo":[{"code":"DTD5-9ECF-5KNZ","check":{"type":"multi_purpose","status":"used_up","codeSuffix":"5KNZ","balanceCents":0}}]},"expected":{"voucherError":"voucher_used_up"}}
   ]
 }

package/fixtures/surface.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.21.0",
+  "version": "1.22.0",
   "baseUrls": {
     "public": "https://api.kasseneck.at/v3",
     "pos": "https://kasse.kasseneck.at/api/v3"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kreiseck/kasseneck-api",
-  "version": "1.21.0",
+  "version": "1.22.0",
   "description": "Austrian fiscal cash register (RKSV) client for JavaScript and TypeScript: signed receipts, cancellations, card payments, receipt printing (ESC/POS), invoices, inventory. RKSV-Registrierkasse für JavaScript und TypeScript.",
   "license": "Apache-2.0",
   "author": "Kreiseck",