@kreiseck/kasseneck-api 1.13.0 → 1.15.0

package/dist/esm/client/list-receipts.js

@@ -0,0 +1,284 @@
+import { KeckPaymentMethod, ReceiptType } from '../enums/index.js';
+import { CANCELLATION_STATUSES, fromReceiptPayload, fromReceiptPaymentPayload, } from '../models/index.js';
+import { readEnumKey } from '../models/enum-payload.js';
+import { KasseneckValidationError } from './errors.js';
+/**
+ * Belege einer Kasse auflisten (`listReceipts`, nur unter `/v3`): ein Tag oder
+ * ein Zeitraum von hoechstens 31 Kalendertagen, Seite fuer Seite ueber einen
+ * undurchsichtigen Cursor. Nachfolger von `getReportV2` fuer Listen;
+ * `getReportV2` bleibt fuer Berichte.
+ *
+ * **Anmeldung wie `getReportV2`:** API-Schluessel plus `cashregister-token`
+ * (`apiKeyAuth`); die Kasse kommt aus dem Token, nie aus einem Parameter.
+ * Kassen-Bediener (Geraet + PIN) weist der Server ab; die Kasse hat dafuer
+ * `listMyReceipts` am Kassenweg. Dieses Paket bildet das nicht nach, wer darf,
+ * entscheidet allein das Backend.
+ *
+ * Zeiten sind die **Wiener Wanduhr** als Text, wie `timeStamp` am Beleg; der
+ * Server vergleicht sie als Text. Ein Tag ist ein Kalendertag, auch an den
+ * Tagen der Zeitumstellung, und die Grenze von 31 Tagen zaehlt Kalendertage,
+ * nicht 31 x 24 Stunden. Die Pruefung hier rechnet darum ohne Zeitzone, genau
+ * wie der Server (`beleg-liste-core.js`).
+ */
+/** Ansicht einer Seite: `summary` eine schlanke Zeile je Beleg, `full` das gespeicherte Belegdokument. */
+export const LIST_RECEIPTS_VIEWS = Object.freeze(['summary', 'full']);
+/** Reihenfolge: `desc` neueste zuerst (Vorgabe des Servers), `asc` aelteste zuerst. */
+export const LIST_RECEIPTS_ORDERS = Object.freeze(['desc', 'asc']);
+/** Groesste Seite, die der Server liefert (`limit`); ohne Angabe nimmt er 100. */
+export const LIST_RECEIPTS_LIMIT_MAX = 500;
+/** Laengster Zeitraum in Kalendertagen (`to` hoechstens `from` + 31 Tage). */
+export const LIST_RECEIPTS_DAYS_MAX = 31;
+/**
+ * So viele Seiten holt [listAllReceipts] hoechstens, dann bricht er mit
+ * Fehler ab. Schutz gegen einen Cursor, der nie endet; mit der Seitengroesse
+ * des Helfers (500) sind das 50.000 Belege, mehr als jede Kasse in 31 Tagen
+ * ausstellt.
+ */
+export const LIST_ALL_RECEIPTS_MAX_PAGES = 100;
+/**
+ * Fehlercodes von `listReceipts` (`code` des [KasseneckApiError]), dazu die
+ * gemeinsamen Codes von Anmeldung und Rand (Kassen-Token, Live-Gate,
+ * API-Freigabe). Ein Code ausserhalb bleibt ueber `KasseneckApiError.code`
+ * lesbar. Die Regeln der ersten sieben prueft dieses Paket schon vor dem
+ * Senden (ausser `invalid_cursor`: ob ein Cursor zur Abfrage passt, weiss nur
+ * der Server).
+ */
+export const LIST_RECEIPTS_ERROR_CODES = Object.freeze([
+    'invalid_date', // kein Datum JJJJ-MM-TT bzw. Zeitpunkt JJJJ-MM-TTThh:mm:ss, oder unmoeglich (2026-02-30)
+    'invalid_range', // nicht genau eine Form (date ODER from + to), oder to nicht nach from
+    'range_too_long', // mehr als 31 Kalendertage
+    'invalid_limit', // keine ganze Zahl von 1 bis 500 (der Server kappt nie still)
+    'invalid_order', // weder desc noch asc
+    'invalid_view', // weder summary noch full
+    'invalid_cursor', // veraendert, fremde Kasse, oder Zeitfenster/order/view anders als auf Seite 1
+    'server_error',
+]);
+const TAG = /^(\d{4})-(\d{2})-(\d{2})$/;
+const ZEIT = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})$/;
+/** Kalendertag als UTC-Mitternacht (nur zum Rechnen mit Tagen; auch fuer Jahre unter 100). */
+function utcTag(jahr, monat, tag) {
+    const d = new Date(Date.UTC(2000, 0, 1));
+    d.setUTCFullYear(jahr, monat - 1, tag);
+    return d;
+}
+/** Ein echtes Kalenderdatum (2026-02-30 nicht)? */
+function kalendertag(jahr, monat, tag) {
+    const d = utcTag(jahr, monat, tag);
+    return d.getUTCFullYear() === jahr && d.getUTCMonth() === monat - 1 && d.getUTCDate() === tag;
+}
+const zwei = (n) => String(n).padStart(2, '0');
+/** Wanduhr-Text `YYYY-MM-DDTHH:mm:ss` aus einem Tag oder Zeitpunkt; sonst `null`. */
+function wanduhr(wert) {
+    if (typeof wert !== 'string')
+        return null;
+    const t = TAG.exec(wert);
+    if (t)
+        return kalendertag(+t[1], +t[2], +t[3]) ? `${wert}T00:00:00` : null;
+    const z = ZEIT.exec(wert);
+    if (z && kalendertag(+z[1], +z[2], +z[3]) && +z[4] <= 23 && +z[5] <= 59 && +z[6] <= 59)
+        return wert;
+    return null;
+}
+/** Wanduhr-Text plus ganze Kalendertage, Uhrzeit bleibt (ohne Zeitzone gerechnet). */
+function plusTage(zeit, tage) {
+    const [datum, uhr] = zeit.split('T');
+    const [j, m, t] = datum.split('-').map(Number);
+    const d = utcTag(j, m, t + tage);
+    return `${String(d.getUTCFullYear()).padStart(4, '0')}-${zwei(d.getUTCMonth() + 1)}-${zwei(d.getUTCDate())}T${uhr}`;
+}
+const gesetzt = (v) => v !== undefined && v !== null;
+/** Fehler in der Eingabe des Aufrufers: es geht keine Anfrage raus. */
+function eingabefehler(grund) {
+    return new KasseneckValidationError('listReceipts', grund, 'request');
+}
+/** Antwort meldet Erfolg, traegt aber nicht, was der Aufruf zusagt. */
+function antwortfehler(grund) {
+    return new KasseneckValidationError('listReceipts', grund, 'response');
+}
+/**
+ * Prueft die Eingabe nach den Regeln des Servers und gibt die Parameter
+ * zurueck, die hinausgehen (nur gesetzte Felder, Werte unveraendert, damit
+ * Folgeseiten dasselbe Fenster senden).
+ */
+function parameter(options) {
+    if (options == null || typeof options !== 'object')
+        throw eingabefehler('Optionen fehlen (date oder from und to)');
+    const o = options;
+    const raus = {};
+    if (gesetzt(o.date)) {
+        if (gesetzt(o.from) || gesetzt(o.to))
+            throw eingabefehler('entweder date oder from und to angeben, nicht beides');
+        if (typeof o.date !== 'string' || !TAG.test(o.date) || wanduhr(o.date) === null) {
+            throw eingabefehler(`date muss ein Datum YYYY-MM-DD sein, war "${String(o.date)}"`);
+        }
+        raus['date'] = o.date;
+    }
+    else {
+        if (!gesetzt(o.from) || !gesetzt(o.to))
+            throw eingabefehler('Zeitraum fehlt: date oder from und to angeben');
+        const von = wanduhr(o.from);
+        if (von === null)
+            throw eingabefehler(`from muss YYYY-MM-DD oder YYYY-MM-DDTHH:mm:ss sein, war "${String(o.from)}"`);
+        const bis = wanduhr(o.to);
+        if (bis === null)
+            throw eingabefehler(`to muss YYYY-MM-DD oder YYYY-MM-DDTHH:mm:ss sein, war "${String(o.to)}"`);
+        if (bis <= von)
+            throw eingabefehler('to muss nach from liegen (to ist ausschliesslich)');
+        if (bis > plusTage(von, LIST_RECEIPTS_DAYS_MAX)) {
+            throw eingabefehler(`Zeitraum hoechstens ${LIST_RECEIPTS_DAYS_MAX} Kalendertage (to hoechstens from + ${LIST_RECEIPTS_DAYS_MAX} Tage)`);
+        }
+        raus['from'] = o.from;
+        raus['to'] = o.to;
+    }
+    if (gesetzt(o.limit)) {
+        if (!Number.isInteger(o.limit) || o.limit < 1 || o.limit > LIST_RECEIPTS_LIMIT_MAX) {
+            throw eingabefehler(`limit muss eine ganze Zahl von 1 bis ${LIST_RECEIPTS_LIMIT_MAX} sein, war "${String(o.limit)}"`);
+        }
+        raus['limit'] = o.limit;
+    }
+    if (gesetzt(o.order)) {
+        if (!LIST_RECEIPTS_ORDERS.includes(o.order))
+            throw eingabefehler(`order muss desc oder asc sein, war "${String(o.order)}"`);
+        raus['order'] = o.order;
+    }
+    if (gesetzt(o.view)) {
+        if (!LIST_RECEIPTS_VIEWS.includes(o.view))
+            throw eingabefehler(`view muss summary oder full sein, war "${String(o.view)}"`);
+        raus['view'] = o.view;
+    }
+    if (gesetzt(o.cursor)) {
+        if (typeof o.cursor !== 'string' || o.cursor === '')
+            throw eingabefehler('cursor muss der nextCursor der vorigen Seite sein (nicht leerer Text)');
+        raus['cursor'] = o.cursor;
+    }
+    return raus;
+}
+const istObjekt = (w) => w != null && typeof w === 'object' && !Array.isArray(w);
+const text = (w) => (typeof w === 'string' ? w : null);
+// Ganze Cent; ein einzelner unbrauchbarer Betrag laesst die Liste nicht scheitern.
+const cent = (w) => (typeof w === 'number' && Number.isInteger(w) ? w : 0);
+function istStornoStand(w) {
+    return typeof w === 'string' && CANCELLATION_STATUSES.includes(w);
+}
+/** Zeile `view: summary` vom Draht. */
+export function fromListReceiptsSummaryPayload(payload) {
+    const brutto = istObjekt(payload['grossByRateCents']) ? payload['grossByRateCents'] : {};
+    const bediener = payload['operator'];
+    const bezug = payload['cancellationOf'];
+    return {
+        receiptId: text(payload['receiptId']),
+        counter: typeof payload['counter'] === 'number' ? payload['counter'] : null,
+        receiptType: typeof payload['receiptType'] === 'string' ? readEnumKey(ReceiptType, payload['receiptType']) : null,
+        zeroKind: text(payload['zeroKind']),
+        timeStamp: text(payload['timeStamp']),
+        totalCents: cent(payload['totalCents']),
+        grossByRateCents: {
+            standard: cent(brutto['standard']),
+            reduced1: cent(brutto['reduced1']),
+            reduced2: cent(brutto['reduced2']),
+            zero: cent(brutto['zero']),
+            special: cent(brutto['special']),
+        },
+        paymentMethod: typeof payload['paymentMethod'] === 'string' ? readEnumKey(KeckPaymentMethod, payload['paymentMethod']) : null,
+        ...(Array.isArray(payload['payments'])
+            ? { payments: payload['payments'].filter(istObjekt).map((z) => fromReceiptPaymentPayload(z)) }
+            : {}),
+        ...(typeof payload['tipCents'] === 'number' ? { tipCents: payload['tipCents'] } : {}),
+        operator: istObjekt(bediener) ? { name: typeof bediener['name'] === 'string' ? bediener['name'] : '' } : null,
+        cancellationOf: istObjekt(bezug) ? { receiptId: text(bezug['receiptId']), timeStamp: text(bezug['timeStamp']) } : null,
+        cancellationReason: text(payload['cancellationReason']),
+        cancellationStatus: istStornoStand(payload['cancellationStatus']) ? payload['cancellationStatus'] : 'unknown',
+        signatureOk: payload['signatureOk'] !== false,
+        customProjectId: text(payload['customProjectId']),
+        fullReceiptId: text(payload['fullReceiptId']),
+    };
+}
+function tagessumme(roh) {
+    if (roh === null)
+        return null;
+    if (!istObjekt(roh))
+        throw antwortfehler('daySummary ist weder ein Objekt noch null');
+    const saetze = Array.isArray(roh['revenueByRate']) ? roh['revenueByRate'] : [];
+    return {
+        date: typeof roh['date'] === 'string' ? roh['date'] : '',
+        receiptCount: cent(roh['receiptCount']),
+        revenueCents: cent(roh['revenueCents']),
+        revenueByRate: saetze.filter(istObjekt).map((z) => ({ rateBp: cent(z['rateBp']), grossCents: cent(z['grossCents']) })),
+    };
+}
+/**
+ * Eine Seite Belege der angemeldeten Kasse (`listReceipts`). Die Eingabe wird
+ * vor dem Senden nach den Regeln des Servers geprueft (genau eine Form des
+ * Zeitfensters, Datumsformat, hoechstens 31 Kalendertage, `limit` 1-500,
+ * `order`, `view`); ein Verstoss wirft [KasseneckValidationError] mit
+ * `scope: 'request'`, ohne dass etwas hinausgeht.
+ *
+ * Mit `view: 'full'` sind die Belege das gespeicherte Belegdokument
+ * ([Receipt], dieselbe Form wie `getReportV2`), sonst [ListReceiptsSummary].
+ * Alle Seiten auf einmal: [listAllReceipts].
+ */
+export async function listReceipts(transport, options) {
+    const params = parameter(options);
+    const voll = params['view'] === 'full';
+    const daten = await transport('listReceipts', params);
+    if (!istObjekt(daten))
+        throw antwortfehler('Antwort enthaelt keine Daten (data fehlt)');
+    const liste = daten['receipts'];
+    if (!Array.isArray(liste) || liste.some((b) => !istObjekt(b))) {
+        throw antwortfehler('Antwort enthaelt keine Belegliste (data.receipts fehlt)');
+    }
+    if (typeof daten['hasMore'] !== 'boolean')
+        throw antwortfehler('Antwort ohne hasMore');
+    const weiter = daten['nextCursor'];
+    // Ein `hasMore` ohne Cursor liesse den Aufrufer ratlos (oder einen Blaetterer im Kreis laufen).
+    if (daten['hasMore'] ? typeof weiter !== 'string' || weiter === '' : weiter !== null) {
+        throw antwortfehler('nextCursor passt nicht zu hasMore (Text bei hasMore, sonst null)');
+    }
+    const receipts = (voll
+        ? liste.map((b) => fromReceiptPayload(b))
+        : liste.map((b) => fromListReceiptsSummaryPayload(b)));
+    return {
+        receipts,
+        hasMore: daten['hasMore'],
+        nextCursor: daten['hasMore'] ? weiter : null,
+        ...('daySummary' in daten ? { daySummary: tagessumme(daten['daySummary']) } : {}),
+    };
+}
+/**
+ * Alle Belege eines Tages oder Zeitraums, Seite fuer Seite: holt mit
+ * [listReceipts] die erste Seite, dann mit `cursor: nextCursor` und
+ * demselben Zeitfenster, `order` und `view` jede weitere, und liefert jeden
+ * Beleg einzeln, in der Reihenfolge des Servers. Jeder Beleg des Fensters
+ * kommt genau einmal.
+ *
+ * Ohne `limit` holt der Helfer Seiten zu 500 (weniger Aufrufe als die
+ * Vorgabe 100 des Servers). Mit `cursor` setzt er an dieser Stelle fort.
+ *
+ * Ein Fehler auf irgendeiner Seite bricht ab (der Fehler kommt im
+ * `for await` an); die bis dahin gelieferten Belege bleiben gueltig. Nach
+ * [LIST_ALL_RECEIPTS_MAX_PAGES] Seiten, oder wenn der Server denselben
+ * Cursor zweimal nennt, bricht er mit [KasseneckValidationError]
+ * (`scope: 'response'`) ab, statt endlos zu laufen.
+ *
+ * `daySummary` liefert der Helfer nicht; wer sie braucht, ruft die erste
+ * Seite mit [listReceipts].
+ */
+export async function* listAllReceipts(transport, options) {
+    // Frueh pruefen: ein Eingabefehler kommt beim ersten Schritt an, vor jedem Aufruf.
+    parameter(options);
+    const grund = { ...options, limit: options.limit ?? LIST_RECEIPTS_LIMIT_MAX };
+    let cursor = options.cursor;
+    const gesehen = new Set();
+    for (let seite = 1; seite <= LIST_ALL_RECEIPTS_MAX_PAGES; seite++) {
+        const page = await listReceipts(transport, { ...grund, cursor });
+        yield* page.receipts;
+        if (!page.hasMore)
+            return;
+        const weiter = page.nextCursor;
+        if (gesehen.has(weiter) || weiter === cursor)
+            throw antwortfehler('Server nennt denselben Cursor erneut; Abbruch statt Endlosschleife');
+        gesehen.add(weiter);
+        cursor = weiter;
+    }
+    throw antwortfehler(`mehr als ${LIST_ALL_RECEIPTS_MAX_PAGES} Seiten; Zeitfenster kleiner waehlen`);
+}

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

@@ -1,5 +1,6 @@
 import { ReceiptType, type ReceiptTypeKey, KeckPaymentMethod, type KeckPaymentMethodKey } from '../enums/index.js';
 import { type Receipt, type ReceiptCompany, type ReceiptItem, type Voucher, type ReceiptSummary, type ReportMonth, type CancellationItem, type CancellationOf, type CancellationReason, type TipRefundSource, type ReturnDisposition, type ReceiptPaymentInput, type RegistrationInfo, type ReceiptEmailVia } from '../models/index.js';
+import { type ReceiptOutput, type ReceiptOutputEntryErrorCode, type ReceiptOutputLogKind, type ReceiptOutputResult } from '../models/receipt-output.js';
 import type { InternerTransport } from './aufrufe.js';
 import { type ReceiptLayout } from '../receipt/layout.js';
 import type { PosPaperSize } from '../printing/escpos.js';
@@ -140,8 +141,9 @@ export type CancelReceiptOptions = {
     /**
      * Rueckzahlung je Zahlung (Betraege negativ, `refundOf` = `id` der
      * Originalzahlung). Ohne Angabe spiegelt der Server die Restbetraege jeder
-     * Originalzahlung; ein Teilstorno eines Belegs mit mehreren Zahlungen
-     * braucht sie (`cancellation_payments_required`).
+     * Originalzahlung (Ausnahme Storno einer Gutschein-Auszahlung: genau eine
+     * positive Barzahlung ohne `refundOf`); ein Teilstorno eines Belegs mit
+     * mehreren Zahlungen braucht sie (`cancellation_payments_required`).
      *
      * **Karten-Storno:** `provider`, `providerPaymentId` und `providerData`
      * beschreiben die ERSTATTUNG am Terminal, nie die Originalzahlung. Die
@@ -216,6 +218,13 @@ export interface ReceiptWithCompany {
      * setzen das Logo in genau dieser Stufe; fehlt der Wert, gilt `M`.
      */
     logoScale: SheetLogoSize;
+    /**
+     * Ausgaben des Belegs (`data.outputs`, nur `getReceipt` unter `/v3`): die
+     * neuesten 20, neueste zuerst. Fehlt, wenn die Antwort keine Liste traegt
+     * (Verkauf, `/api`). Gelesen nach [ReceiptOutput]; ein kaputter Eintrag
+     * faellt weg, der Beleg bleibt lesbar.
+     */
+    outputs?: ReceiptOutput[];
 }
 /**
  * Das Zeilenmodell zum Drucken und Anzeigen eines Belegs aus einer Antwort.
@@ -402,6 +411,80 @@ export interface SendReceiptEmailResult {
  * eine zweite Mail und zaehlt auf die Schleuse.
  */
 export declare function sendReceiptEmail(transport: InternerTransport, options: SendReceiptEmailOptions): Promise<SendReceiptEmailResult>;
+/**
+ * Eine Ausgabe, wie die Kasse sie puffert und meldet: ein Druck oder ein
+ * Teilen des Belegs. Siehe [logReceiptOutputs].
+ */
+export interface ReceiptOutputEntry {
+    /**
+     * Idempotenzschluessel des Eintrags, am Geraet beim Puffern vergeben und
+     * beim Nachsenden unveraendert: ein zweites Melden legt keinen zweiten
+     * Eintrag an. 8–64 Zeichen `[A-Za-z0-9_-]` (Regel des Servers); ein anderer
+     * Schluessel wirft vor dem Senden.
+     */
+    key: string;
+    /** Beleg in der Kasse der Anmeldung; ein Beleg einer anderen Kasse ist `receipt_not_found`. */
+    receiptId: string;
+    /** `print` (Erstdruck), `reprint` (Duplikat, gedruckt mit `markAsDuplicate`), `link_shared`, `pdf_shared`. */
+    kind: ReceiptOutputLogKind;
+    /**
+     * Zeitpunkt am Geraet: Millisekunden seit 1970 oder ISO 8601 **mit Zone**
+     * (`new Date().toISOString()`); Text ohne Zone wirft vor dem Senden. Eine
+     * falsch gehende Geraeteuhr lehnt der Server nicht ab: er klemmt die Zeit auf
+     * Belegzeit bis Eingang.
+     */
+    at: number | string;
+    /**
+     * Ergebnis eines Drucks: `ok`, `failed` (sicher nicht gedruckt) oder
+     * `unclear` (Ausgang offen). Pflicht bei `print` und `reprint` (sonst lehnt
+     * der Server den Eintrag mit `validation` ab); beim Teilen ohne Angabe `ok`.
+     */
+    result?: ReceiptOutputResult;
+}
+/** Eingabe von [logReceiptOutputs]. Die Kasse bindet die Anmeldung (wie bei [sendReceiptEmail]). */
+export interface LogReceiptOutputsOptions {
+    /** 1–50 Eintraege ([RECEIPT_OUTPUT_ENTRIES_MAX]); ein groesserer Puffer geht in mehreren Aufrufen hinaus. */
+    entries: ReceiptOutputEntry[];
+}
+/** Ein abgelehnter Eintrag: dauerhaft, aus dem Puffer nehmen und nicht noch einmal senden. */
+export interface RejectedReceiptOutput {
+    key: string;
+    /** Aus [RECEIPT_OUTPUT_ENTRY_ERROR_CODES]; ein Code, den das Paket nicht kennt, bleibt lesbar. */
+    code: ReceiptOutputEntryErrorCode | (string & {});
+}
+/** Antwort von [logReceiptOutputs]. */
+export interface LogReceiptOutputsResult {
+    /** Angenommene Eintraege, auch die schon frueher gemeldeten (gleicher Schluessel). */
+    accepted: number;
+    rejected: RejectedReceiptOutput[];
+}
+/**
+ * Meldet Drucke und das Teilen eines Belegs an das Protokoll „Ausgaben“
+ * (Endpunkt `logReceiptOutputs`, nur ueber den Kassenweg `/api/v3`; mit
+ * `registerUserAuth` und mit `apiKeyAuth`). Registrierkassen-Erlass
+ * BMF-AV Nr. 2/2026, Abschnitt 4.2: die Belegerteilung ist zu dokumentieren.
+ * Der Beleg selbst bleibt unberuehrt; das Protokoll steht nie im DEP.
+ *
+ * **Ein Eintrag scheitert nie die anderen.** Der Server nimmt jeden Eintrag
+ * einzeln an oder lehnt ihn mit Code ab (`rejected`, Codes
+ * [RECEIPT_OUTPUT_ENTRY_ERROR_CODES]); nach einer Erfolgsantwort ist jeder
+ * gesendete Eintrag erledigt. Die Kasse puffert die Eintraege (offline,
+ * Neustart) und sendet sie spaeter; der Puffer blockiert nie Druck oder Teilen.
+ *
+ * **Wiederholen ist gefahrlos:** jeder Eintrag traegt seinen Schluessel. Bei
+ * unklarem Ausgang (`outcome: 'unknown'`) dieselben Eintraege mit denselben
+ * Schluesseln noch einmal senden.
+ *
+ * **Vor dem Senden abgewiesen** wird nur, was die ganze Anfrage scheitern
+ * liesse oder ohne Netz sicher falsch ist: keine oder mehr als 50 Eintraege,
+ * ein unbekanntes Feld (oben oder im Eintrag), ein fehlender Beleg, ein
+ * Schluessel ausserhalb der Regel des Servers, eine Art oder ein Ergebnis
+ * ausserhalb des Katalogs, eine Zeit, die weder ganze Millisekunden noch
+ * ISO 8601 mit Zone ist. `email` und `opened` gehen hinaus und kommen als
+ * `invalid_output_kind` zurueck: so verwirft der Puffer genau diesen Eintrag.
+ * Fehler der ganzen Anfrage: [RECEIPT_OUTPUT_ERROR_CODES].
+ */
+export declare function logReceiptOutputs(transport: InternerTransport, options: LogReceiptOutputsOptions): Promise<LogReceiptOutputsResult>;
 /**
  * Prueft die Gutschein-Kombination eines Belegs und liefert den ersten
  * Regelverstoss als Text (oder `null`) — Zwilling von

package/dist/esm/client/receipts.js

@@ -1,8 +1,10 @@
 import { ReceiptType, KeckPaymentMethod, CreditCardProvider, VoucherAction, VoucherType, } from '../enums/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 { RECEIPT_OUTPUT_ENTRIES_MAX, RECEIPT_OUTPUT_KINDS, RECEIPT_OUTPUT_RESULTS, receiptOutputsFromWire, } from '../models/receipt-output.js';
+import { VoucherCode } from '@kreiseck/validator';
 import { parseServerTimeStamp, toViennaWallClock } from '../vienna-time.js';
 import { euroToCents } from '../money.js';
-import { KasseneckValidationError, isKasseneckApiError, signiertGelesen } from './errors.js';
+import { KasseneckApiError, KasseneckValidationError, isKasseneckApiError, signiertGelesen } from './errors.js';
 import { buildReceiptLayout } from '../receipt/layout.js';
 /**
  * Das Zeilenmodell zum Drucken und Anzeigen eines Belegs aus einer Antwort.
@@ -38,14 +40,44 @@ export function receiptLayoutFromResult(result, options = {}) {
  * die Hand des Aufrufers, sondern zu einem der benannten Aufrufe darunter.
  */
 export async function createReceipt(rufen, options) {
-    const daten = await rufen('createReceipt', createReceiptParams(options));
+    const daten = await createReceiptRufen(rufen, options);
     return signiertGelesen('createReceipt', () => belegAusHuelle(daten, 'createReceipt'));
 }
 /** Wie [createReceipt], liest aus derselben Antwort zusaetzlich die Firmendaten. */
 async function createReceiptWithCompany(rufen, options) {
-    const daten = await rufen('createReceipt', createReceiptParams(options));
+    const daten = await createReceiptRufen(rufen, options);
     return signiertGelesen('createReceipt', () => belegMitFirmaAusHuelle(daten, 'createReceipt'));
 }
+/**
+ * Sendet `createReceipt`; die Gutschein-Codes der Nutzlast gelten als Geheimnis
+ * (normiert und formatiert): der Transport siebt Ursachen und Details, ein
+ * Servertext, der den Code wiederholt, wird hier geschwaerzt.
+ */
+async function createReceiptRufen(rufen, options) {
+    // Der Code geht so hinaus, wie er getippt wurde: die getippte Schreibweise (auch ungueltig,
+    // etwa mit falscher Pruefziffer) zaehlt ebenso als Geheimnis wie normiert und formatiert.
+    // Kurze Reste (Endung mit vier Zeichen) werden nie eingetragen.
+    const geheim = [...new Set((options.vouchers ?? []).flatMap((v) => {
+            if (typeof v.code !== 'string')
+                return [];
+            const roh = v.code.trim();
+            const geprueft = VoucherCode.validate(v.code);
+            const liste = geprueft.ok ? [geprueft.normalized, VoucherCode.format(geprueft.normalized)] : [];
+            if (roh.length >= 8)
+                liste.push(roh);
+            return liste;
+        }))].sort((a, b) => b.length - a.length);
+    try {
+        return await rufen('createReceipt', createReceiptParams(options), undefined, geheim);
+    }
+    catch (fehler) {
+        if (fehler instanceof KasseneckApiError && geheim.some((g) => fehler.serverMessage.includes(g))) {
+            const text = geheim.reduce((t, g) => t.split(g).join('****'), fehler.serverMessage);
+            throw new KasseneckApiError('createReceipt', text, fehler.details, fehler.code);
+        }
+        throw fehler;
+    }
+}
 /**
  * Baut die Nutzlast von `createReceipt` und prueft die Eingabe. Wirft, bevor
  * irgendetwas rausgeht — ein Beleg ist nicht folgenlos wiederholbar.
@@ -171,6 +203,24 @@ function pruefeRueckgabeWahl(wert, pfad) {
         throw new KasseneckValidationError('cancelReceipt', `${pfad}: erlaubt sind ${RETURN_DISPOSITIONS.join(', ')}`, 'request');
     }
 }
+/**
+ * Storno einer Gutschein-Auszahlung: genau eine positive Barzahlung ohne `refundOf`
+ * (das Geld kommt in die Lade zurueck). Alles andere bleibt Rueckzahlung mit negativem Betrag;
+ * ob der Beleg eine Auszahlung war, entscheidet der Server.
+ */
+function istStornoAuszahlung(payments, original) {
+    if (!Array.isArray(payments) || payments.length !== 1)
+        return false;
+    // Kennt der Aufrufer das Original und es hat keine Auszahlung, bleibt es bei negativen Rueckzahlungen.
+    if (original != null && !(original.vouchers ?? []).some((v) => v.action === VoucherAction.payout))
+        return false;
+    const z = payments[0];
+    if (z == null || typeof z !== 'object')
+        return false;
+    const m = z['method'];
+    const art = typeof m === 'object' && m !== null ? m.value : m;
+    return art === 'cash' && typeof z['amountCents'] === 'number' && z['amountCents'] > 0 && z['refundOf'] === undefined;
+}
 /**
  * Storno-Beleg zu einem bestehenden Beleg — voll oder in Teilen. Prueft die
  * Eingabe, bevor etwas hinausgeht; der Server haelt die Restmengen und die
@@ -218,7 +268,7 @@ export async function cancelReceipt(transport, options) {
         throw new KasseneckValidationError('cancelReceipt', `${altfeld} gibt es unter /v3 nicht mehr: Rueckzahlungen gehen als payments hinaus.`, 'request');
     }
     // `payments: null` gilt wie im Backend als nicht angegeben.
-    const zahlungen = options.payments != null ? gepruefteZahlungen(options.payments, true, 'cancelReceipt') : undefined;
+    const zahlungen = options.payments != null ? gepruefteZahlungen(options.payments, true, 'cancelReceipt', false, istStornoAuszahlung(options.payments, options.receipt)) : undefined;
     if (zahlungen !== undefined)
         pruefeKartenRueckbuchung(zahlungen, options.receipt);
     const params = { cashregisterId, originalReceiptId, reason: options.reason };
@@ -450,6 +500,111 @@ export async function sendReceiptEmail(transport, options) {
         via,
     };
 }
+const AUSGABEN_FELDER = ['entries'];
+const AUSGABE_FELDER = ['key', 'receiptId', 'kind', 'at', 'result'];
+/** Idempotenzschluessel eines Eintrags, wie der Server ihn annimmt. */
+const AUSGABE_SCHLUESSEL = /^[A-Za-z0-9_-]{8,64}$/;
+/** Zeitpunkt als Text: RFC 3339 mit Zone, bis zu sechs Nachkommastellen (wie der Server). */
+const AUSGABE_ZEIT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|[+-]\d{2}:\d{2})$/;
+/**
+ * Meldet Drucke und das Teilen eines Belegs an das Protokoll „Ausgaben“
+ * (Endpunkt `logReceiptOutputs`, nur ueber den Kassenweg `/api/v3`; mit
+ * `registerUserAuth` und mit `apiKeyAuth`). Registrierkassen-Erlass
+ * BMF-AV Nr. 2/2026, Abschnitt 4.2: die Belegerteilung ist zu dokumentieren.
+ * Der Beleg selbst bleibt unberuehrt; das Protokoll steht nie im DEP.
+ *
+ * **Ein Eintrag scheitert nie die anderen.** Der Server nimmt jeden Eintrag
+ * einzeln an oder lehnt ihn mit Code ab (`rejected`, Codes
+ * [RECEIPT_OUTPUT_ENTRY_ERROR_CODES]); nach einer Erfolgsantwort ist jeder
+ * gesendete Eintrag erledigt. Die Kasse puffert die Eintraege (offline,
+ * Neustart) und sendet sie spaeter; der Puffer blockiert nie Druck oder Teilen.
+ *
+ * **Wiederholen ist gefahrlos:** jeder Eintrag traegt seinen Schluessel. Bei
+ * unklarem Ausgang (`outcome: 'unknown'`) dieselben Eintraege mit denselben
+ * Schluesseln noch einmal senden.
+ *
+ * **Vor dem Senden abgewiesen** wird nur, was die ganze Anfrage scheitern
+ * liesse oder ohne Netz sicher falsch ist: keine oder mehr als 50 Eintraege,
+ * ein unbekanntes Feld (oben oder im Eintrag), ein fehlender Beleg, ein
+ * Schluessel ausserhalb der Regel des Servers, eine Art oder ein Ergebnis
+ * ausserhalb des Katalogs, eine Zeit, die weder ganze Millisekunden noch
+ * ISO 8601 mit Zone ist. `email` und `opened` gehen hinaus und kommen als
+ * `invalid_output_kind` zurueck: so verwirft der Puffer genau diesen Eintrag.
+ * Fehler der ganzen Anfrage: [RECEIPT_OUTPUT_ERROR_CODES].
+ */
+export async function logReceiptOutputs(transport, options) {
+    const name = 'logReceiptOutputs';
+    const anfrage = (grund) => new KasseneckValidationError(name, grund, 'request');
+    if (options === null || typeof options !== 'object' || Array.isArray(options))
+        throw anfrage('Anfrage muss ein Objekt sein');
+    // Ein unbekanntes Feld (etwa eine zweite cashregisterId) ginge sonst still verloren.
+    const fremd = Object.keys(options).find((k) => !AUSGABEN_FELDER.includes(k));
+    if (fremd != null)
+        throw anfrage(`unbekanntes Feld "${fremd}"`);
+    const roh = options.entries;
+    if (!Array.isArray(roh) || roh.length === 0 || roh.length > RECEIPT_OUTPUT_ENTRIES_MAX) {
+        throw anfrage(`entries muss 1–${RECEIPT_OUTPUT_ENTRIES_MAX} Eintraege haben`);
+    }
+    const entries = roh.map((e, i) => {
+        const wo = `entries[${i}]`;
+        if (e === null || typeof e !== 'object' || Array.isArray(e))
+            throw anfrage(`${wo} muss ein Objekt sein`);
+        const eintrag = {};
+        for (const [feld, w] of Object.entries(e)) {
+            if (!AUSGABE_FELDER.includes(feld))
+                throw anfrage(`${wo}: unbekanntes Feld "${feld}"`);
+            if (w !== undefined)
+                eintrag[feld] = w;
+        }
+        // Schluessel und Beleg nie getrimmt: ein veraenderter Schluessel waere ein anderer.
+        for (const feld of ['key', 'receiptId']) {
+            const w = eintrag[feld];
+            if (typeof w !== 'string' || w.trim() === '')
+                throw anfrage(`${wo}.${feld} fehlt`);
+        }
+        // Dieselbe Regel wie der Server: so traegt jede Antwort (`rejected[].key`)
+        // genau den Schluessel, unter dem die Kasse den Eintrag puffert.
+        if (!AUSGABE_SCHLUESSEL.test(eintrag.key))
+            throw anfrage(`${wo}.key muss 8–64 Zeichen [A-Za-z0-9_-] haben`);
+        // Ein Wert ausserhalb des Katalogs liesse den Rand die ganze Anfrage abweisen.
+        if (!RECEIPT_OUTPUT_KINDS.includes(eintrag.kind)) {
+            throw anfrage(`${wo}.kind muss ${RECEIPT_OUTPUT_KINDS.join(', ')} sein`);
+        }
+        if (eintrag.result !== undefined && !RECEIPT_OUTPUT_RESULTS.includes(eintrag.result)) {
+            throw anfrage(`${wo}.result muss ${RECEIPT_OUTPUT_RESULTS.join(', ')} sein`);
+        }
+        const at = eintrag.at;
+        // Text nur als ISO 8601 mit Zone (Regel des Servers): ohne Zone waere die
+        // Zeit je nach Geraet eine andere; das ist ein Fehler der Kasse, kein Fall
+        // fuer den Puffer.
+        const zeitOk = (typeof at === 'number' && Number.isSafeInteger(at) && at >= 0) || (typeof at === 'string' && AUSGABE_ZEIT.test(at));
+        if (!zeitOk)
+            throw anfrage(`${wo}.at muss Millisekunden seit 1970 oder ISO 8601 mit Zone sein`);
+        return eintrag;
+    });
+    return ausgabenGemeldet(name, await transport(name, { entries }));
+}
+/** Antwort von `logReceiptOutputs`, streng: `accepted` ganze Zahl ab 0, `rejected` Liste aus Schluessel und Code. */
+function ausgabenGemeldet(name, daten) {
+    if (daten === null || typeof daten !== 'object' || Array.isArray(daten))
+        throw antwortfehler(name, 'Antwort ist kein Objekt');
+    const { accepted, rejected } = daten;
+    if (typeof accepted !== 'number' || !Number.isSafeInteger(accepted) || accepted < 0) {
+        throw antwortfehler(name, 'Antwort enthaelt keine Zahl accepted');
+    }
+    if (!Array.isArray(rejected))
+        throw antwortfehler(name, 'Antwort enthaelt keine Liste rejected');
+    return {
+        accepted,
+        rejected: rejected.map((r, i) => {
+            const { key, code } = (r ?? {});
+            if (typeof key !== 'string' || typeof code !== 'string' || code === '') {
+                throw antwortfehler(name, `rejected[${i}] ohne Schluessel oder Code`);
+            }
+            return { key, code };
+        }),
+    };
+}
 /**
  * Prueft die Gutschein-Kombination eines Belegs und liefert den ersten
  * Regelverstoss als Text (oder `null`) — Zwilling von
@@ -643,14 +798,15 @@ const MAX_ZAHLUNGEN = 20;
  * (Summe, Anbieter-Pflicht und Trinkgeld prueft der Server). Wirft, bevor
  * etwas hinausgeht.
  */
-function gepruefteZahlungen(roh, storno, functionName, auszahlung = false) {
+function gepruefteZahlungen(roh, storno, functionName, auszahlung = false, stornoAuszahlung = 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;
+    // Storno einer Auszahlung: der Kunde gibt das Geld zurueck, die eine Barzahlung ist positiv (zahlungen-core stornoAuszahlung).
+    const negativ = (storno && !stornoAuszahlung) || auszahlung;
     if (auszahlung) {
         const e = roh[0];
         if (roh.length !== 1)
@@ -823,6 +979,7 @@ export function belegAusHuelle(daten, functionName) {
 export function belegMitFirmaAusHuelle(daten, functionName) {
     const receipt = belegAusHuelle(daten, functionName);
     const d = (daten ?? {});
+    const outputs = receiptOutputsFromWire(d.outputs);
     const layout = d.layout && typeof d.layout === 'object' && Array.isArray(d.layout.lines) ? d.layout : null;
     const angaben = d.registrationInfo && typeof d.registrationInfo === 'object' ? readRegistrationInfo(d.registrationInfo) : null;
     return {
@@ -834,6 +991,7 @@ export function belegMitFirmaAusHuelle(daten, functionName) {
         layout,
         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 } : {}),
     };
 }
 /**

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

@@ -4,7 +4,7 @@
 export declare const VoucherType: {
     /** Altform: Wertgutschein (Wert im Cent, Code frei). */
     readonly value: "value";
-    /** Altform: Rabatt-/Promotionsgutschein. */
+    /** Altform: Rabatt-/Aktionsgutschein. */
     readonly promo: "promo";
     /** Neue Form: Mehrzweckgutschein (Zahlungsmittel, Steuer erst bei der Einloesung). */
     readonly multi_purpose: "multi_purpose";

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

@@ -4,7 +4,7 @@
 export const VoucherType = {
     /** Altform: Wertgutschein (Wert im Cent, Code frei). */
     value: 'value',
-    /** Altform: Rabatt-/Promotionsgutschein. */
+    /** Altform: Rabatt-/Aktionsgutschein. */
     promo: 'promo',
     /** Neue Form: Mehrzweckgutschein (Zahlungsmittel, Steuer erst bei der Einloesung). */
     multi_purpose: 'multi_purpose',