@kreiseck/kasseneck-api 1.28.0 → 1.30.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (122) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/README.md +111 -0
  3. package/dist/cjs/client/api.d.ts +15 -0
  4. package/dist/cjs/client/api.js +8 -0
  5. package/dist/cjs/client/aufrufe.d.ts +3 -3
  6. package/dist/cjs/client/aufrufe.js +28 -0
  7. package/dist/cjs/client/index.d.ts +1 -0
  8. package/dist/cjs/client/index.js +17 -1
  9. package/dist/cjs/client/list-receipts.d.ts +5 -0
  10. package/dist/cjs/client/list-receipts.js +5 -1
  11. package/dist/cjs/client/receipts.d.ts +6 -0
  12. package/dist/cjs/client/receipts.js +1 -0
  13. package/dist/cjs/client/terminal.d.ts +206 -0
  14. package/dist/cjs/client/terminal.js +288 -0
  15. package/dist/cjs/enums/voucher-type.d.ts +5 -1
  16. package/dist/cjs/enums/voucher-type.js +5 -1
  17. package/dist/cjs/index.d.ts +2 -2
  18. package/dist/cjs/index.js +28 -4
  19. package/dist/cjs/inventory/index.d.ts +2 -2
  20. package/dist/cjs/inventory/index.js +3 -2
  21. package/dist/cjs/inventory/typen.d.ts +39 -1
  22. package/dist/cjs/inventory/vertrag.d.ts +13 -2
  23. package/dist/cjs/inventory/vertrag.js +16 -1
  24. package/dist/cjs/inventory/webhook.d.ts +3 -0
  25. package/dist/cjs/inventory/webhook.js +39 -0
  26. package/dist/cjs/models/index.d.ts +1 -1
  27. package/dist/cjs/models/index.js +10 -2
  28. package/dist/cjs/models/voucher.d.ts +78 -2
  29. package/dist/cjs/models/voucher.js +127 -5
  30. package/dist/cjs/pos/gutschein.d.ts +13 -0
  31. package/dist/cjs/pos/gutschein.js +5 -1
  32. package/dist/cjs/pos/index.d.ts +1 -1
  33. package/dist/cjs/pos/index.js +3 -2
  34. package/dist/cjs/pos/texte.d.ts +20 -0
  35. package/dist/cjs/pos/texte.js +11 -0
  36. package/dist/cjs/receipt/due.d.ts +8 -1
  37. package/dist/cjs/receipt/due.js +1 -0
  38. package/dist/cjs/receipt/gutschein-plan.d.ts +11 -1
  39. package/dist/cjs/receipt/gutschein-plan.js +116 -1
  40. package/dist/cjs/receipt/layout.js +39 -6
  41. package/dist/cjs/stored/draht.js +5 -0
  42. package/dist/cjs/stored/vokabular.d.ts +3 -1
  43. package/dist/cjs/stored/vokabular.js +15 -2
  44. package/dist/cjs/version.d.ts +1 -1
  45. package/dist/cjs/version.js +1 -1
  46. package/dist/esm/client/api.d.ts +15 -0
  47. package/dist/esm/client/api.js +8 -0
  48. package/dist/esm/client/aufrufe.d.ts +3 -3
  49. package/dist/esm/client/aufrufe.js +28 -0
  50. package/dist/esm/client/index.d.ts +1 -0
  51. package/dist/esm/client/index.js +1 -0
  52. package/dist/esm/client/list-receipts.d.ts +5 -0
  53. package/dist/esm/client/list-receipts.js +5 -2
  54. package/dist/esm/client/receipts.d.ts +6 -0
  55. package/dist/esm/client/receipts.js +1 -0
  56. package/dist/esm/client/terminal.d.ts +206 -0
  57. package/dist/esm/client/terminal.js +278 -0
  58. package/dist/esm/enums/voucher-type.d.ts +5 -1
  59. package/dist/esm/enums/voucher-type.js +5 -1
  60. package/dist/esm/index.d.ts +2 -2
  61. package/dist/esm/index.js +2 -2
  62. package/dist/esm/inventory/index.d.ts +2 -2
  63. package/dist/esm/inventory/index.js +1 -1
  64. package/dist/esm/inventory/typen.d.ts +39 -1
  65. package/dist/esm/inventory/vertrag.d.ts +13 -2
  66. package/dist/esm/inventory/vertrag.js +15 -0
  67. package/dist/esm/inventory/webhook.d.ts +3 -0
  68. package/dist/esm/inventory/webhook.js +39 -0
  69. package/dist/esm/models/index.d.ts +1 -1
  70. package/dist/esm/models/index.js +1 -1
  71. package/dist/esm/models/voucher.d.ts +78 -2
  72. package/dist/esm/models/voucher.js +122 -4
  73. package/dist/esm/pos/gutschein.d.ts +13 -0
  74. package/dist/esm/pos/gutschein.js +4 -0
  75. package/dist/esm/pos/index.d.ts +1 -1
  76. package/dist/esm/pos/index.js +1 -1
  77. package/dist/esm/pos/texte.d.ts +20 -0
  78. package/dist/esm/pos/texte.js +11 -0
  79. package/dist/esm/receipt/due.d.ts +8 -1
  80. package/dist/esm/receipt/due.js +1 -0
  81. package/dist/esm/receipt/gutschein-plan.d.ts +11 -1
  82. package/dist/esm/receipt/gutschein-plan.js +117 -2
  83. package/dist/esm/receipt/layout.js +40 -7
  84. package/dist/esm/stored/draht.js +6 -1
  85. package/dist/esm/stored/vokabular.d.ts +3 -1
  86. package/dist/esm/stored/vokabular.js +14 -1
  87. package/dist/esm/version.d.ts +1 -1
  88. package/dist/esm/version.js +1 -1
  89. package/fixtures/expected/voucher-external-redeem.grid32.txt +30 -0
  90. package/fixtures/expected/voucher-external-redeem.grid48.txt +27 -0
  91. package/fixtures/expected/voucher-external-redeem.lines.json +280 -0
  92. package/fixtures/expected/voucher-external-redeem.sheet32.json +206 -0
  93. package/fixtures/expected/voucher-external-redeem.sheet48.json +188 -0
  94. package/fixtures/expected/voucher-external-sale.grid32.txt +27 -0
  95. package/fixtures/expected/voucher-external-sale.grid48.txt +26 -0
  96. package/fixtures/expected/voucher-external-sale.lines.json +256 -0
  97. package/fixtures/expected/voucher-external-sale.sheet32.json +188 -0
  98. package/fixtures/expected/voucher-external-sale.sheet48.json +182 -0
  99. package/fixtures/hobex-hps-codes.json +1 -1
  100. package/fixtures/invoice-api.schema.json +1 -1
  101. package/fixtures/invoice-texts.json +1 -1
  102. package/fixtures/manifest.json +16 -0
  103. package/fixtures/pos-texts.json +22 -2
  104. package/fixtures/receipt-due-voucher-generated.json +2 -2
  105. package/fixtures/receipts/voucher-external-redeem.json +85 -0
  106. package/fixtures/receipts/voucher-external-sale.json +80 -0
  107. package/fixtures/stored/voucher-cases.json +2800 -0
  108. package/fixtures/surface.json +32 -4
  109. package/fixtures/v3/antworten/belege.json +4 -3
  110. package/fixtures/v3/antworten/belegmail.json +2 -2
  111. package/fixtures/v3/antworten/berichte.json +2 -2
  112. package/fixtures/v3/antworten/kasse-belege.json +4 -3
  113. package/fixtures/v3/antworten/kasse.json +16 -10
  114. package/fixtures/v3/antworten/lager.json +6 -3
  115. package/fixtures/v3/antworten/rechnungen.json +2 -2
  116. package/fixtures/v3/antworten/storno.json +2 -2
  117. package/fixtures/v3/stored/belege.json +2 -2
  118. package/fixtures/v3/stored/kasse.json +3 -3
  119. package/fixtures/v3/stored/rechnungen.json +2 -2
  120. package/fixtures/v3/v3-vokabular.json +222 -10
  121. package/fixtures/v3/zahlbetrag-faelle.json +2 -2
  122. package/package.json +1 -1
@@ -11,6 +11,7 @@
11
11
  * Tag) `YYYY-MM-DD`.
12
12
  */
13
13
  import type { InventoryWarningCode, InventoryWebhookEventType, LandedCostAllocation, LandedCostType, LocationType, ReservationStatus, StockChangeCause, StockCondition, StockKind, StockLossReason, StockMovementSource, StockMovementType, StocktakeActorType, StocktakeCheckReason, StocktakeInventoryAsOf, StocktakeNotBookedReason, StocktakeScopeType, StocktakeSource, StocktakeStatus, StocktakeType, WebhookDeliveryStatus, WithdrawalType } from './vertrag.js';
14
+ import type { ListedFullReceipt } from '../client/list-receipts.js';
14
15
  /**
15
16
  * Ein Artikel, wie `getArticle`, `listArticles`, `lookupArticleByCode` und die
16
17
  * Ereignisse `article.*` ihn senden.
@@ -355,7 +356,44 @@ export interface InventoryWebhookEnvelope<T extends InventoryWebhookEventType, D
355
356
  test: boolean;
356
357
  data: D;
357
358
  }
358
- export type InventoryWebhookEvent = InventoryWebhookEnvelope<'stock.changed', StockChangedEventData> | InventoryWebhookEnvelope<'stock.below_minimum', StockBelowMinimumEventData> | InventoryWebhookEnvelope<'article.created', Article> | InventoryWebhookEnvelope<'article.updated', Article> | InventoryWebhookEnvelope<'article.deactivated', Article> | InventoryWebhookEnvelope<'reservation.expired', Reservation> | InventoryWebhookEnvelope<'reservation.released', Reservation> | InventoryWebhookEnvelope<'reservation.redeemed', Reservation> | InventoryWebhookEnvelope<'variant_group.created', VariantGroup> | InventoryWebhookEnvelope<'variant_group.updated', VariantGroup>;
359
+ /**
360
+ * Nutzlast von `receipt.created` (Beleg-Webhooks): der Beleg wie `listReceipts` mit `view: 'full'` (dieselbe
361
+ * Darstellung, auch Fremdgutscheine mit Nummer, eigene maskiert). Ist der Beleg fuer eine Zustellung zu gross,
362
+ * fehlen seine Positionen (`receipt.items` leer), `truncated` ist `true` und `hint` sagt, ihn mit `getReceipt`
363
+ * zu holen.
364
+ */
365
+ export interface ReceiptCreatedEventData {
366
+ receipt: ListedFullReceipt;
367
+ /** Nur bei einer gekuerzten Zustellung: `true` (die Positionen fehlen). */
368
+ truncated?: true;
369
+ /** Nur bei einer gekuerzten Zustellung: Hinweis (deutsch). */
370
+ hint?: string;
371
+ }
372
+ /** Eine stornierte Position aus dem Storno-Beleg (`cancelledItems[]`). */
373
+ export interface ReceiptCancelledItem {
374
+ /** Index der Position im Original; `null`, wenn der Storno-Beleg ihn nicht traegt (Positionen ohne Artikel). */
375
+ index: number | null;
376
+ quantity: number | null;
377
+ }
378
+ /** Eine Rueckzahlung des Storno-Belegs (`refunds[]`): Betrag positiv in Cent. */
379
+ export interface ReceiptRefund {
380
+ /** Kennung der Zahlung im Original (`payments[].id`); `null` ohne Bezug (etwa bar zurueck). */
381
+ refundOf: string | null;
382
+ amountCents: number | null;
383
+ /** Zahlart wie in `payments[].method`. */
384
+ method: string | null;
385
+ }
386
+ /**
387
+ * Nutzlast von `receipt.cancelled`: der Storno-Beleg wie bei `receipt.created`, dazu Bezug, stornierte Positionen
388
+ * und Rueckzahlungen, abgeleitet aus dem Storno-Beleg selbst. `cancellationOf` ist die Beleg-ID des Originals;
389
+ * der veraltete Storno ohne Bezug traegt `null`.
390
+ */
391
+ export interface ReceiptCancelledEventData extends ReceiptCreatedEventData {
392
+ cancellationOf: string | null;
393
+ cancelledItems: ReceiptCancelledItem[];
394
+ refunds: ReceiptRefund[];
395
+ }
396
+ export type InventoryWebhookEvent = InventoryWebhookEnvelope<'stock.changed', StockChangedEventData> | InventoryWebhookEnvelope<'stock.below_minimum', StockBelowMinimumEventData> | InventoryWebhookEnvelope<'article.created', Article> | InventoryWebhookEnvelope<'article.updated', Article> | InventoryWebhookEnvelope<'article.deactivated', Article> | InventoryWebhookEnvelope<'reservation.expired', Reservation> | InventoryWebhookEnvelope<'reservation.released', Reservation> | InventoryWebhookEnvelope<'reservation.redeemed', Reservation> | InventoryWebhookEnvelope<'variant_group.created', VariantGroup> | InventoryWebhookEnvelope<'variant_group.updated', VariantGroup> | InventoryWebhookEnvelope<'receipt.created', ReceiptCreatedEventData> | InventoryWebhookEnvelope<'receipt.cancelled', ReceiptCancelledEventData>;
359
397
  /**
360
398
  * Die Felder eines Artikels beim Anlegen. Bei der Anlage heisst `null` „nicht
361
399
  * angegeben“ (ausser bei `name`, der Pflicht ist).
@@ -58,9 +58,20 @@ export type WebhookDeliveryStatus = (typeof WEBHOOK_DELIVERY_STATUSES)[number];
58
58
  * Variantengruppe wie `getVariantGroup`; `updated` kommt nur bei einer aussen
59
59
  * sichtbaren Aenderung (neuer Wert, neue oder stillgelegte Variante, Name,
60
60
  * Vorgaben, Stilllegen der Gruppe).
61
+ * `receipt.created` und `receipt.cancelled` (Beleg-Webhooks, Server 2026-11) tragen den Beleg wie
62
+ * `listReceipts` mit `view: 'full'` ([RECEIPT_WEBHOOK_EVENTS]); sie brauchen das Modul Registrierkasse, nicht
63
+ * das Lager (sonst `webhook_event_not_available` beim Anlegen oder Aendern).
61
64
  */
62
- export declare const INVENTORY_WEBHOOK_EVENTS: readonly ["stock.changed", "stock.below_minimum", "article.created", "article.updated", "article.deactivated", "reservation.expired", "reservation.released", "reservation.redeemed", "variant_group.created", "variant_group.updated"];
65
+ export declare const INVENTORY_WEBHOOK_EVENTS: readonly ["stock.changed", "stock.below_minimum", "article.created", "article.updated", "article.deactivated", "reservation.expired", "reservation.released", "reservation.redeemed", "variant_group.created", "variant_group.updated", "receipt.created", "receipt.cancelled"];
63
66
  export type InventoryWebhookEventType = (typeof INVENTORY_WEBHOOK_EVENTS)[number];
67
+ /**
68
+ * Die Beleg-Ereignisse der Konto-Webhooks: `receipt.created` fuer jeden neu signierten Beleg jeder Art (auch den
69
+ * Storno-Beleg), `receipt.cancelled` zusaetzlich fuer jeden Storno-Beleg. Ein Storno bringt also beide. Die
70
+ * Ereignis-ID ist je Beleg und Ereignis fest: darauf entdoppeln. Fehlt eine fortlaufende Belegnummer einer Kasse,
71
+ * den Zeitraum mit `listReceipts` nachholen.
72
+ */
73
+ export declare const RECEIPT_WEBHOOK_EVENTS: readonly ["receipt.created", "receipt.cancelled"];
74
+ export type ReceiptWebhookEventType = (typeof RECEIPT_WEBHOOK_EVENTS)[number];
64
75
  /**
65
76
  * Die Felder der Huelle jeder Zustellung, in der Reihenfolge am Draht. Statt
66
77
  * `partnerId` (Partner-Webhooks) traegt sie `accountId`; `test` steht nur auf
@@ -117,7 +128,7 @@ export declare const INVENTORY_LIST_LIMIT_MAX = 200;
117
128
  * `stocktake_not_closed` (das Protokoll gibt es erst nach dem Abschluss, auch
118
129
  * nicht fuer eine abgebrochene Inventur).
119
130
  */
120
- export declare const INVENTORY_ERROR_CODES: readonly ["validation", "invalid_cursor", "article_not_found", "webhook_not_found", "webhook_limit", "invalid_webhook_url", "event_not_subscribed", "webhook_inactive", "inventory_api_not_enabled", "module_inactive", "rate_limited", "server_error", "idempotency_key_required", "idempotency_conflict", "location_not_found", "location_inactive", "invalid_location", "invalid_locations", "invalid_transfer", "operation_not_found", "already_reversed", "reversal_not_possible", "reversal_not_supported", "exceeds_stock", "no_positions", "too_many_positions", "invalid_step", "invalid_quantity", "invalid_amount", "invalid_price", "negative_value", "invalid_reason", "note_required", "withdrawal_type_required", "invalid_method", "invalid_stock_kind", "invalid_minimum", "invalid_dimensions", "weight_missing", "invalid_landed_cost", "invalid_distribution", "landed_costs_mismatch", "return_totals_mismatch", "lot_not_found", "invalid_serial", "serial_required", "serial_not_allowed", "serial_already_exists", "serial_not_in_stock", "code_taken", "external_id_taken", "group_not_found", "revenue_group_not_found", "stock_kind_locked", "article_inactive", "invalid_position", "invalid_condition", "reason_required", "insufficient_available", "reservation_not_found", "reservation_not_active", "variant_group_not_found", "variant_already_exists", "invalid_variant_attributes", "variant_group_inactive", "variant_limit", "stocktake_not_found", "stocktake_not_open", "stocktake_closed", "stocktake_not_in_review", "stocktake_closing", "stocktake_location_busy", "stocktake_review_running", "stocktake_recount_open", "article_not_in_scope", "article_not_tracked", "count_not_found", "count_already_voided", "serial_already_counted", "too_many_counts", "stocktake_not_closed"];
131
+ export declare const INVENTORY_ERROR_CODES: readonly ["validation", "invalid_cursor", "article_not_found", "webhook_not_found", "webhook_limit", "invalid_webhook_url", "event_not_subscribed", "webhook_inactive", "inventory_api_not_enabled", "module_inactive", "rate_limited", "server_error", "webhook_event_not_available", "idempotency_key_required", "idempotency_conflict", "location_not_found", "location_inactive", "invalid_location", "invalid_locations", "invalid_transfer", "operation_not_found", "already_reversed", "reversal_not_possible", "reversal_not_supported", "exceeds_stock", "no_positions", "too_many_positions", "invalid_step", "invalid_quantity", "invalid_amount", "invalid_price", "negative_value", "invalid_reason", "note_required", "withdrawal_type_required", "invalid_method", "invalid_stock_kind", "invalid_minimum", "invalid_dimensions", "weight_missing", "invalid_landed_cost", "invalid_distribution", "landed_costs_mismatch", "return_totals_mismatch", "lot_not_found", "invalid_serial", "serial_required", "serial_not_allowed", "serial_already_exists", "serial_not_in_stock", "code_taken", "external_id_taken", "group_not_found", "revenue_group_not_found", "stock_kind_locked", "article_inactive", "invalid_position", "invalid_condition", "reason_required", "insufficient_available", "reservation_not_found", "reservation_not_active", "variant_group_not_found", "variant_already_exists", "invalid_variant_attributes", "variant_group_inactive", "variant_limit", "stocktake_not_found", "stocktake_not_open", "stocktake_closed", "stocktake_not_in_review", "stocktake_closing", "stocktake_location_busy", "stocktake_review_running", "stocktake_recount_open", "article_not_in_scope", "article_not_tracked", "count_not_found", "count_already_voided", "serial_already_counted", "too_many_counts", "stocktake_not_closed"];
121
132
  export type InventoryErrorCode = (typeof INVENTORY_ERROR_CODES)[number];
122
133
  /**
123
134
  * Codes, die Anmeldung und Rand auf jedem Lager-Aufruf erzeugen koennen,
@@ -136,6 +136,9 @@ export const WEBHOOK_DELIVERY_STATUSES = ['delivered', 'pending', 'failed', 'dro
136
136
  * Variantengruppe wie `getVariantGroup`; `updated` kommt nur bei einer aussen
137
137
  * sichtbaren Aenderung (neuer Wert, neue oder stillgelegte Variante, Name,
138
138
  * Vorgaben, Stilllegen der Gruppe).
139
+ * `receipt.created` und `receipt.cancelled` (Beleg-Webhooks, Server 2026-11) tragen den Beleg wie
140
+ * `listReceipts` mit `view: 'full'` ([RECEIPT_WEBHOOK_EVENTS]); sie brauchen das Modul Registrierkasse, nicht
141
+ * das Lager (sonst `webhook_event_not_available` beim Anlegen oder Aendern).
139
142
  */
140
143
  export const INVENTORY_WEBHOOK_EVENTS = [
141
144
  'stock.changed',
@@ -148,7 +151,16 @@ export const INVENTORY_WEBHOOK_EVENTS = [
148
151
  'reservation.redeemed',
149
152
  'variant_group.created',
150
153
  'variant_group.updated',
154
+ 'receipt.created',
155
+ 'receipt.cancelled',
151
156
  ];
157
+ /**
158
+ * Die Beleg-Ereignisse der Konto-Webhooks: `receipt.created` fuer jeden neu signierten Beleg jeder Art (auch den
159
+ * Storno-Beleg), `receipt.cancelled` zusaetzlich fuer jeden Storno-Beleg. Ein Storno bringt also beide. Die
160
+ * Ereignis-ID ist je Beleg und Ereignis fest: darauf entdoppeln. Fehlt eine fortlaufende Belegnummer einer Kasse,
161
+ * den Zeitraum mit `listReceipts` nachholen.
162
+ */
163
+ export const RECEIPT_WEBHOOK_EVENTS = ['receipt.created', 'receipt.cancelled'];
152
164
  /**
153
165
  * Die Felder der Huelle jeder Zustellung, in der Reihenfolge am Draht. Statt
154
166
  * `partnerId` (Partner-Webhooks) traegt sie `accountId`; `test` steht nur auf
@@ -218,6 +230,9 @@ export const INVENTORY_ERROR_CODES = [
218
230
  'module_inactive',
219
231
  'rate_limited',
220
232
  'server_error',
233
+ // Seit Beleg-Webhooks (Server 2026-11, Stelle wie im Vertrag): ein Ereignis, dessen Modul dem Konto fehlt
234
+ // (`receipt.*` ohne Registrierkasse, `stock.*` u. a. ohne Lager), laesst sich nicht abonnieren; mit `field: 'events'`.
235
+ 'webhook_event_not_available',
221
236
  'idempotency_key_required',
222
237
  'idempotency_conflict',
223
238
  'location_not_found',
@@ -46,6 +46,9 @@ export declare function verifyInventoryWebhookSignature(secret: string | readonl
46
46
  * - `variant_group.created|updated` tragen die Gruppe wie `getVariantGroup`
47
47
  * (seit 1.6.0). Zwei Zustellungen koennen sich ueberholen: den Stand nur
48
48
  * uebernehmen, wenn `data.updatedAt` neuer ist als der gespeicherte.
49
+ * - `receipt.created|cancelled` (Beleg-Webhooks) tragen den Beleg wie
50
+ * `listReceipts` mit `view: 'full'` ([ReceiptCreatedEventData],
51
+ * [ReceiptCancelledEventData]).
49
52
  * - Ein Rumpf, der keine Huelle ist, oder eine Bruchzahl in einer Menge wirft
50
53
  * `KasseneckValidationError` (`scope: 'response'`).
51
54
  *
@@ -17,6 +17,7 @@ import { KasseneckValidationError } from '../client/errors.js';
17
17
  import { verifyWebhookSignature as pruefeSignatur } from '../partner/webhook-signatur.js';
18
18
  import { artikel, bestandGeaendert, objekt, reservierung, unterMindestbestand, variantengruppe } from './lesen.js';
19
19
  import { INVENTORY_WEBHOOK_EVENTS } from './vertrag.js';
20
+ import { vollerBeleg } from '../client/list-receipts.js';
20
21
  export { WEBHOOK_SIGNATURE_HEADER, WEBHOOK_EVENT_HEADER, WEBHOOK_DELIVERY_HEADER, WEBHOOK_TOLERANCE_SEC, } from '../partner/webhook-signatur.js';
21
22
  /**
22
23
  * Prueft die Signatur einer Zustellung. `true` nur, wenn Kopf, Zeitfenster
@@ -63,6 +64,9 @@ function kaputt(grund) {
63
64
  * - `variant_group.created|updated` tragen die Gruppe wie `getVariantGroup`
64
65
  * (seit 1.6.0). Zwei Zustellungen koennen sich ueberholen: den Stand nur
65
66
  * uebernehmen, wenn `data.updatedAt` neuer ist als der gespeicherte.
67
+ * - `receipt.created|cancelled` (Beleg-Webhooks) tragen den Beleg wie
68
+ * `listReceipts` mit `view: 'full'` ([ReceiptCreatedEventData],
69
+ * [ReceiptCancelledEventData]).
66
70
  * - Ein Rumpf, der keine Huelle ist, oder eine Bruchzahl in einer Menge wirft
67
71
  * `KasseneckValidationError` (`scope: 'response'`).
68
72
  *
@@ -107,7 +111,42 @@ export function parseInventoryWebhookEvent(rawBody) {
107
111
  case 'variant_group.created':
108
112
  case 'variant_group.updated':
109
113
  return { ...huelle, type: huelle.type, data: variantengruppe(ort, data) };
114
+ case 'receipt.created':
115
+ return { ...huelle, type: huelle.type, data: belegDaten(data) };
116
+ case 'receipt.cancelled':
117
+ return { ...huelle, type: huelle.type, data: stornoDaten(data) };
110
118
  default:
111
119
  return { ...huelle, type: huelle.type, data: artikel(ort, data) };
112
120
  }
113
121
  }
122
+ /** `data` von `receipt.created`: der Beleg der vollen Ansicht, bei einer gekuerzten Zustellung mit Hinweis. */
123
+ function belegDaten(data) {
124
+ const beleg = objekt(data['receipt']);
125
+ if (!beleg)
126
+ throw kaputt('Ereignis ohne data.receipt');
127
+ return {
128
+ receipt: vollerBeleg(beleg),
129
+ ...(data['truncated'] === true ? { truncated: true } : {}),
130
+ ...(typeof data['hint'] === 'string' ? { hint: data['hint'] } : {}),
131
+ };
132
+ }
133
+ const ganzOderNull = (w) => (typeof w === 'number' && Number.isInteger(w) ? w : null);
134
+ const textOderNull = (w) => (typeof w === 'string' && w !== '' ? w : null);
135
+ /** `data` von `receipt.cancelled`: dazu Bezug, stornierte Positionen und Rueckzahlungen aus dem Storno-Beleg. */
136
+ function stornoDaten(data) {
137
+ const { cancellationOf, cancelledItems, refunds } = data;
138
+ if (cancellationOf !== null && typeof cancellationOf !== 'string')
139
+ throw kaputt('data.cancellationOf ist weder Text noch null');
140
+ if (!Array.isArray(cancelledItems) || cancelledItems.some((x) => !objekt(x)))
141
+ throw kaputt('data.cancelledItems ist keine Liste von Positionen');
142
+ if (!Array.isArray(refunds) || refunds.some((x) => !objekt(x)))
143
+ throw kaputt('data.refunds ist keine Liste von Rueckzahlungen');
144
+ return {
145
+ ...belegDaten(data),
146
+ cancellationOf: cancellationOf === '' ? null : cancellationOf,
147
+ cancelledItems: cancelledItems.map((p) => ({ index: ganzOderNull(p['index']), quantity: ganzOderNull(p['quantity']) })),
148
+ refunds: refunds.map((r) => ({
149
+ refundOf: textOderNull(r['refundOf']), amountCents: ganzOderNull(r['amountCents']), method: textOderNull(r['method']),
150
+ })),
151
+ };
152
+ }
@@ -1,5 +1,5 @@
1
1
  export { type ReceiptItem, type ReceiptItemPayload, type ReceiptItemPayloadRead, toReceiptItemPayload, fromReceiptItemPayload, receiptItemTotalCents, receiptItemIsValid, negateReceiptItem, type TipRecipient, isTipItem, isDiscountItem, isVoucherItem, isVoucherFloatItem, } from './receipt-item.js';
2
- export { type Voucher, type VoucherArticle, type IssuedVoucher, type ReturnIssuedVoucher, type VoucherPayload, toVoucherPayload, fromVoucherPayload, voucherIsValid, isNewFormVoucher, voucherServerFields } from './voucher.js';
2
+ export { type Voucher, type VoucherArticle, type IssuedVoucher, type ReturnIssuedVoucher, type VoucherPayload, toVoucherPayload, fromVoucherPayload, voucherIsValid, isNewFormVoucher, voucherServerFields, type VoucherSource, type LegacyValueVoucherWish, VOUCHER_SOURCES, isExternalVoucher, externalVoucherIsValid, normalizeExternalVoucherNumber, checkExternalVoucherNumber, type ExternalVoucherNumberCheck, EXTERNAL_VOUCHER_NUMBER_MAX, EXTERNAL_VOUCHER_TAXED_WITH_MAX, EXTERNAL_VOUCHER_VAT_RATES_BP, } from './voucher.js';
3
3
  export { type Receipt, type RegistrationInfo, type ReceiptPayload, type ReceiptPayloadRead, toReceiptPayload, fromReceiptPayload, readRegistrationInfo, receiptSubSumCents, receiptSumCents, receiptValueVoucherSign, } from './receipt.js';
4
4
  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';
5
5
  export { type ReceiptPayment, type ReceiptPaymentPayload, type ReceiptPaymentInput, fromReceiptPaymentPayload, toReceiptPaymentPayload, } from './receipt-payment.js';
@@ -1,5 +1,5 @@
1
1
  export { toReceiptItemPayload, fromReceiptItemPayload, receiptItemTotalCents, receiptItemIsValid, negateReceiptItem, isTipItem, isDiscountItem, isVoucherItem, isVoucherFloatItem, } from './receipt-item.js';
2
- export { toVoucherPayload, fromVoucherPayload, voucherIsValid, isNewFormVoucher, voucherServerFields } from './voucher.js';
2
+ export { toVoucherPayload, fromVoucherPayload, voucherIsValid, isNewFormVoucher, voucherServerFields, VOUCHER_SOURCES, isExternalVoucher, externalVoucherIsValid, normalizeExternalVoucherNumber, checkExternalVoucherNumber, EXTERNAL_VOUCHER_NUMBER_MAX, EXTERNAL_VOUCHER_TAXED_WITH_MAX, EXTERNAL_VOUCHER_VAT_RATES_BP, } from './voucher.js';
3
3
  export { toReceiptPayload, fromReceiptPayload, readRegistrationInfo, receiptSubSumCents, receiptSumCents, receiptValueVoucherSign, } from './receipt.js';
4
4
  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';
5
5
  export { fromReceiptPaymentPayload, toReceiptPaymentPayload, } from './receipt-payment.js';
@@ -12,7 +12,22 @@ import { VoucherAction, VoucherType } from '../enums/index.js';
12
12
  */
13
13
  export interface Voucher {
14
14
  name?: string;
15
+ /**
16
+ * Code eines eigenen Gutscheins (Einloesung, Auszahlung). Am gelesenen Eintrag die Maske. Ein Wunsch der
17
+ * Altform mit frei getipptem Code ist veraltet ([LegacyValueVoucherWish]).
18
+ */
15
19
  code?: string;
20
+ /**
21
+ * Fremdgutschein (Server 2026-11): `external` = Gutschein eines anderen Systems (Warenwirtschaft, Webshop) mit
22
+ * seiner Nummer in [number]. Kein Dokument bei Kasseneck, kein Saldo, keine Pruefung: Art, Satz und Betrag sagt
23
+ * der Betrieb. Fehlt bei eigenen Gutscheinen.
24
+ */
25
+ source?: VoucherSource | string;
26
+ /**
27
+ * Nummer des Fremdgutscheins (nur mit `source: 'external'`): nach [normalizeExternalVoucherNumber] 1 bis 40
28
+ * Zeichen aus `A–Z a–z 0–9 - _ . /`; ein eigener Gutscheincode ist keine Fremdnummer. Steht voll am Bon.
29
+ */
30
+ number?: string;
16
31
  action: VoucherAction | string;
17
32
  /**
18
33
  * Art des Gutscheins. Beim Verkauf ueber eine Sorte die Art der Sorte
@@ -119,6 +134,8 @@ export interface VoucherArticle {
119
134
  export interface VoucherPayload {
120
135
  name?: string | null;
121
136
  code?: string | null;
137
+ source?: string;
138
+ number?: string;
122
139
  action: string;
123
140
  type: string;
124
141
  value?: number | null;
@@ -142,16 +159,35 @@ export interface VoucherPayload {
142
159
  exempt?: boolean;
143
160
  zeroRateBucket?: boolean;
144
161
  }
162
+ /**
163
+ * Wunsch der Altform: Wertgutschein mit frei getipptem Code (`{ action, type: 'value', code, valueCents }`).
164
+ * Nur als Typ fuer Aufrufer, die ihn noch senden; ein gelesener Beleg ist davon nicht betroffen.
165
+ *
166
+ * @deprecated Server 2026-11: der Weg bleibt gueltig, die Antwort traegt `deprecation`
167
+ * ([ReceiptWithCompany.deprecation]). Der Code wird nicht geprueft, steuerlich ist das ein fremder
168
+ * Mehrzweckgutschein. Einen Gutschein eines anderen Systems als Fremdgutschein senden: `{ source: 'external',
169
+ * action, type: 'multi_purpose', number, amountCents }`; eigene Gutscheine ueber eine Sorte (`typeId`)
170
+ * verkaufen und mit ihrem Code einloesen.
171
+ */
172
+ export type LegacyValueVoucherWish = Voucher & {
173
+ type: 'value';
174
+ code: string;
175
+ };
145
176
  /** Arten der neuen Gutscheinform (die Altwerte sind `value` und `promo`). */
146
177
  export declare const NEUE_GUTSCHEINARTEN: readonly string[];
178
+ /** Herkunft eines Gutscheins: `external` = Fremdgutschein (Katalog `GUTSCHEIN_QUELLE`). */
179
+ export type VoucherSource = 'external';
180
+ export declare const VOUCHER_SOURCES: readonly VoucherSource[];
181
+ /** Fremdgutschein (`source: 'external'`)? Zwilling von `gutschein-beleg.istFremd`. */
182
+ export declare function isExternalVoucher(voucher: Pick<Voucher, 'source'>): boolean;
147
183
  /** Gehoert der Gutschein zur neuen Form (Art, Aktion `payout` oder Verkauf ueber eine Sorte ohne Art)? */
148
- export declare function isNewFormVoucher(voucher: Pick<Voucher, 'type' | 'action' | 'typeId'>): boolean;
184
+ export declare function isNewFormVoucher(voucher: Pick<Voucher, 'type' | 'action' | 'typeId'> & Pick<Voucher, 'source'>): boolean;
149
185
  /**
150
186
  * Wert-Verkauf: ein Mehrzweck- oder Einzweckgutschein wird verkauft (mit Art
151
187
  * oder nur ueber die Sorte). Paketintern: Zahlbetrag und Pruefung vor dem
152
188
  * Senden entscheiden daran, ob eine Sorte noetig ist.
153
189
  */
154
- export declare function istWertVerkauf(voucher: Pick<Voucher, 'type' | 'action' | 'typeId'>): boolean;
190
+ export declare function istWertVerkauf(voucher: Pick<Voucher, 'type' | 'action' | 'typeId'> & Pick<Voucher, 'source'>): boolean;
155
191
  /**
156
192
  * Felder, die nur der Server setzt; an einem Wunsch sind sie `voucher_invalid`.
157
193
  * Sortenname und Auszahlung friert der Server beim Verkauf ein (Stufe 4b).
@@ -175,3 +211,43 @@ export declare function fromVoucherPayload(payload: VoucherPayload): Voucher;
175
211
  * Stufe 4b antwortet darauf `voucher_type_required`). Paketintern.
176
212
  */
177
213
  export declare function wunschFormGueltig(v: Voucher, sorteNoetig: boolean): boolean;
214
+ /** Hoechstlaenge der Nummer eines Fremdgutscheins (nach dem Abschneiden des Rands). */
215
+ export declare const EXTERNAL_VOUCHER_NUMBER_MAX = 40;
216
+ /** Hoechstlaenge von `taxedWith` (Vermerk, mit welchem Beleg im fremden System der Einzweckgutschein versteuert ist). */
217
+ export declare const EXTERNAL_VOUCHER_TAXED_WITH_MAX = 40;
218
+ /**
219
+ * Saetze, mit denen ein fremder Einzweckgutschein verkauft sein kann (Basispunkte): die Saetze der Kasse
220
+ * (20, 10, 13, 19, 4,9 %) und 0 = befreit verkauft (Kleinunternehmer).
221
+ */
222
+ export declare const EXTERNAL_VOUCHER_VAT_RATES_BP: readonly number[];
223
+ /**
224
+ * Nummer eines Fremdgutscheins in der Form, mit der der Server sie speichert und druckt
225
+ * (`gutschein-core.normiereFremdnummer`): Rand weg, **keine** Unicode-Normalisierung, Gross-/Kleinschreibung
226
+ * bleibt; dann 1 bis 40 Zeichen aus `A–Z a–z 0–9 - _ . /`. Sonst `null` (`external_voucher_number_invalid`).
227
+ * Einen eigenen Gutscheincode erkennt erst [checkExternalVoucherNumber].
228
+ */
229
+ export declare function normalizeExternalVoucherNumber(text: unknown): string | null;
230
+ /** Ergebnis von [checkExternalVoucherNumber]: die Nummer wie gespeichert, oder der Fehlercode des Servers. */
231
+ export type ExternalVoucherNumberCheck = {
232
+ ok: true;
233
+ number: string;
234
+ } | {
235
+ ok: false;
236
+ code: 'external_voucher_number_is_own_code' | 'external_voucher_number_invalid';
237
+ };
238
+ /**
239
+ * Prueft eine Fremdnummer in der Reihenfolge des Servers (`gutschein-beleg.pruefeFremd`): zuerst, ob sie ein
240
+ * gueltiger eigener Gutscheincode ist (12 Zeichen mit Pruefzeichen, in jeder Schreibweise der Kasse, auch mit `.`, `_`
241
+ * oder `/` als Trenner) – dann
242
+ * `external_voucher_number_is_own_code`, der Gutschein gehoert als eigener eingeloest –, danach die Form.
243
+ */
244
+ export declare function checkExternalVoucherNumber(text: unknown): ExternalVoucherNumberCheck;
245
+ /**
246
+ * Ist der Fremdgutschein sendbar? Die Form wie `gutschein-beleg.pruefeFremd` (ohne die Freigabe des Kontos, die
247
+ * kennt nur der Server bzw. `PosVoucherSettings.externalVouchers`): Aktion `sell`/`redeem`/`payout`, Art
248
+ * `multi_purpose`/`single_purpose`, gueltige Nummer (kein eigener Code), Betrag 1 bis 1.000.000 Cent; Einzweck mit
249
+ * einem Satz aus [EXTERNAL_VOUCHER_VAT_RATES_BP], Mehrzweck ohne; `taxedWith` nur bei Einzweck-Einloesung bzw.
250
+ * -Auszahlung (1 bis 40 Zeichen ohne Steuerzeichen); Auszahlung mit Grund (1 bis 200 Zeichen). Felder eigener
251
+ * Gutscheine (Code, Sorte, Artikel, Menge, Positionen) und Serverfelder nie.
252
+ */
253
+ export declare function externalVoucherIsValid(voucher: Voucher): boolean;
@@ -1,4 +1,5 @@
1
1
  import { VoucherAction, VoucherType } from '../enums/index.js';
2
+ import { VoucherCode } from '@kreiseck/validator';
2
3
  import { euroToCents } from '../money.js';
3
4
  import { readEnumKey, requireEnumKey } from './enum-payload.js';
4
5
  /** Arten der neuen Gutscheinform (die Altwerte sind `value` und `promo`). */
@@ -8,6 +9,11 @@ export const NEUE_GUTSCHEINARTEN = [
8
9
  VoucherType.service,
9
10
  VoucherType.promotion,
10
11
  ];
12
+ export const VOUCHER_SOURCES = Object.freeze(['external']);
13
+ /** Fremdgutschein (`source: 'external'`)? Zwilling von `gutschein-beleg.istFremd`. */
14
+ export function isExternalVoucher(voucher) {
15
+ return voucher.source === 'external';
16
+ }
11
17
  /**
12
18
  * Verkauf ueber eine Sorte ohne Art (`typeId` ohne `type`): die Art kommt aus
13
19
  * der Sorte. Zwilling von `gutschein-beleg.istSortenVerkauf`.
@@ -17,7 +23,8 @@ function istSortenVerkaufOhneArt(voucher) {
17
23
  }
18
24
  /** Gehoert der Gutschein zur neuen Form (Art, Aktion `payout` oder Verkauf ueber eine Sorte ohne Art)? */
19
25
  export function isNewFormVoucher(voucher) {
20
- return NEUE_GUTSCHEINARTEN.includes(voucher.type) || voucher.action === VoucherAction.payout || istSortenVerkaufOhneArt(voucher);
26
+ return NEUE_GUTSCHEINARTEN.includes(voucher.type) || voucher.action === VoucherAction.payout || istSortenVerkaufOhneArt(voucher)
27
+ || isExternalVoucher(voucher);
21
28
  }
22
29
  /**
23
30
  * Wert-Verkauf: ein Mehrzweck- oder Einzweckgutschein wird verkauft (mit Art
@@ -25,7 +32,7 @@ export function isNewFormVoucher(voucher) {
25
32
  * Senden entscheiden daran, ob eine Sorte noetig ist.
26
33
  */
27
34
  export function istWertVerkauf(voucher) {
28
- return voucher.action === VoucherAction.sell
35
+ return !isExternalVoucher(voucher) && voucher.action === VoucherAction.sell
29
36
  && (voucher.type === VoucherType.multi_purpose || voucher.type === VoucherType.single_purpose || istSortenVerkaufOhneArt(voucher));
30
37
  }
31
38
  /**
@@ -38,7 +45,7 @@ export function voucherServerFields(voucher) {
38
45
  return GUTSCHEIN_SERVERFELDER.filter((feld) => voucher[feld] != null);
39
46
  }
40
47
  const NEUE_FELDER = [
41
- 'amountCents', 'articleId', 'quantity', 'positions', 'reason', 'typeId', 'typeName', 'payout', 'voucherType', 'voucherId', 'codeSuffix',
48
+ 'source', 'number', 'amountCents', 'articleId', 'quantity', 'positions', 'reason', 'typeId', 'typeName', 'payout', 'voucherType', 'voucherId', 'codeSuffix',
42
49
  'vatRateBp', 'article', 'balanceAfterCents', 'remainingQuantityAfter', 'taxedWith', 'exempt', 'zeroRateBucket', 'fromReturn',
43
50
  ];
44
51
  export function toVoucherPayload(voucher) {
@@ -71,6 +78,8 @@ export function toVoucherPayload(voucher) {
71
78
  * gesetzter Wert muss positiv sein.
72
79
  */
73
80
  export function voucherIsValid(voucher) {
81
+ if (isExternalVoucher(voucher))
82
+ return externalVoucherIsValid(voucher);
74
83
  if (isNewFormVoucher(voucher))
75
84
  return newFormVoucherIsValid(voucher);
76
85
  if (voucher.type === VoucherType.value && voucher.valueCents == null) {
@@ -160,13 +169,21 @@ function newFormVoucherIsValid(v) {
160
169
  * Stufe 4b antwortet darauf `voucher_type_required`). Paketintern.
161
170
  */
162
171
  export function wunschFormGueltig(v, sorteNoetig) {
172
+ if (isExternalVoucher(v))
173
+ return externalVoucherIsValid(v);
163
174
  if (voucherServerFields(v).length > 0)
164
175
  return false;
165
176
  const r = v;
166
- for (const feld of ['vatRateBp', 'article', 'balanceAfterCents', 'remainingQuantityAfter', 'taxedWith', 'exempt']) {
177
+ for (const feld of ['article', 'balanceAfterCents', 'remainingQuantityAfter', 'exempt']) {
167
178
  if (r[feld] != null)
168
179
  return false;
169
180
  }
181
+ // Felder nur des Fremdgutscheins (gutschein-beleg.NUR_BEI_FREMD): der Server weist sie an einem eigenen Wunsch
182
+ // schon gesendet ab, auch als `null` (`voucher_invalid`); eine andere Herkunft als `external` gibt es nicht.
183
+ for (const feld of ['number', 'taxedWith', 'vatRateBp', 'source']) {
184
+ if (r[feld] !== undefined)
185
+ return false;
186
+ }
170
187
  if (v.valueCents != null)
171
188
  return false;
172
189
  // Die Sorte gehoert nur an einen Wert-Verkauf (Server: sorteId sonst voucher_invalid).
@@ -210,3 +227,104 @@ export function wunschFormGueltig(v, sorteNoetig) {
210
227
  // Altart mit neuer Aktion (payout + value/promo): nicht sendbar.
211
228
  return false;
212
229
  }
230
+ // ---- Fremdgutscheine (Server 2026-11) -------------------------------------------
231
+ /**
232
+ * Rand einer Fremdnummer (Zwilling von `gutschein-core.FREMD_RAND`): ASCII-Leerraum und die Unicode-Leerzeichen,
233
+ * die beim Kopieren aus Fremdsystemen mitkommen. Bewusst ohne U+0085 (NEL): ein Steuerzeichen, das nie still
234
+ * verschwindet, sondern die Nummer ungueltig macht.
235
+ */
236
+ const FREMD_RAND = '\\t\\n\\v\\f\\r \\u00A0\\u1680\\u2000-\\u200A\\u2028\\u2029\\u202F\\u205F\\u3000\\uFEFF';
237
+ const FREMD_RAND_MUSTER = new RegExp(`^[${FREMD_RAND}]+|[${FREMD_RAND}]+$`, 'g');
238
+ const FREMD_NUMMER_MUSTER = /^[A-Za-z0-9\-_./]{1,40}$/;
239
+ /** Hoechstlaenge der Nummer eines Fremdgutscheins (nach dem Abschneiden des Rands). */
240
+ export const EXTERNAL_VOUCHER_NUMBER_MAX = 40;
241
+ /** Hoechstlaenge von `taxedWith` (Vermerk, mit welchem Beleg im fremden System der Einzweckgutschein versteuert ist). */
242
+ export const EXTERNAL_VOUCHER_TAXED_WITH_MAX = 40;
243
+ /**
244
+ * Saetze, mit denen ein fremder Einzweckgutschein verkauft sein kann (Basispunkte): die Saetze der Kasse
245
+ * (20, 10, 13, 19, 4,9 %) und 0 = befreit verkauft (Kleinunternehmer).
246
+ */
247
+ export const EXTERNAL_VOUCHER_VAT_RATES_BP = Object.freeze([2000, 1000, 1300, 1900, 490, 0]);
248
+ /**
249
+ * Nummer eines Fremdgutscheins in der Form, mit der der Server sie speichert und druckt
250
+ * (`gutschein-core.normiereFremdnummer`): Rand weg, **keine** Unicode-Normalisierung, Gross-/Kleinschreibung
251
+ * bleibt; dann 1 bis 40 Zeichen aus `A–Z a–z 0–9 - _ . /`. Sonst `null` (`external_voucher_number_invalid`).
252
+ * Einen eigenen Gutscheincode erkennt erst [checkExternalVoucherNumber].
253
+ */
254
+ export function normalizeExternalVoucherNumber(text) {
255
+ if (typeof text !== 'string')
256
+ return null;
257
+ const n = text.replace(FREMD_RAND_MUSTER, '');
258
+ return FREMD_NUMMER_MUSTER.test(n) ? n : null;
259
+ }
260
+ /**
261
+ * Prueft eine Fremdnummer in der Reihenfolge des Servers (`gutschein-beleg.pruefeFremd`): zuerst, ob sie ein
262
+ * gueltiger eigener Gutscheincode ist (12 Zeichen mit Pruefzeichen, in jeder Schreibweise der Kasse, auch mit `.`, `_`
263
+ * oder `/` als Trenner) – dann
264
+ * `external_voucher_number_is_own_code`, der Gutschein gehoert als eigener eingeloest –, danach die Form.
265
+ */
266
+ export function checkExternalVoucherNumber(text) {
267
+ // `.`, `_` und `/` zwischen den Gruppen liest die Pruefung wie `-` (Zwilling von `gutschein-core.istEigenerCode`):
268
+ // `7148.FGQA.935K` ist der eigene Code. Die Nummer selbst bleibt, wie sie kam.
269
+ if (typeof text === 'string' && VoucherCode.validate(text.replace(/[._/]/g, '-')).ok)
270
+ return { ok: false, code: 'external_voucher_number_is_own_code' };
271
+ const number = normalizeExternalVoucherNumber(text);
272
+ return number === null ? { ok: false, code: 'external_voucher_number_invalid' } : { ok: true, number };
273
+ }
274
+ /** Steuer- und Formatzeichen (`gutschein-core.STEUERZEICHEN`): nie in `taxedWith`. */
275
+ const STEUERZEICHEN = /[\p{Cc}\p{Cf}]/u;
276
+ /**
277
+ * Ist der Fremdgutschein sendbar? Die Form wie `gutschein-beleg.pruefeFremd` (ohne die Freigabe des Kontos, die
278
+ * kennt nur der Server bzw. `PosVoucherSettings.externalVouchers`): Aktion `sell`/`redeem`/`payout`, Art
279
+ * `multi_purpose`/`single_purpose`, gueltige Nummer (kein eigener Code), Betrag 1 bis 1.000.000 Cent; Einzweck mit
280
+ * einem Satz aus [EXTERNAL_VOUCHER_VAT_RATES_BP], Mehrzweck ohne; `taxedWith` nur bei Einzweck-Einloesung bzw.
281
+ * -Auszahlung (1 bis 40 Zeichen ohne Steuerzeichen); Auszahlung mit Grund (1 bis 200 Zeichen). Felder eigener
282
+ * Gutscheine (Code, Sorte, Artikel, Menge, Positionen) und Serverfelder nie.
283
+ */
284
+ export function externalVoucherIsValid(voucher) {
285
+ const v = voucher;
286
+ if (!isExternalVoucher(v))
287
+ return false;
288
+ if (voucherServerFields(v).length > 0)
289
+ return false;
290
+ const r = v;
291
+ // gutschein-beleg.NICHT_BEI_FREMD (gesendet heisst voucher_invalid, auch als null).
292
+ for (const feld of ['code', 'typeId', 'articleId', 'article', 'quantity', 'positions']) {
293
+ if (r[feld] !== undefined)
294
+ return false;
295
+ }
296
+ for (const feld of ['balanceAfterCents', 'remainingQuantityAfter', 'exempt']) {
297
+ if (r[feld] != null)
298
+ return false;
299
+ }
300
+ if (v.valueCents != null)
301
+ return false;
302
+ if (v.action !== VoucherAction.sell && v.action !== VoucherAction.redeem && v.action !== VoucherAction.payout)
303
+ return false;
304
+ if (v.type !== VoucherType.multi_purpose && v.type !== VoucherType.single_purpose)
305
+ return false;
306
+ if (!checkExternalVoucherNumber(v.number).ok)
307
+ return false;
308
+ if (!istCent(v.amountCents))
309
+ return false;
310
+ if (v.type === VoucherType.single_purpose) {
311
+ if (!(typeof v.vatRateBp === 'number' && EXTERNAL_VOUCHER_VAT_RATES_BP.includes(v.vatRateBp)))
312
+ return false;
313
+ }
314
+ else if (v.vatRateBp != null) {
315
+ return false;
316
+ }
317
+ if (v.taxedWith != null) {
318
+ if (v.type !== VoucherType.single_purpose || v.action === VoucherAction.sell)
319
+ return false;
320
+ const t = typeof v.taxedWith === 'string' ? v.taxedWith.trim() : '';
321
+ if (t.length < 1 || t.length > EXTERNAL_VOUCHER_TAXED_WITH_MAX || STEUERZEICHEN.test(t))
322
+ return false;
323
+ }
324
+ if (v.action === VoucherAction.payout) {
325
+ const g = typeof v.reason === 'string' ? v.reason.trim() : '';
326
+ if (g.length < 1 || g.length > MAX_GRUND)
327
+ return false;
328
+ }
329
+ return true;
330
+ }
@@ -36,6 +36,14 @@ export declare const VOUCHER_TYPE_KINDS: readonly VoucherTypeKind[];
36
36
  export declare const VOUCHER_AMOUNT_MODES: readonly ('free' | 'fixed')[];
37
37
  /** Gueltigkeit einer Sorte: unbefristet oder N Jahre (das Muster der Sorte, nicht das eines Gutscheins). */
38
38
  export declare const VOUCHER_TYPE_VALIDITY_PATTERNS: readonly ('unlimited' | 'years')[];
39
+ /**
40
+ * Freigabe fuer Fremdgutscheine des Kontos (`vouchers.externalVouchers`): `off` keine, `multi_purpose` nur
41
+ * Wertgutscheine (Mehrzweck) eines anderen Systems, `all` dazu Einzweckgutscheine. Die Kasse zeigt den Weg
42
+ * „Fremdgutschein“ nur ab `multi_purpose`, die Art Einzweck nur bei `all`; der Server prueft dieselbe Freigabe
43
+ * (`external_voucher_not_enabled`, `external_voucher_type_not_enabled`). Die Test-Umgebung ist immer `all`.
44
+ */
45
+ export type PosExternalVouchers = 'off' | 'multi_purpose' | 'all';
46
+ export declare const EXTERNAL_VOUCHERS: readonly PosExternalVouchers[];
39
47
  /** Der Artikel eines Dienstleistungsgutscheins. */
40
48
  export interface VoucherArticle {
41
49
  id: string;
@@ -158,6 +166,11 @@ export interface PosVoucherSettings {
158
166
  * passende Sorte). Fehlt sie, zeigt die Kasse „Als Gutschein“ nicht.
159
167
  */
160
168
  returnType?: PosVoucherReturnType;
169
+ /**
170
+ * Freigabe fuer Fremdgutscheine (Server 2026-11, [EXTERNAL_VOUCHERS]). Der Leser setzt sie immer; fehlt sie
171
+ * am Draht (aelterer Server) oder ist sie unbekannt, gilt `off`.
172
+ */
173
+ externalVouchers?: PosExternalVouchers;
161
174
  }
162
175
  /** Sorte fuer Rueckgaben (`vouchers.returnType`): Kennung und Name. */
163
176
  export interface PosVoucherReturnType {
@@ -13,10 +13,12 @@ export const VOUCHER_TYPE_KINDS = Object.freeze(['multi_purpose', 'single_purpos
13
13
  export const VOUCHER_AMOUNT_MODES = Object.freeze(['free', 'fixed']);
14
14
  /** Gueltigkeit einer Sorte: unbefristet oder N Jahre (das Muster der Sorte, nicht das eines Gutscheins). */
15
15
  export const VOUCHER_TYPE_VALIDITY_PATTERNS = Object.freeze(['unlimited', 'years']);
16
+ export const EXTERNAL_VOUCHERS = Object.freeze(['off', 'multi_purpose', 'all']);
16
17
  /** Ohne Block `vouchers` (alter Server, Konto ohne Schalter): Verkaufen ist aus. */
17
18
  export const VOUCHER_SETTINGS_DEFAULTS = Object.freeze({
18
19
  sale: false, valueVoucherType: null, vatRateBp: null,
19
20
  typeSale: false, types: Object.freeze([]), serviceArticles: false, labelDefault: null,
21
+ externalVouchers: 'off',
20
22
  });
21
23
  /**
22
24
  * Block `vouchers` einer Einstellungs-Antwort, geschlossen im Zweifel: ist
@@ -77,6 +79,8 @@ export function posVoucherSettingsFromWire(block) {
77
79
  serviceArticles: leistung,
78
80
  labelDefault: vorlageVomDraht(b['labelDefault']),
79
81
  ...rueckgabeSorteVomDraht(b['returnType']),
82
+ // Unbekannt oder fehlend: aus (schliesst nur den Fremdgutschein, nie den Block).
83
+ externalVouchers: EXTERNAL_VOUCHERS.includes(b['externalVouchers']) ? b['externalVouchers'] : 'off',
80
84
  };
81
85
  }
82
86
  /** `vouchers.returnType`, nur stimmig (Kennung wie eine Sorte, Name als Text); sonst fehlt es. */
@@ -23,7 +23,7 @@ export { STOCK_LOCATION_TYPES, type StockLocationType, type StockLocation, type
23
23
  export { type ListMyStocktakesOptions, type ListMyStocktakeItemsOptions, type ListMyStocktakeCountsOptions, type RecordMyStocktakeCountOptions, type VoidMyStocktakeCountOptions, listMyStocktakes, listMyStocktakeItems, listMyStocktakeCounts, recordMyStocktakeCount, voidMyStocktakeCount, parseQuantityMilli, } from './inventur.js';
24
24
  export type { Stocktake, StocktakeItem, StocktakeCount, StocktakeCountResult, StocktakeItemPage, StocktakeCountPage, StocktakeActor, StocktakeProgress, StocktakeReview, StocktakeRecount, StocktakeScope, } from '../inventory/typen.js';
25
25
  export type { StocktakeStatus } from '../inventory/vertrag.js';
26
- export { VOUCHER_KINDS, VOUCHER_STATUSES, checkVoucher, reprintVoucherLabel, VOUCHER_SETTINGS_DEFAULTS, posVoucherSettingsFromWire, VOUCHER_PAYOUTS, VOUCHER_TYPE_KINDS, VOUCHER_AMOUNT_MODES, VOUCHER_TYPE_VALIDITY_PATTERNS, type VoucherKind, type VoucherStatus, type VoucherValidity, type VoucherArticle, type VoucherCheck, type PosVoucherSettings, type PosVoucherReturnType, type VoucherPayout, type VoucherTypeKind, type PosVoucherType, type VoucherLabelTemplate, } from './gutschein.js';
26
+ export { VOUCHER_KINDS, VOUCHER_STATUSES, checkVoucher, reprintVoucherLabel, VOUCHER_SETTINGS_DEFAULTS, posVoucherSettingsFromWire, VOUCHER_PAYOUTS, VOUCHER_TYPE_KINDS, VOUCHER_AMOUNT_MODES, VOUCHER_TYPE_VALIDITY_PATTERNS, EXTERNAL_VOUCHERS, type PosExternalVouchers, type VoucherKind, type VoucherStatus, type VoucherValidity, type VoucherArticle, type VoucherCheck, type PosVoucherSettings, type PosVoucherReturnType, type VoucherPayout, type VoucherTypeKind, type PosVoucherType, type VoucherLabelTemplate, } from './gutschein.js';
27
27
  export { type GetMyDrawerStateOptions, type OpenMyShiftOptions, type RecordMyCashMovementOptions, type DrawerOpeningEntry, type LogMyDrawerOpeningsOptions, type GetMyShiftReportOptions, type TipPayout, type CloseMyShiftOptions, type AfterCountOption, type RecordMyShiftCountOptions, getMyDrawerState, openMyShift, recordMyCashMovement, logMyDrawerOpenings, getMyShiftReport, closeMyShift, recordMyShiftCount, sumDenominations, parseCentsAllowZero, newIdempotencyKey, shiftTipLines, durationText, type ShiftTipLine, type ShiftTipLineKey, } from './schicht.js';
28
28
  export { EUR_DENOMINATIONS, MOVEMENT_TYPES, MANUAL_MOVEMENT_TYPES, CASH_LOCATIONS, OPENING_REASONS, MANUAL_OPENING_REASONS, SHIFT_RECEIPT_KINDS, AFTER_COUNT_TYPES, type AfterCountType, type AfterCount, EXPECTED_PART_KEYS, DIFFERENCE_PART_TYPES, type ExpectedPartKey, type ShiftExpectedPart, type DifferencePartType, type ShiftDifferencePart, type LastShift, type ShiftCountResult, type EurDenomination, type MovementType, type ManualMovementType, type CashLocation, type OpeningReason, type ManualOpeningReason, type ShiftReceiptKind, type ShiftStatus, type ShiftActorRole, type Denominations, type ShiftActor, type DrawerInfo, type DrawerRights, type NonCashAmount, type ShiftTipTotals, type ShiftTip, type ShiftOwnerTip, type ShiftRunningTotals, type ShiftReconciliation, type Shift, type TipClaim, type DrawerOpening, type DrawerState, type CashMovement, type ShiftReceiptHeader, type ShiftReceiptMovement, type ShiftReceiptTip, type ShiftSummaryReceipt, type CashMovementReceipt, type ShiftReceipt, type OpenShiftResult, type CashMovementResult, type DrawerOpeningsResult, type ShiftReport, type CloseShiftResult, } from './schicht-typen.js';
29
29
  export { type ShiftReceiptLayoutOptions, shiftReceiptLayout, cashMovementLayout } from '../receipt/shift-sheet.js';
@@ -29,7 +29,7 @@ export { reportConnectState } from './connect-bestand.js';
29
29
  export { STOCK_LOCATION_TYPES, listMyStockLocations, listMyStock, setMyCashregisterStockLocation, } from './lager.js';
30
30
  export { listMyStocktakes, listMyStocktakeItems, listMyStocktakeCounts, recordMyStocktakeCount, voidMyStocktakeCount, parseQuantityMilli, } from './inventur.js';
31
31
  // Gutschein pruefen und Etikett nachdrucken an der Kasse; Gutschein-Sorten (Stufe 4b, 1.17.0).
32
- export { VOUCHER_KINDS, VOUCHER_STATUSES, checkVoucher, reprintVoucherLabel, VOUCHER_SETTINGS_DEFAULTS, posVoucherSettingsFromWire, VOUCHER_PAYOUTS, VOUCHER_TYPE_KINDS, VOUCHER_AMOUNT_MODES, VOUCHER_TYPE_VALIDITY_PATTERNS, } from './gutschein.js';
32
+ export { VOUCHER_KINDS, VOUCHER_STATUSES, checkVoucher, reprintVoucherLabel, VOUCHER_SETTINGS_DEFAULTS, posVoucherSettingsFromWire, VOUCHER_PAYOUTS, VOUCHER_TYPE_KINDS, VOUCHER_AMOUNT_MODES, VOUCHER_TYPE_VALIDITY_PATTERNS, EXTERNAL_VOUCHERS, } from './gutschein.js';
33
33
  // Schicht, Kassenstand und Lade-Protokoll (1.9.0): Aufrufe, Kataloge, Helfer, Bons.
34
34
  export { getMyDrawerState, openMyShift, recordMyCashMovement, logMyDrawerOpenings, getMyShiftReport, closeMyShift, recordMyShiftCount, sumDenominations, parseCentsAllowZero, newIdempotencyKey, shiftTipLines, durationText, } from './schicht.js';
35
35
  export { EUR_DENOMINATIONS, MOVEMENT_TYPES, MANUAL_MOVEMENT_TYPES, CASH_LOCATIONS, OPENING_REASONS, MANUAL_OPENING_REASONS, SHIFT_RECEIPT_KINDS, AFTER_COUNT_TYPES, EXPECTED_PART_KEYS, DIFFERENCE_PART_TYPES, } from './schicht-typen.js';
@@ -414,6 +414,21 @@ declare const MELDUNGEN_ROH: {
414
414
  readonly 'voucher_error.payout_not_allowed': {
415
415
  readonly text: "Dieser Gutschein kann nicht ausgezahlt werden.";
416
416
  };
417
+ readonly 'voucher_error.external_not_enabled': {
418
+ readonly text: "Fremde Gutscheine sind für dieses Konto nicht freigegeben.";
419
+ };
420
+ readonly 'voucher_error.external_type_not_enabled': {
421
+ readonly text: "Fremde Einzweckgutscheine sind für dieses Konto nicht freigegeben.";
422
+ };
423
+ readonly 'voucher_error.external_number_invalid': {
424
+ readonly text: "Gutscheinnummer prüfen: 1 bis 40 Zeichen, nur Buchstaben, Ziffern und - _ . / sind erlaubt.";
425
+ };
426
+ readonly 'voucher_error.external_number_is_own_code': {
427
+ readonly text: "Das ist ein eigener Gutscheincode. Bitte als eigenen Gutschein einlösen.";
428
+ };
429
+ readonly 'voucher_error.external_duplicate': {
430
+ readonly text: "Diese Gutscheinnummer steht schon auf dem Beleg.";
431
+ };
417
432
  readonly 'voucher.type_changed': {
418
433
  readonly text: "Diese Gutschein-Sorte hat sich geändert. Bitte die Zeile entfernen und die Kachel neu antippen.";
419
434
  };
@@ -1210,6 +1225,11 @@ export declare const VOUCHER_ERROR_MESSAGES: {
1210
1225
  readonly voucher_amount_mismatch: "voucher_error.amount_mismatch";
1211
1226
  readonly voucher_service_not_allowed: "voucher_error.service_not_allowed";
1212
1227
  readonly voucher_payout_not_allowed: "voucher_error.payout_not_allowed";
1228
+ readonly external_voucher_not_enabled: "voucher_error.external_not_enabled";
1229
+ readonly external_voucher_type_not_enabled: "voucher_error.external_type_not_enabled";
1230
+ readonly external_voucher_number_invalid: "voucher_error.external_number_invalid";
1231
+ readonly external_voucher_number_is_own_code: "voucher_error.external_number_is_own_code";
1232
+ readonly external_voucher_duplicate: "voucher_error.external_duplicate";
1213
1233
  };
1214
1234
  export type VoucherMessageCode = keyof typeof VOUCHER_ERROR_MESSAGES;
1215
1235
  /** Der Satz zu einem Gutschein-`code`; `undefined` für jeden anderen Code. */