@kreiseck/kasseneck-api 1.11.1 → 1.12.0

package/dist/esm/client/receipts.js

@@ -1,5 +1,5 @@
 import { ReceiptType, KeckPaymentMethod, CreditCardProvider, VoucherAction, VoucherType, } from '../enums/index.js';
-import { fromReceiptCompanyPayload, fromReceiptPayload, toReceiptItemPayload, toVoucherPayload, receiptItemIsValid, voucherIsValid, fromReceiptSummaryPayload, isCancellationReason, isReturnDisposition, RETURN_DISPOSITIONS, isTipRefundSource, TIP_REFUND_SOURCES, RECEIPT_EMAIL_VIAS, readRegistrationInfo, } from '../models/index.js';
+import { fromReceiptCompanyPayload, fromReceiptPayload, toReceiptItemPayload, toVoucherPayload, receiptItemIsValid, voucherIsValid, isNewFormVoucher, voucherServerFields, fromReceiptSummaryPayload, isCancellationReason, isReturnDisposition, RETURN_DISPOSITIONS, isTipRefundSource, TIP_REFUND_SOURCES, RECEIPT_EMAIL_VIAS, readRegistrationInfo, } from '../models/index.js';
 import { parseServerTimeStamp, toViennaWallClock } from '../vienna-time.js';
 import { euroToCents } from '../money.js';
 import { KasseneckValidationError, isKasseneckApiError, signiertGelesen } from './errors.js';
@@ -50,7 +50,7 @@ async function createReceiptWithCompany(rufen, options) {
  * Baut die Nutzlast von `createReceipt` und prueft die Eingabe. Wirft, bevor
  * irgendetwas rausgeht — ein Beleg ist nicht folgenlos wiederholbar.
  */
-function createReceiptParams(options) {
+export function createReceiptParams(options) {
     const typ = belegtyp(options.receiptType);
     const { items, vouchers } = options;
     // Unter /v3 weist der Server diese Felder ab (payment_method_not_supported);
@@ -62,10 +62,15 @@ function createReceiptParams(options) {
     if (typ.value === ReceiptType.cancellation.value) {
         throw eingabefehler('Ein Storno geht nur ueber cancelReceipt (Bezug, Grund, Restmengen).');
     }
+    // Gutschein-Positionen setzt nur der Server; vor jeder anderen Positionspruefung.
+    if (items?.some((item) => item.kind === 'voucher' || item.kind === 'voucher_float') ?? false) {
+        throw eingabefehler('voucher_invalid: Gutschein-Positionen (kind voucher, voucher_float) setzt nur der Server.');
+    }
     if (typ.needsItems) {
         // Ein reiner Gutscheinverkauf ist ein Umsatz ohne Positionen, deshalb
         // zaehlt er hier wie eine Position (wie im Flutter-Vorbild).
-        const hatVerkaufsgutschein = vouchers?.some((v) => v.action === VoucherAction.sell) ?? false;
+        // (Eine Auszahlung der neuen Form braucht ebenfalls keine Positionen.)
+        const hatVerkaufsgutschein = vouchers?.some((v) => v.action === VoucherAction.sell || v.action === VoucherAction.payout) ?? false;
         if ((items == null || items.length === 0) && !hatVerkaufsgutschein) {
             throw eingabefehler(`Positionen sind Pflicht bei receiptType "${typ.value}" und duerfen nicht leer sein.`);
         }
@@ -78,6 +83,13 @@ function createReceiptParams(options) {
         if (!typ.allowsVouchers) {
             throw eingabefehler(`Gutscheine sind nicht erlaubt bei receiptType "${typ.value}".`);
         }
+        const serverfeld = vouchers.flatMap(voucherServerFields)[0];
+        if (serverfeld != null) {
+            throw eingabefehler(`voucher_invalid: Das Feld ${serverfeld} setzt nur der Server.`);
+        }
+        if (typ.value === ReceiptType.training.value && vouchers.some(isNewFormVoucher)) {
+            throw eingabefehler('Gutscheine der neuen Form gibt es nicht auf Schulungsbelegen (receiptType training).');
+        }
         if (vouchers.some((voucher) => !voucherIsValid(voucher))) {
             throw eingabefehler('Ungueltiger Gutschein uebergeben.');
         }
@@ -90,6 +102,11 @@ function createReceiptParams(options) {
     if (items != null && items.length > 0) {
         params['items'] = alsNutzlast(items, toReceiptItemPayload);
     }
+    else if (items != null && (vouchers?.some(isNewFormVoucher) ?? false)) {
+        // Verkauf/Auszahlung der neuen Form ohne Positionen: die leere Liste geht
+        // mit, wie der Vertrag es zeigt (Altform ohne Positionen bleibt byte-gleich).
+        params['items'] = [];
+    }
     const umsatz = typ.value === ReceiptType.standard.value || typ.value === ReceiptType.training.value;
     if (umsatz) {
         // Pflicht unter /v3 (payments_required); eine leere Liste ist erlaubt,
@@ -97,7 +114,12 @@ function createReceiptParams(options) {
         if (options.payments == null) {
             throw eingabefehler('payments fehlt: unter /v3 ist die Zahlungsliste Pflicht (Summe = receiptDueCents).');
         }
-        params['payments'] = gepruefteZahlungen(options.payments, false, 'createReceipt');
+        // Beleg nur aus Gutschein-Auszahlungen (Server gutschein-beleg.istNurAuszahlung):
+        // genau eine Barzahlung ueber den negativen Zahlbetrag.
+        // Wie der Server erst nach dem Anhaengen des Trinkgelds: eine Trinkgeldzeile ist keine Gutscheinzeile.
+        const nurAuszahlung = (vouchers?.length ?? 0) > 0 && vouchers.every((v) => v.action === VoucherAction.payout)
+            && (items?.length ?? 0) === 0 && options.tip == null;
+        params['payments'] = gepruefteZahlungen(options.payments, false, 'createReceipt', nurAuszahlung);
     }
     else if (options.payments != null) {
         throw eingabefehler(`payments sind bei receiptType "${typ.value}" nicht erlaubt.`);
@@ -453,6 +475,26 @@ export function checkVoucherCombinationError(vouchers, items) {
             verkaufenPromo++;
         }
     }
+    // Neue Form, Regeln wie gutschein-beleg.plane des Servers:
+    // - Verkauf und Einloesung nie zusammen, sobald einer davon die neue Form
+    //   hat (auch gegen die Altform); eine Auszahlung zaehlt hier nicht.
+    // - der Aktionsgutschein (promotion) steht allein.
+    // - eine Auszahlung nie mit einem Altform-Rabatt (promo).
+    // Die Altform-Zaehler unten zaehlen die neue Form bewusst nicht mit.
+    const neu = vouchers.filter((v) => isNewFormVoucher(v));
+    const verkaufEinloesung = vouchers.filter((v) => v.action === VoucherAction.sell || v.action === VoucherAction.redeem);
+    if (verkaufEinloesung.some((v) => v.action === VoucherAction.sell)
+        && verkaufEinloesung.some((v) => v.action === VoucherAction.redeem)
+        && verkaufEinloesung.some((v) => isNewFormVoucher(v))) {
+        return 'Ungueltige Daten: Ein Beleg kann Gutscheine der neuen Form nicht zugleich verkaufen und einloesen';
+    }
+    if (neu.some((v) => v.type === VoucherType.promotion) && vouchers.length > 1) {
+        return 'Ungueltige Daten: Ein Aktionsgutschein (type promotion) darf nicht mit anderen Gutscheinen kombiniert werden';
+    }
+    if (neu.some((v) => v.action === VoucherAction.payout) && vouchers.some((v) => !isNewFormVoucher(v) && v.type === VoucherType.promo)) {
+        return 'Ungueltige Daten: Eine Auszahlung (action payout) darf nicht mit einem Gutschein mit type promo kombiniert werden';
+    }
+    const einloesenNeu = neu.filter((v) => v.action === VoucherAction.redeem).length;
     const einloesenGesamt = einloesenWert + einloesenPromo;
     const verkaufenGesamt = verkaufenWert + verkaufenPromo;
     if (verkaufenPromo > 0) {
@@ -467,7 +509,7 @@ export function checkVoucherCombinationError(vouchers, items) {
     if (einloesenPromo > 0 && verkaufenGesamt > 0) {
         return 'Ungueltige Daten: Mit einem Gutschein mit type promo duerfen nicht andere Gutscheine verkauft werden';
     }
-    if (einloesenGesamt > 0 && items.length === 0) {
+    if ((einloesenGesamt > 0 || einloesenNeu > 0) && items.length === 0) {
         return 'Ungueltige Daten: Gutscheine mit action redeem benoetigen mindestens ein item';
     }
     return null;
@@ -601,12 +643,28 @@ const MAX_ZAHLUNGEN = 20;
  * (Summe, Anbieter-Pflicht und Trinkgeld prueft der Server). Wirft, bevor
  * etwas hinausgeht.
  */
-function gepruefteZahlungen(roh, storno, functionName) {
+function gepruefteZahlungen(roh, storno, functionName, auszahlung = false) {
     const fehler = (grund) => new KasseneckValidationError(functionName, grund, 'request');
     if (!Array.isArray(roh))
         throw fehler('payments muss eine Liste sein.');
     if (roh.length > MAX_ZAHLUNGEN)
         throw fehler(`payments: es sind hoechstens ${MAX_ZAHLUNGEN} Eintraege erlaubt.`);
+    // Auszahlung eines Gutscheins: der Betrag geht bar hinaus, ohne gegeben und ohne Trinkgeld (Server pruefeZahlungen).
+    const negativ = storno || auszahlung;
+    if (auszahlung) {
+        const e = roh[0];
+        if (roh.length !== 1)
+            throw fehler('Auszahlung: genau eine Barzahlung angeben.');
+        if (e != null && typeof e === 'object') {
+            const m = e['method'];
+            if ((typeof m === 'object' && m !== null ? m.value : m) !== 'cash')
+                throw fehler('Auszahlung: nur in bar moeglich.');
+            if (e['tenderedCents'] !== undefined)
+                throw fehler('Auszahlung: tenderedCents ist nicht moeglich.');
+            if (e['tipCents'] !== undefined)
+                throw fehler('Auszahlung: tipCents ist nicht moeglich.');
+        }
+    }
     return roh.map((eintrag, i) => {
         const nr = i + 1;
         if (eintrag == null || typeof eintrag !== 'object' || Array.isArray(eintrag)) {
@@ -615,8 +673,8 @@ function gepruefteZahlungen(roh, storno, functionName) {
         const z = eintrag;
         const method = gepruefteZahlungsart(z['method']);
         const betrag = z['amountCents'];
-        if (typeof betrag !== 'number' || !Number.isInteger(betrag) || (storno ? betrag >= 0 : betrag <= 0)) {
-            throw fehler(`Zahlung ${nr}: amountCents muss eine ganze Zahl ${storno ? 'kleiner' : 'groesser'} als 0 sein.`);
+        if (typeof betrag !== 'number' || !Number.isInteger(betrag) || (negativ ? betrag >= 0 : betrag <= 0)) {
+            throw fehler(`Zahlung ${nr}: amountCents muss eine ganze Zahl ${negativ ? 'kleiner' : 'groesser'} als 0 sein.`);
         }
         const aus = { method, amountCents: betrag };
         if (z['tenderedCents'] !== undefined) {

package/dist/esm/enums/voucher-action.d.ts

@@ -5,6 +5,8 @@
 export declare const VoucherAction: {
     readonly sell: "sell";
     readonly redeem: "redeem";
+    /** Neue Form: Restwert auszahlen (Mehrzweck/Einzweck). */
+    readonly payout: "payout";
 };
 export type VoucherActionKey = keyof typeof VoucherAction;
 export type VoucherAction = (typeof VoucherAction)[VoucherActionKey];

package/dist/esm/enums/voucher-action.js

@@ -5,4 +5,6 @@
 export const VoucherAction = {
     sell: 'sell',
     redeem: 'redeem',
+    /** Neue Form: Restwert auszahlen (Mehrzweck/Einzweck). */
+    payout: 'payout',
 };

package/dist/esm/enums/voucher-type.d.ts

@@ -2,8 +2,18 @@
  * Gutscheinart — Zwilling von `VoucherType` in kasseneck_api/lib/enums/voucher_type.dart.
  */
 export declare const VoucherType: {
+    /** Altform: Wertgutschein (Wert im Cent, Code frei). */
     readonly value: "value";
+    /** Altform: Rabatt-/Promotionsgutschein. */
     readonly promo: "promo";
+    /** Neue Form: Mehrzweckgutschein (Zahlungsmittel, Steuer erst bei der Einloesung). */
+    readonly multi_purpose: "multi_purpose";
+    /** Neue Form: Einzweckgutschein (Steuer schon beim Verkauf, ein Satz). */
+    readonly single_purpose: "single_purpose";
+    /** Neue Form: Leistungsgutschein (Artikel mal Menge). */
+    readonly service: "service";
+    /** Neue Form: Aktionsgutschein (Rabatt laut Aktion, nur einloesbar). */
+    readonly promotion: "promotion";
 };
 export type VoucherTypeKey = keyof typeof VoucherType;
 export type VoucherType = (typeof VoucherType)[VoucherTypeKey];

package/dist/esm/enums/voucher-type.js

@@ -2,6 +2,16 @@
  * Gutscheinart — Zwilling von `VoucherType` in kasseneck_api/lib/enums/voucher_type.dart.
  */
 export const VoucherType = {
+    /** Altform: Wertgutschein (Wert im Cent, Code frei). */
     value: 'value',
+    /** Altform: Rabatt-/Promotionsgutschein. */
     promo: 'promo',
+    /** Neue Form: Mehrzweckgutschein (Zahlungsmittel, Steuer erst bei der Einloesung). */
+    multi_purpose: 'multi_purpose',
+    /** Neue Form: Einzweckgutschein (Steuer schon beim Verkauf, ein Satz). */
+    single_purpose: 'single_purpose',
+    /** Neue Form: Leistungsgutschein (Artikel mal Menge). */
+    service: 'service',
+    /** Neue Form: Aktionsgutschein (Rabatt laut Aktion, nur einloesbar). */
+    promotion: 'promotion',
 };

package/dist/esm/index.d.ts

@@ -1,6 +1,6 @@
 export { ReceiptType, type ReceiptTypeKey, VatRate, type VatRateKey, KeckPaymentMethod, type KeckPaymentMethodKey, CreditCardProvider, type CreditCardProviderKey, VoucherType, type VoucherTypeKey, VoucherAction, type VoucherActionKey, StripeLinkMode, type StripeLinkModeKey, } from './enums/index.js';
-export { type ReceiptItem, type ReceiptItemPayload, type ReceiptItemPayloadRead, toReceiptItemPayload, fromReceiptItemPayload, receiptItemTotalCents, receiptItemIsValid, negateReceiptItem, type TipRecipient, isTipItem, type Voucher, type VoucherPayload, toVoucherPayload, fromVoucherPayload, voucherIsValid, type Receipt, type RegistrationInfo, type ReceiptPayload, type ReceiptPayloadRead, toReceiptPayload, fromReceiptPayload, receiptSubSumCents, receiptSumCents, receiptValueVoucherSign, type CancellationOf, type CancellationItem, type Cancellation, type CancellationReason, type CancellationErrorCode, type CancellationStatus, type ReturnDisposition, RETURN_DISPOSITIONS, CANCELLATION_REASONS, CANCELLATION_STATUSES, CANCELLATION_ERROR_CODES, CANCELLATION_RESERVATION_MS, isCancellationReason, isReturnDisposition, isCancellationErrorCode, cancellationErrorCode, isCancellationError, cancellationFieldErrors, type CancellationFieldError, type ReceiptPayment, type ReceiptPaymentPayload, type ReceiptPaymentInput, fromReceiptPaymentPayload, toReceiptPaymentPayload, type PaymentErrorCode, PAYMENT_ERROR_CODES, isPaymentErrorCode, paymentErrorCode, isPaymentError, paymentFieldErrors, type PaymentFieldError, type ReceiptEmailErrorCode, type ReceiptEmailVia, RECEIPT_EMAIL_ERROR_CODES, RECEIPT_EMAIL_SEND_ERROR_CODES, type ReceiptEmailSendErrorCode, RECEIPT_EMAIL_VIAS, isReceiptEmailErrorCode, receiptEmailErrorCode, isReceiptEmailError, receiptEmailFieldErrors, type ReceiptEmailFieldError, type ReceiptErrorCode, type ReceiptFieldError, RECEIPT_ERROR_CODES, isReceiptErrorCode, receiptErrorCode, isReceiptError, receiptFieldErrors, remainingQuantities, TIP_REFUND_SOURCES, type TipRefundSource, isTipRefundSource, openStaffTipCents, cancellationItemsForTip, cancellationCashRefundCents, asksTipRefundSource, asksRefundTip, type ReceiptCompany, type ReceiptCompanyPayload, fromReceiptCompanyPayload, receiptCompanyTaxInfo, type Cashregister, type CashregisterOnboarding, type CashregisterPayload, type CashregisterOnboardingPayload, type CashregisterAutoLogout, type CashregisterAutoLogoutPayload, fromCashregisterPayload, type ReceiptSummary, type ReceiptSummaryPayload, fromReceiptSummaryPayload, type ZeroKind, ZERO_KINDS, isZeroKind, type ReportMonth, reportMonthFromDate, previousReportMonth, nextReportMonth, reportMonthKey, reportMonthReadable, type StripeUrlSession, type StripeUrlSessionPayload, toStripeUrlSessionPayload, fromStripeUrlSessionPayload, type HobexReceipt, type HobexReceiptPayload, toHobexReceiptPayload, fromHobexReceiptPayload, hobexReceiptToCardPaymentData, hobexReceiptNeedsSignature, } from './models/index.js';
+export { type ReceiptItem, type ReceiptItemPayload, type ReceiptItemPayloadRead, toReceiptItemPayload, fromReceiptItemPayload, receiptItemTotalCents, receiptItemIsValid, negateReceiptItem, type TipRecipient, isTipItem, isVoucherItem, isVoucherFloatItem, type Voucher, type VoucherArticle, type VoucherPayload, toVoucherPayload, fromVoucherPayload, voucherIsValid, type Receipt, type RegistrationInfo, type ReceiptPayload, type ReceiptPayloadRead, toReceiptPayload, fromReceiptPayload, receiptSubSumCents, receiptSumCents, receiptValueVoucherSign, type CancellationOf, type CancellationItem, type Cancellation, type CancellationReason, type CancellationErrorCode, type CancellationStatus, type ReturnDisposition, RETURN_DISPOSITIONS, CANCELLATION_REASONS, CANCELLATION_STATUSES, CANCELLATION_ERROR_CODES, CANCELLATION_RESERVATION_MS, isCancellationReason, isReturnDisposition, isCancellationErrorCode, cancellationErrorCode, isCancellationError, cancellationFieldErrors, type CancellationFieldError, type ReceiptPayment, type ReceiptPaymentPayload, type ReceiptPaymentInput, fromReceiptPaymentPayload, toReceiptPaymentPayload, type PaymentErrorCode, PAYMENT_ERROR_CODES, isPaymentErrorCode, paymentErrorCode, isPaymentError, paymentFieldErrors, type PaymentFieldError, type ReceiptEmailErrorCode, type ReceiptEmailVia, RECEIPT_EMAIL_ERROR_CODES, RECEIPT_EMAIL_SEND_ERROR_CODES, type ReceiptEmailSendErrorCode, RECEIPT_EMAIL_VIAS, isReceiptEmailErrorCode, receiptEmailErrorCode, isReceiptEmailError, receiptEmailFieldErrors, type ReceiptEmailFieldError, type ReceiptErrorCode, type ReceiptFieldError, RECEIPT_ERROR_CODES, isReceiptErrorCode, receiptErrorCode, isReceiptError, receiptFieldErrors, remainingQuantities, TIP_REFUND_SOURCES, type TipRefundSource, isTipRefundSource, openStaffTipCents, cancellationItemsForTip, cancellationCashRefundCents, asksTipRefundSource, asksRefundTip, type ReceiptCompany, type ReceiptCompanyPayload, fromReceiptCompanyPayload, receiptCompanyTaxInfo, type Cashregister, type CashregisterOnboarding, type CashregisterPayload, type CashregisterOnboardingPayload, type CashregisterAutoLogout, type CashregisterAutoLogoutPayload, fromCashregisterPayload, type ReceiptSummary, type ReceiptSummaryPayload, fromReceiptSummaryPayload, type ZeroKind, ZERO_KINDS, isZeroKind, type ReportMonth, reportMonthFromDate, previousReportMonth, nextReportMonth, reportMonthKey, reportMonthReadable, type StripeUrlSession, type StripeUrlSessionPayload, toStripeUrlSessionPayload, fromStripeUrlSessionPayload, type HobexReceipt, type HobexReceiptPayload, toHobexReceiptPayload, fromHobexReceiptPayload, hobexReceiptToCardPaymentData, hobexReceiptNeedsSignature, } from './models/index.js';
 export { type AuthCredentials, type KasseneckAuth, type ApiKeyAuthOptions, type RegisterUserAuthOptions, apiKeyAuth, registerUserAuth, DEFAULT_BASE_URL, POS_BASE_URL, DEFAULT_TIMEOUT_MS, type HttpResponseLike, type HttpRequestInit, type FetchLike, type TransportOptions, type TransportBodyFields, type TransportCallOptions, type KasseneckTransport, type KasseneckBinaryTransport, type KasseneckPdfOrDataTransport, type PdfOrData, ALL_CALLS, type ApiCall, PUBLIC_CALLS, POS_CALLS, UNKNOWN_OUTCOME_CALLS, type PublicCall, type PosCall, createTransport, createBinaryTransport, createPdfOrDataTransport, KasseneckApiError, KasseneckAuthError, KasseneckHttpError, KasseneckNetworkError, KasseneckValidationError, type ValidationScope, type KasseneckError, type HttpFailureReason, type CauseDigest, type ErrorOutcome, CLIENT_ERROR_CODES, type ClientErrorCode, isKasseneckApiError, isKasseneckAuthError, isKasseneckHttpError, isKasseneckNetworkError, isKasseneckValidationError, isOutcomeUnknown, type ReceiptCommonOptions, type SellReceiptOptions, type TipOptions, type TipRecipientShare, type CancelReceiptOptions, type CancelReceiptResult, type ReceiptWithCompany, sellReceipt, sellReceiptWithCompany, paymentsExpectedCents, cardRefundReference, receiptLayoutFromResult, cancelReceipt, zeroReceipt, getReceipt, getReceiptWithCompany, generateFullReceiptId, getFirstReceiptDate, listMyReceipts, type ListMyReceiptsOptions, type ReceiptList, type ReceiptListStats, listMyCashregisters, checkVoucherCombinationError, type SendReceiptEmailOptions, type SendReceiptEmailResult, sendReceiptEmail, downloadDailyReport, downloadMonthlyReport, getCashregisterReport, type CashregisterReportPeriod, getReportV2, type ReportV2, type ReportV2Metadata, type ReportV2Options, type CashboxStatus, type SignatureStatus, getCashboxStatus, getSignatureStatus, type KasseneckApi, createKasseneckApi, } from './client/index.js';
-export { type ReceiptDueTip, type ReceiptDueTipRecipient, type ReceiptDueOptions, type ReceiptDueBuckets, type ReceiptDueBreakdown, type ReceiptDueErrorReason, receiptDueCents, receiptDueBreakdown, ReceiptDueError, RECEIPT_DUE_ERROR_REASONS, isReceiptDueError, } from './receipt/due.js';
+export { type ReceiptDueTip, type ReceiptDueTipRecipient, type ReceiptDueOptions, type ReceiptDueBuckets, type ReceiptDueBreakdown, type ReceiptDueErrorReason, receiptDueCents, receiptDueBreakdown, ReceiptDueError, RECEIPT_DUE_ERROR_REASONS, isReceiptDueError, type VoucherDueInfo, type VoucherDueArticle, type VoucherRedeemContext, voucherRedeemMaxCents, VOUCHER_ZERO_RATE_BUCKET_FROM, } from './receipt/due.js';
 export { parseServerTimeStamp, toViennaWallClock, type ViennaWallClock } from './vienna-time.js';
-export { type PosBusinessSettings, type PosDeviceSettings, type PosSettings, type ArticleGroup, type PosArticle, POS_BUSINESS_DEFAULTS, POS_DEVICE_DEFAULTS, mergePosSettings, fromArticleGroupPayload, fromPosArticlePayload, listMyArticleGroups, listMyArticles, getPosSettings, setMyPosSettings, setMyRegisterDeviceSettings, distributeDiscount, cancelScopeOf, receiptsScopeOf, stockViewOf, } from './pos/index.js';
+export { type PosBusinessSettings, type PosDeviceSettings, type PosSettings, type ArticleGroup, type PosArticle, POS_BUSINESS_DEFAULTS, POS_DEVICE_DEFAULTS, mergePosSettings, fromArticleGroupPayload, fromPosArticlePayload, listMyArticleGroups, listMyArticles, getPosSettings, setMyPosSettings, setMyRegisterDeviceSettings, distributeDiscount, cancelScopeOf, receiptsScopeOf, stockViewOf, voucherPermsOf, } from './pos/index.js';

package/dist/esm/index.js

@@ -1,6 +1,6 @@
 export { ReceiptType, VatRate, KeckPaymentMethod, CreditCardProvider, VoucherType, VoucherAction, StripeLinkMode, } from './enums/index.js';
-export { toReceiptItemPayload, fromReceiptItemPayload, receiptItemTotalCents, receiptItemIsValid, negateReceiptItem, isTipItem, toVoucherPayload, fromVoucherPayload, voucherIsValid, toReceiptPayload, fromReceiptPayload, receiptSubSumCents, receiptSumCents, receiptValueVoucherSign, RETURN_DISPOSITIONS, CANCELLATION_REASONS, CANCELLATION_STATUSES, CANCELLATION_ERROR_CODES, CANCELLATION_RESERVATION_MS, isCancellationReason, isReturnDisposition, isCancellationErrorCode, cancellationErrorCode, isCancellationError, cancellationFieldErrors, fromReceiptPaymentPayload, toReceiptPaymentPayload, PAYMENT_ERROR_CODES, isPaymentErrorCode, paymentErrorCode, isPaymentError, paymentFieldErrors, RECEIPT_EMAIL_ERROR_CODES, RECEIPT_EMAIL_SEND_ERROR_CODES, RECEIPT_EMAIL_VIAS, isReceiptEmailErrorCode, receiptEmailErrorCode, isReceiptEmailError, receiptEmailFieldErrors, RECEIPT_ERROR_CODES, isReceiptErrorCode, receiptErrorCode, isReceiptError, receiptFieldErrors, remainingQuantities, TIP_REFUND_SOURCES, isTipRefundSource, openStaffTipCents, cancellationItemsForTip, cancellationCashRefundCents, asksTipRefundSource, asksRefundTip, fromReceiptCompanyPayload, receiptCompanyTaxInfo, fromCashregisterPayload, fromReceiptSummaryPayload, ZERO_KINDS, isZeroKind, reportMonthFromDate, previousReportMonth, nextReportMonth, reportMonthKey, reportMonthReadable, toStripeUrlSessionPayload, fromStripeUrlSessionPayload, toHobexReceiptPayload, fromHobexReceiptPayload, hobexReceiptToCardPaymentData, hobexReceiptNeedsSignature, } from './models/index.js';
+export { toReceiptItemPayload, fromReceiptItemPayload, receiptItemTotalCents, receiptItemIsValid, negateReceiptItem, isTipItem, isVoucherItem, isVoucherFloatItem, toVoucherPayload, fromVoucherPayload, voucherIsValid, toReceiptPayload, fromReceiptPayload, receiptSubSumCents, receiptSumCents, receiptValueVoucherSign, RETURN_DISPOSITIONS, CANCELLATION_REASONS, CANCELLATION_STATUSES, CANCELLATION_ERROR_CODES, CANCELLATION_RESERVATION_MS, isCancellationReason, isReturnDisposition, isCancellationErrorCode, cancellationErrorCode, isCancellationError, cancellationFieldErrors, fromReceiptPaymentPayload, toReceiptPaymentPayload, PAYMENT_ERROR_CODES, isPaymentErrorCode, paymentErrorCode, isPaymentError, paymentFieldErrors, RECEIPT_EMAIL_ERROR_CODES, RECEIPT_EMAIL_SEND_ERROR_CODES, RECEIPT_EMAIL_VIAS, isReceiptEmailErrorCode, receiptEmailErrorCode, isReceiptEmailError, receiptEmailFieldErrors, RECEIPT_ERROR_CODES, isReceiptErrorCode, receiptErrorCode, isReceiptError, receiptFieldErrors, remainingQuantities, TIP_REFUND_SOURCES, isTipRefundSource, openStaffTipCents, cancellationItemsForTip, cancellationCashRefundCents, asksTipRefundSource, asksRefundTip, fromReceiptCompanyPayload, receiptCompanyTaxInfo, fromCashregisterPayload, fromReceiptSummaryPayload, ZERO_KINDS, isZeroKind, reportMonthFromDate, previousReportMonth, nextReportMonth, reportMonthKey, reportMonthReadable, toStripeUrlSessionPayload, fromStripeUrlSessionPayload, toHobexReceiptPayload, fromHobexReceiptPayload, hobexReceiptToCardPaymentData, hobexReceiptNeedsSignature, } from './models/index.js';
 export { apiKeyAuth, registerUserAuth, DEFAULT_BASE_URL, POS_BASE_URL, DEFAULT_TIMEOUT_MS, ALL_CALLS, PUBLIC_CALLS, POS_CALLS, UNKNOWN_OUTCOME_CALLS, createTransport, createBinaryTransport, createPdfOrDataTransport, KasseneckApiError, KasseneckAuthError, KasseneckHttpError, KasseneckNetworkError, KasseneckValidationError, CLIENT_ERROR_CODES, isKasseneckApiError, isKasseneckAuthError, isKasseneckHttpError, isKasseneckNetworkError, isKasseneckValidationError, isOutcomeUnknown, sellReceipt, sellReceiptWithCompany, paymentsExpectedCents, cardRefundReference, receiptLayoutFromResult, cancelReceipt, zeroReceipt, getReceipt, getReceiptWithCompany, generateFullReceiptId, getFirstReceiptDate, listMyReceipts, listMyCashregisters, checkVoucherCombinationError, sendReceiptEmail, downloadDailyReport, downloadMonthlyReport, getCashregisterReport, getReportV2, getCashboxStatus, getSignatureStatus, createKasseneckApi, } from './client/index.js';
-export { receiptDueCents, receiptDueBreakdown, ReceiptDueError, RECEIPT_DUE_ERROR_REASONS, isReceiptDueError, } from './receipt/due.js';
+export { receiptDueCents, receiptDueBreakdown, ReceiptDueError, RECEIPT_DUE_ERROR_REASONS, isReceiptDueError, voucherRedeemMaxCents, VOUCHER_ZERO_RATE_BUCKET_FROM, } from './receipt/due.js';
 export { parseServerTimeStamp, toViennaWallClock } from './vienna-time.js';
-export { POS_BUSINESS_DEFAULTS, POS_DEVICE_DEFAULTS, mergePosSettings, fromArticleGroupPayload, fromPosArticlePayload, listMyArticleGroups, listMyArticles, getPosSettings, setMyPosSettings, setMyRegisterDeviceSettings, distributeDiscount, cancelScopeOf, receiptsScopeOf, stockViewOf, } from './pos/index.js';
+export { POS_BUSINESS_DEFAULTS, POS_DEVICE_DEFAULTS, mergePosSettings, fromArticleGroupPayload, fromPosArticlePayload, listMyArticleGroups, listMyArticles, getPosSettings, setMyPosSettings, setMyRegisterDeviceSettings, distributeDiscount, cancelScopeOf, receiptsScopeOf, stockViewOf, voucherPermsOf, } from './pos/index.js';

package/dist/esm/models/index.d.ts

@@ -1,5 +1,5 @@
-export { type ReceiptItem, type ReceiptItemPayload, type ReceiptItemPayloadRead, toReceiptItemPayload, fromReceiptItemPayload, receiptItemTotalCents, receiptItemIsValid, negateReceiptItem, type TipRecipient, isTipItem, isDiscountItem, } from './receipt-item.js';
-export { type Voucher, type VoucherPayload, toVoucherPayload, fromVoucherPayload, voucherIsValid } from './voucher.js';
+export { type ReceiptItem, type ReceiptItemPayload, type ReceiptItemPayloadRead, toReceiptItemPayload, fromReceiptItemPayload, receiptItemTotalCents, receiptItemIsValid, negateReceiptItem, type TipRecipient, isTipItem, isDiscountItem, isVoucherItem, isVoucherFloatItem, } from './receipt-item.js';
+export { type Voucher, type VoucherArticle, type VoucherPayload, toVoucherPayload, fromVoucherPayload, voucherIsValid, isNewFormVoucher, voucherServerFields } from './voucher.js';
 export { type Receipt, type RegistrationInfo, type ReceiptPayload, type ReceiptPayloadRead, toReceiptPayload, fromReceiptPayload, readRegistrationInfo, receiptSubSumCents, receiptSumCents, receiptValueVoucherSign, } from './receipt.js';
 export { type CancellationOf, type CancellationItem, type Cancellation, type CancellationReason, type CancellationErrorCode, type CancellationStatus, type ReturnDisposition, RETURN_DISPOSITIONS, CANCELLATION_REASONS, CANCELLATION_STATUSES, CANCELLATION_ERROR_CODES, CANCELLATION_RESERVATION_MS, isCancellationReason, isReturnDisposition, isCancellationErrorCode, cancellationErrorCode, isCancellationError, cancellationFieldErrors, type CancellationFieldError, remainingQuantities, TIP_REFUND_SOURCES, type TipRefundSource, isTipRefundSource, openStaffTipCents, cancellationItemsForTip, cancellationCashRefundCents, asksTipRefundSource, asksRefundTip, } from './cancellation.js';
 export { type ReceiptPayment, type ReceiptPaymentPayload, type ReceiptPaymentInput, fromReceiptPaymentPayload, toReceiptPaymentPayload, } from './receipt-payment.js';

package/dist/esm/models/index.js

@@ -1,5 +1,5 @@
-export { toReceiptItemPayload, fromReceiptItemPayload, receiptItemTotalCents, receiptItemIsValid, negateReceiptItem, isTipItem, isDiscountItem, } from './receipt-item.js';
-export { toVoucherPayload, fromVoucherPayload, voucherIsValid } from './voucher.js';
+export { toReceiptItemPayload, fromReceiptItemPayload, receiptItemTotalCents, receiptItemIsValid, negateReceiptItem, isTipItem, isDiscountItem, isVoucherItem, isVoucherFloatItem, } from './receipt-item.js';
+export { toVoucherPayload, fromVoucherPayload, voucherIsValid, isNewFormVoucher, voucherServerFields } from './voucher.js';
 export { toReceiptPayload, fromReceiptPayload, readRegistrationInfo, receiptSubSumCents, receiptSumCents, receiptValueVoucherSign, } from './receipt.js';
 export { RETURN_DISPOSITIONS, CANCELLATION_REASONS, CANCELLATION_STATUSES, CANCELLATION_ERROR_CODES, CANCELLATION_RESERVATION_MS, isCancellationReason, isReturnDisposition, isCancellationErrorCode, cancellationErrorCode, isCancellationError, cancellationFieldErrors, remainingQuantities, TIP_REFUND_SOURCES, isTipRefundSource, openStaffTipCents, cancellationItemsForTip, cancellationCashRefundCents, asksTipRefundSource, asksRefundTip, } from './cancellation.js';
 export { fromReceiptPaymentPayload, toReceiptPaymentPayload, } from './receipt-payment.js';

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

@@ -16,7 +16,7 @@ import { KasseneckApiError } from '../client/errors.js';
  * ...) stehen in [PAYMENT_ERROR_CODES]. Ein Code ausserhalb bleibt ueber
  * `KasseneckApiError.code` lesbar.
  */
-export declare const RECEIPT_ERROR_CODES: readonly ["cancellation_reference_unavailable", "cashregister_closed", "cashregister_decommissioned", "final_receipt_expired", "final_receipt_not_allowed", "module_inactive", "not_permitted", "receipt_limit_exceeded", "receipt_not_found", "receipt_outcome_unknown", "receipt_type_invalid", "signature_incomplete", "signature_missing", "signing_failed", "small_business_vat_not_allowed", "tip_invalid", "tip_not_allowed", "tip_recipient_unknown", "validation", "account_not_found", "action_confirmation_required", "admin_required", "api_not_approved", "app_check_invalid", "app_check_missing", "cashregister_not_assigned", "cashregister_not_found", "cashregister_token_invalid", "cashregister_token_missing", "dialect_mismatch", "internal_translation_error", "live_not_enabled", "method_not_allowed", "mfa_required", "not_found", "password_change_required", "register_user_no_business", "register_user_not_allowed", "register_user_not_found", "response_translation_failed", "second_factor_required", "session_expired", "session_other_cashregister", "unauthorized", "user_disabled", "user_verification_failed", "route_missing", "response_unreadable"];
+export declare const RECEIPT_ERROR_CODES: readonly ["cancellation_reference_unavailable", "cashregister_closed", "cashregister_decommissioned", "final_receipt_expired", "final_receipt_not_allowed", "module_inactive", "not_permitted", "receipt_limit_exceeded", "receipt_not_found", "receipt_outcome_unknown", "receipt_type_invalid", "server_error", "signature_incomplete", "signature_missing", "signing_failed", "small_business_vat_not_allowed", "tip_invalid", "tip_not_allowed", "tip_recipient_unknown", "validation", "voucher_balance_changed", "account_not_found", "action_confirmation_required", "admin_required", "api_not_approved", "app_check_invalid", "app_check_missing", "cashregister_not_assigned", "cashregister_not_found", "cashregister_token_invalid", "cashregister_token_missing", "dialect_mismatch", "internal_translation_error", "live_not_enabled", "method_not_allowed", "mfa_required", "not_found", "password_change_required", "register_user_no_business", "register_user_not_allowed", "register_user_not_found", "response_translation_failed", "second_factor_required", "session_expired", "session_other_cashregister", "unauthorized", "user_disabled", "user_verification_failed", "route_missing", "response_unreadable"];
 export type ReceiptErrorCode = (typeof RECEIPT_ERROR_CODES)[number];
 export declare function isReceiptErrorCode(value: unknown): value is ReceiptErrorCode;
 /** Der Code eines geworfenen Fehlers, wenn er in [RECEIPT_ERROR_CODES] steht; sonst `undefined`. */

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

@@ -28,6 +28,7 @@ export const RECEIPT_ERROR_CODES = Object.freeze([
     'receipt_not_found',
     'receipt_outcome_unknown',
     'receipt_type_invalid',
+    'server_error',
     'signature_incomplete',
     'signature_missing',
     'signing_failed',
@@ -36,6 +37,7 @@ export const RECEIPT_ERROR_CODES = Object.freeze([
     'tip_not_allowed',
     'tip_recipient_unknown',
     'validation',
+    'voucher_balance_changed',
     // Anmeldung und Rand (errorCodes.auth ohne Partner-Zugang, errorCodes.edge)
     'account_not_found',
     'action_confirmation_required',

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

@@ -36,7 +36,7 @@ export interface ReceiptItem {
      * negative Entgeltminderungen je Steuersatz; die Kennzeichnung steuert nur
      * die Bon-Darstellung (Summenzeile mit Aufteilung), nie die Beträge.
      */
-    kind?: 'tip' | 'discount';
+    kind?: 'tip' | 'discount' | 'voucher' | 'voucher_float';
     /** Empfaenger der Trinkgeld-Position; `null` = nicht zugeordnet. */
     recipient?: TipRecipient | null;
     /** Zahlart der Trinkgeld-Position (kann von der des Belegs abweichen). */
@@ -73,6 +73,14 @@ export interface TipRecipient {
 export declare function isTipItem(item: ReceiptItem | ReceiptItemPayloadRead): boolean;
 /** Rabatt-Position? Die eine Erkennungsstelle — niemand prueft `kind` selbst. */
 export declare function isDiscountItem(item: ReceiptItem | ReceiptItemPayloadRead): boolean;
+/**
+ * Gutschein-Position (Server, neue Gutscheinform)? `voucher` ist eine
+ * Einloesung oder ein Verkauf mit Umsatzsteuer-Wirkung, siehe
+ * [isVoucherFloatItem] fuer den durchlaufenden Posten.
+ */
+export declare function isVoucherItem(item: ReceiptItem | ReceiptItemPayloadRead): boolean;
+/** Gutschein-Position als durchlaufender Posten (Mehrzweck: Verkauf, Auszahlung)? */
+export declare function isVoucherFloatItem(item: ReceiptItem | ReceiptItemPayloadRead): boolean;
 /**
  * Nutzlast-Form, die dieses Paket **schreibt** (v2):
  * `{ name, quantity, unitPriceCents, vatRate }`.
@@ -82,8 +90,8 @@ export interface ReceiptItemPayload {
     quantity: number;
     unitPriceCents: number;
     vatRate: number;
-    /** Trinkgeld-/Rabatt-Kennzeichnung, siehe [ReceiptItem.kind]. */
-    kind?: 'tip' | 'discount';
+    /** Trinkgeld-/Rabatt-/Gutschein-Kennzeichnung, siehe [ReceiptItem.kind]. */
+    kind?: 'tip' | 'discount' | 'voucher' | 'voucher_float';
     recipient?: TipRecipient | null;
     paymentMethod?: string;
     receivedImmediately?: boolean;

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

@@ -9,6 +9,18 @@ export function isTipItem(item) {
 export function isDiscountItem(item) {
     return item != null && item.kind === 'discount';
 }
+/**
+ * Gutschein-Position (Server, neue Gutscheinform)? `voucher` ist eine
+ * Einloesung oder ein Verkauf mit Umsatzsteuer-Wirkung, siehe
+ * [isVoucherFloatItem] fuer den durchlaufenden Posten.
+ */
+export function isVoucherItem(item) {
+    return item != null && item.kind === 'voucher';
+}
+/** Gutschein-Position als durchlaufender Posten (Mehrzweck: Verkauf, Auszahlung)? */
+export function isVoucherFloatItem(item) {
+    return item != null && item.kind === 'voucher_float';
+}
 export function toReceiptItemPayload(item) {
     // Schreibpfad bleibt streng: ein unaufgeloester (unbekannter) Steuersatz
     // darf nicht unbesehen wieder hinausgehen.
@@ -37,6 +49,11 @@ export function toReceiptItemPayload(item) {
     // am Bon wieder als gewoehnliche Warenzeile mit "1 x" an.
     if (item.kind === 'discount')
         nutzlast.kind = 'discount';
+    // Gutschein-Positionen (vom Server) reisen mit: der Cache der Kasse schreibt
+    // gelesene Belege wieder, und ein Wunsch an den Server traegt sie nie
+    // (createReceipt weist sie als voucher_invalid ab).
+    if (item.kind === 'voucher' || item.kind === 'voucher_float')
+        nutzlast.kind = item.kind;
     // Artikel-Verweis reist mit (Erloesgruppen im Bericht); leere Werte nicht.
     if (item.articleId != null && item.articleId !== '')
         nutzlast.articleId = item.articleId;
@@ -81,7 +98,9 @@ export function fromReceiptItemPayload(payload) {
             }
             : payload.kind === 'discount'
                 ? { kind: 'discount' }
-                : {}),
+                : payload.kind === 'voucher' || payload.kind === 'voucher_float'
+                    ? { kind: payload.kind }
+                    : {}),
         // Artikel-Verweis erhalten (Storno-Spiegelung schreibt ihn wieder mit).
         ...(typeof payload.articleId === 'string' && payload.articleId !== '' ? { articleId: payload.articleId } : {}),
         // Lager: Bezug und Rueckgabe-Wahl einer Storno-Zeile (nur gelesen; ein

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

@@ -162,10 +162,22 @@ export declare function receiptValueVoucherSign(receipt: Receipt): 1 | -1;
  * mindert nichts: den Rabatt nimmt der Server dort ueber Ausgleichspositionen
  * (`kind: 'discount'`) zurueck, und belegToepfe verteilt einen Promo-Eintrag
  * nur auf eine positive Topfsumme, die ein Storno nie hat.
+ *
+ * Gutscheine der neuen Form (Spec 2026-10-14): ihr Betrag steht als Position
+ * (`kind: 'voucher'` bei Einzweck/Leistung, `'voucher_float'` im 0-%-Topf) und
+ * zaehlt hier schon mit den Positionen. Ein Eintrag mit `zeroRateBucket`
+ * (Server: `imNullTopf`, Mehrzweck-Verkauf ab dem Stichtag, Auszahlung) zaehlt
+ * darum nicht noch einmal -- sonst stuende der Betrag doppelt am Bon
+ * (Vorfall 16.10.2026: Verkauf ueber 30 € mit „Gesamt 60,00“). Eintraege der
+ * Arten `single_purpose`/`service` tragen keinen Fluss (wie
+ * gutschein-beleg.zahlbetrag, das nur `value`/`promo` an den Fluss gibt).
  */
 export declare function receiptSubSumCents(receipt: Receipt): number;
 /**
  * Gesamtsumme in **Cent** — Zwischensumme minus eingeloeste Wertgutscheine
- * (am Storno-Beleg plus, siehe [receiptValueVoucherSign]).
+ * (am Storno-Beleg plus, siehe [receiptValueVoucherSign]). Zwilling von
+ * zahlungen-core.wertgutscheinFlussCents: eine Auszahlung (`payout`) eines
+ * Wertgutscheins ohne `zeroRateBucket` mindert wie eine Einloesung; mit
+ * `zeroRateBucket` steht sie als Position und zaehlt nur dort.
  */
 export declare function receiptSumCents(receipt: Receipt): number;

package/dist/esm/models/receipt.js

@@ -149,11 +149,22 @@ export function receiptValueVoucherSign(receipt) {
  * mindert nichts: den Rabatt nimmt der Server dort ueber Ausgleichspositionen
  * (`kind: 'discount'`) zurueck, und belegToepfe verteilt einen Promo-Eintrag
  * nur auf eine positive Topfsumme, die ein Storno nie hat.
+ *
+ * Gutscheine der neuen Form (Spec 2026-10-14): ihr Betrag steht als Position
+ * (`kind: 'voucher'` bei Einzweck/Leistung, `'voucher_float'` im 0-%-Topf) und
+ * zaehlt hier schon mit den Positionen. Ein Eintrag mit `zeroRateBucket`
+ * (Server: `imNullTopf`, Mehrzweck-Verkauf ab dem Stichtag, Auszahlung) zaehlt
+ * darum nicht noch einmal -- sonst stuende der Betrag doppelt am Bon
+ * (Vorfall 16.10.2026: Verkauf ueber 30 € mit „Gesamt 60,00“). Eintraege der
+ * Arten `single_purpose`/`service` tragen keinen Fluss (wie
+ * gutschein-beleg.zahlbetrag, das nur `value`/`promo` an den Fluss gibt).
  */
 export function receiptSubSumCents(receipt) {
     const vz = receiptValueVoucherSign(receipt);
     let cents = receipt.items.reduce((acc, item) => acc + receiptItemTotalCents(item), 0);
     for (const voucher of receipt.vouchers) {
+        if (voucher.zeroRateBucket === true)
+            continue;
         if (vz === 1 && voucher.action === VoucherAction.redeem && voucher.type === VoucherType.promo) {
             cents -= voucher.valueCents ?? 0;
         }
@@ -165,13 +176,18 @@ export function receiptSubSumCents(receipt) {
 }
 /**
  * Gesamtsumme in **Cent** — Zwischensumme minus eingeloeste Wertgutscheine
- * (am Storno-Beleg plus, siehe [receiptValueVoucherSign]).
+ * (am Storno-Beleg plus, siehe [receiptValueVoucherSign]). Zwilling von
+ * zahlungen-core.wertgutscheinFlussCents: eine Auszahlung (`payout`) eines
+ * Wertgutscheins ohne `zeroRateBucket` mindert wie eine Einloesung; mit
+ * `zeroRateBucket` steht sie als Position und zaehlt nur dort.
  */
 export function receiptSumCents(receipt) {
     const vz = receiptValueVoucherSign(receipt);
     let cents = receiptSubSumCents(receipt);
     for (const voucher of receipt.vouchers) {
-        if (voucher.action === VoucherAction.redeem && voucher.type === VoucherType.value) {
+        if (voucher.zeroRateBucket === true || voucher.type !== VoucherType.value)
+            continue;
+        if (voucher.action === VoucherAction.redeem || voucher.action === VoucherAction.payout) {
             cents -= vz * (voucher.valueCents ?? 0);
         }
     }

package/dist/esm/models/voucher.d.ts

@@ -16,11 +16,41 @@ export interface Voucher {
     action: VoucherAction | string;
     type: VoucherType | string;
     valueCents?: number;
+    /** Neue Form: Betrag in Cent (Verkauf, Einloesung, Auszahlung). */
+    amountCents?: number;
+    /** Neue Form, Leistungsgutschein: verkaufter Artikel. */
+    articleId?: string;
+    /** Neue Form, Leistungsgutschein: Menge (Verkauf) bzw. eingeloeste Menge. */
+    quantity?: number;
+    /** Neue Form, Leistungsgutschein einloesen: Indizes der Belegpositionen. */
+    positions?: number[];
+    /** Neue Form, Auszahlung: Grund, 1 bis 200 Zeichen. */
+    reason?: string;
+    voucherType?: string;
+    voucherId?: string;
+    /** Letzte vier Zeichen des Codes; der Klartext steht nie am Beleg. */
+    codeSuffix?: string;
+    vatRateBp?: number;
+    article?: VoucherArticle;
+    balanceAfterCents?: number;
+    remainingQuantityAfter?: number;
+    taxedWith?: string;
+    exempt?: boolean;
+    zeroRateBucket?: boolean;
+}
+/** Artikel eines Leistungsgutscheins, wie der Server ihn am Beleg festhaelt. */
+export interface VoucherArticle {
+    id: string;
+    name: string;
+    vatRateBp: number;
+    priceCents: number;
 }
 /**
- * Nutzlast eines Gutscheins. Geschrieben wird nur `valueCents` (ganze Cent);
- * `value` (Euro) kommt nur beim Lesen vor: der Server legt es in seinen
- * Antworten daneben, gelesen wird es nur, wenn `valueCents` fehlt.
+ * Nutzlast eines Gutscheins. Altform: nur `valueCents` (ganze Cent); `value`
+ * (Euro) kommt nur beim Lesen vor: der Server legt es in seinen Antworten
+ * daneben, gelesen wird es nur, wenn `valueCents` fehlt. Neue Form: roh mit
+ * `amountCents` und den weiteren Feldern; gesetzte Feldern gehen hinaus,
+ * fehlende fehlen (kein `valueCents: null` an der neuen Form).
  * `name` und `code` gehen nur hinaus, wenn sie gesetzt sind.
  */
 export interface VoucherPayload {
@@ -29,8 +59,31 @@ export interface VoucherPayload {
     action: string;
     type: string;
     value?: number | null;
-    valueCents: number | null;
+    valueCents?: number | null;
+    amountCents?: number;
+    articleId?: string;
+    quantity?: number;
+    positions?: number[];
+    reason?: string;
+    voucherType?: string;
+    voucherId?: string;
+    codeSuffix?: string;
+    vatRateBp?: number;
+    article?: VoucherArticle;
+    balanceAfterCents?: number;
+    remainingQuantityAfter?: number;
+    taxedWith?: string;
+    exempt?: boolean;
+    zeroRateBucket?: boolean;
 }
+/** Arten der neuen Gutscheinform (die Altwerte sind `value` und `promo`). */
+export declare const NEUE_GUTSCHEINARTEN: readonly string[];
+/** Gehoert der Gutschein zur neuen Form (Art oder Aktion `payout`)? */
+export declare function isNewFormVoucher(voucher: Pick<Voucher, 'type' | 'action'>): boolean;
+/** Felder, die nur der Server setzt; an einem Wunsch sind sie `voucher_invalid`. */
+export declare const GUTSCHEIN_SERVERFELDER: readonly ["voucherId", "codeSuffix", "zeroRateBucket", "voucherType"];
+/** Welche Serverfelder tragt der Gutschein (leere Liste = keines)? */
+export declare function voucherServerFields(voucher: Voucher): string[];
 export declare function toVoucherPayload(voucher: Voucher): VoucherPayload;
 /**
  * Ist der Gutschein an das Backend sendbar? Zwilling von `KeckVoucher.isValid`