@kreiseck/kasseneck-api 0.15.0 → 0.17.0

package/dist/esm/rechnung/vertrag.js

@@ -30,6 +30,8 @@ export const RECHNUNG_AUFRUFE = [
     'listInvoices',
     'getInvoicePdf',
     'getInvoiceXml',
+    'getInvoiceSetupStatus',
+    'listBrands',
 ];
 /**
  * Stabile Fehlercodes. Das Fremdsystem verzweigt am Code, der Text darf sich
@@ -51,6 +53,10 @@ export const INVOICE_ERROR_CODES = [
     'partial_credit_exists',
     'credit_exceeds_invoice',
     'einvoice_incomplete',
+    'invoice_api_not_enabled',
+    'invoice_setup_incomplete',
+    'language_not_allowed',
+    'brand_not_found',
 ];
 /** Gruende einer Gutschrift. Der Server druckt den deutschen Anzeigetext. */
 export const CREDIT_NOTE_REASONS = [
@@ -67,6 +73,153 @@ export const CUSTOMER_TYPES = ['private', 'company'];
 export const INVOICE_LIST_STATUS = ['final', 'paid', 'cancelled', 'open', 'overdue'];
 export const DOC_TYPES = ['RE', 'GU'];
 export const EINVOICE_FORMATS = ['ubl', 'cii'];
+/**
+ * Sprachen einer Rechnung. Die Sprache wird beim Festschreiben eingefroren;
+ * fehlt sie an Kunde oder Rechnung, gilt `de`. Behoerden bekommen immer `de`
+ * (`language_not_allowed`). Datum und Betraege bleiben in jeder Sprache
+ * oesterreichisch formatiert.
+ */
+export const INVOICE_LANGUAGES = ['de', 'en'];
+/**
+ * Einheiten einer Position. Die API nimmt nur diese Schluessel an; gedruckt
+ * wird das Kuerzel in der Sprache der Rechnung (`RECHNUNG_TEXTE`,
+ * `einheit.<schluessel>`), die E-Rechnung fuehrt den UN/ECE-Code
+ * (`RECHNUNG_EINHEITEN_CODES`). Ohne Angabe gilt `piece`.
+ */
+export const INVOICE_UNITS = [
+    'piece',
+    'pair',
+    'set',
+    'dozen',
+    'second',
+    'minute',
+    'hour',
+    'day',
+    'night',
+    'week',
+    'month',
+    'quarter',
+    'half_year',
+    'year',
+    'milligram',
+    'gram',
+    'kilogram',
+    'tonne',
+    'millimetre',
+    'centimetre',
+    'metre',
+    'running_metre',
+    'kilometre',
+    'square_metre',
+    'hectare',
+    'millilitre',
+    'litre',
+    'cubic_metre',
+    'kilowatt_hour',
+    'megawatt_hour',
+    'gigabyte',
+    'terabyte',
+    'flat_rate',
+    'person',
+    'licence',
+    'user',
+    'device',
+    'session',
+    'trip',
+    'page',
+    'sheet',
+    'package',
+    'box',
+    'carton',
+    'bottle',
+    'can',
+    'roll',
+    'bag',
+    'pallet',
+];
+/**
+ * UN/ECE-Code je Einheit (Recommendation 20, Verpackungen aus Recommendation 21
+ * mit `X`). Mehrere Einheiten duerfen denselben Code tragen (Meter und
+ * Laufmeter; Lizenz, Benutzer, Geraet als Stueck). Die Validatoren der
+ * E-Rechnung pruefen jeden Code im Backend (Beispiel `api-einheiten`).
+ */
+export const RECHNUNG_EINHEITEN_CODES = Object.freeze({
+    piece: 'C62',
+    pair: 'PR',
+    set: 'SET',
+    dozen: 'DZN',
+    second: 'SEC',
+    minute: 'MIN',
+    hour: 'HUR',
+    day: 'DAY',
+    night: 'C62',
+    week: 'WEE',
+    month: 'MON',
+    quarter: 'QAN',
+    half_year: 'SAN',
+    year: 'ANN',
+    milligram: 'MGM',
+    gram: 'GRM',
+    kilogram: 'KGM',
+    tonne: 'TNE',
+    millimetre: 'MMT',
+    centimetre: 'CMT',
+    metre: 'MTR',
+    running_metre: 'MTR',
+    kilometre: 'KMT',
+    square_metre: 'MTK',
+    // Rec 20 fuehrt fuer Hektar HAR, EN 16931 laesst davon nur H18
+    // („square hectometre", Synonym hectare) zu.
+    hectare: 'H18',
+    millilitre: 'MLT',
+    litre: 'LTR',
+    cubic_metre: 'MTQ',
+    kilowatt_hour: 'KWH',
+    megawatt_hour: 'MWH',
+    gigabyte: 'E34',
+    terabyte: 'E35',
+    flat_rate: 'LS',
+    person: 'IE',
+    licence: 'C62',
+    user: 'C62',
+    device: 'C62',
+    session: 'C62',
+    trip: 'C62',
+    page: 'ZP',
+    // Ebenso: ST („sheet") steht nicht in der Liste von EN 16931, LEF („leaf") schon.
+    sheet: 'LEF',
+    package: 'XPK',
+    box: 'XBX',
+    carton: 'XCT',
+    bottle: 'XBO',
+    can: 'XCA',
+    roll: 'XRO',
+    bag: 'XSA',
+    pallet: 'XPX',
+});
+/**
+ * Was erfuellt sein muss, bevor ueber die API ausgestellt werden darf — in
+ * dieser Reihenfolge meldet `getInvoiceSetupStatus`, was fehlt, und dieselben
+ * Schluessel stehen in `invoice_setup_incomplete`.
+ *
+ * - `module_active`  Modul Rechnung aktiv
+ * - `api_enabled`    Rechnungs-API fuer das Konto von Kasseneck freigegeben (nur live)
+ * - `live_enabled`   Konto live freigeschaltet (nur live)
+ * - `business_name`, `address`, `vat_id`  Pflichtangaben des Ausstellers (§ 11 UStG;
+ *   `vat_id` entfaellt bei Kleinunternehmern)
+ * - `bank_account`   IBAN und Kontoinhaber
+ * - `number_format`  Rechnungsnummern-Format bewusst gespeichert
+ */
+export const INVOICE_SETUP_REQUIREMENTS = [
+    'module_active',
+    'api_enabled',
+    'live_enabled',
+    'business_name',
+    'address',
+    'vat_id',
+    'bank_account',
+    'number_format',
+];
 const text = (max, pflicht = false, extra = {}) => ({ typ: 'string', pflicht, max, ...(pflicht && extra.min === undefined ? { min: 1 } : {}), ...extra });
 const idempotencyKey = (pflicht) => ({ typ: 'string', pflicht, min: 1, max: 120 });
 const id = { typ: 'string', pflicht: false, min: 1, max: 128 };
@@ -91,6 +244,8 @@ export const KUNDE_FELDER = Object.freeze({
     isAuthority: { typ: 'boolean', pflicht: false },
     note: text(1000),
     externalId: { typ: 'string', pflicht: false, min: 1, max: 120 },
+    /** Sprache der Rechnungen an diesen Kunden; fehlt = `de`. */
+    language: { typ: 'enum', pflicht: false, werte: INVOICE_LANGUAGES },
 });
 /** Beim Aendern ist jedes Kundenfeld optional. */
 const KUNDE_PATCH = Object.freeze(Object.fromEntries(Object.entries(KUNDE_FELDER).map(([name, feld]) => [name, { ...feld, pflicht: false }])));
@@ -99,7 +254,8 @@ export const POSITION_FELDER = Object.freeze({
     description: text(300, true),
     subtitle: text(1000),
     quantity: { typ: 'number', pflicht: true, min: 0, exklusivMin: true, max: 1_000_000, nachkomma: 3 },
-    unit: text(20),
+    /** Einheit aus `INVOICE_UNITS`; ohne Angabe `piece`. */
+    unit: { typ: 'enum', pflicht: false, werte: INVOICE_UNITS },
     unitPriceCents: { typ: 'integer', pflicht: true, min: 0, max: 100_000_000 },
     vatRate: { typ: 'enum', pflicht: true, werte: VAT_RATES },
     discountPct: { typ: 'number', pflicht: false, min: 0, max: 100, nachkomma: 2 },
@@ -142,6 +298,10 @@ export const RECHNUNG_ANFRAGEN = Object.freeze({
         tracking: { typ: 'boolean', pflicht: false },
         items: positionen,
         metadata: { typ: 'map', pflicht: false, maxSchluessel: 20, schluesselMuster: '^[a-zA-Z0-9_]{1,40}$', wertMax: 500 },
+        /** Sprache dieser Rechnung; sonst die des Kunden, sonst `de`. */
+        language: { typ: 'enum', pflicht: false, werte: INVOICE_LANGUAGES },
+        /** Marke (Kennung aus `listBrands`); sonst die Standardmarke. */
+        brandId: id,
     },
     cancelInvoice: {
         idempotencyKey: idempotencyKey(true),
@@ -171,11 +331,15 @@ export const RECHNUNG_ANFRAGEN = Object.freeze({
     },
     getInvoicePdf: {
         invoiceId: idPflicht,
+        /** Andere Sprache als die der Rechnung: gekennzeichnete Uebersetzungskopie, keine eigene Rechnung. */
+        language: { typ: 'enum', pflicht: false, werte: INVOICE_LANGUAGES },
     },
     getInvoiceXml: {
         invoiceId: idPflicht,
         format: { typ: 'enum', pflicht: false, werte: EINVOICE_FORMATS },
     },
+    getInvoiceSetupStatus: {},
+    listBrands: {},
 });
 /** Genau eines dieser Felder muss gesetzt sein (je Aufruf, je Gruppe). */
 export const RECHNUNG_GENAU_EINS = Object.freeze({

package/fixtures/hobex-hps-codes.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.15.0",
+  "version": "0.17.0",
   "gemessenAn": {
     "tid": "3600335",
     "hpsVersion": "1.10.0",

package/fixtures/kasse-texte.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.15.0",
+  "version": "0.17.0",
   "meldungen": {
     "netz.keine_verbindung": {
       "text": "Keine Verbindung zum Server. Bitte die Internetverbindung prüfen und erneut versuchen."

package/fixtures/oberflaeche.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.15.0",
+  "version": "0.17.0",
   "aufrufe": [
     "activateCashregister",
     "cancelInvoice",
@@ -25,6 +25,7 @@
     "getFirstReceiptDate",
     "getInvoice",
     "getInvoicePdf",
+    "getInvoiceSetupStatus",
     "getInvoiceXml",
     "getKasseSettings",
     "getPartnerCustomer",
@@ -36,6 +37,7 @@
     "issueInvoice",
     "listCustomerCashregisters",
     "listInvoices",
+    "listBrands",
     "listMyArticleGroups",
     "listMyArticles",
     "listMyCashregisters",
@@ -395,7 +397,15 @@
       "not_cancellable",
       "partial_credit_exists",
       "credit_exceeds_invoice",
-      "einvoice_incomplete"
+      "einvoice_incomplete",
+      "invoice_api_not_enabled",
+      "invoice_setup_incomplete",
+      "language_not_allowed",
+      "brand_not_found"
+    ],
+    "invoiceLanguages": [
+      "de",
+      "en"
     ],
     "invoiceListStatus": [
       "final",
@@ -404,6 +414,67 @@
       "open",
       "overdue"
     ],
+    "invoiceSetupRequirements": [
+      "module_active",
+      "api_enabled",
+      "live_enabled",
+      "business_name",
+      "address",
+      "vat_id",
+      "bank_account",
+      "number_format"
+    ],
+    "invoiceUnits": [
+      "piece",
+      "pair",
+      "set",
+      "dozen",
+      "second",
+      "minute",
+      "hour",
+      "day",
+      "night",
+      "week",
+      "month",
+      "quarter",
+      "half_year",
+      "year",
+      "milligram",
+      "gram",
+      "kilogram",
+      "tonne",
+      "millimetre",
+      "centimetre",
+      "metre",
+      "running_metre",
+      "kilometre",
+      "square_metre",
+      "hectare",
+      "millilitre",
+      "litre",
+      "cubic_metre",
+      "kilowatt_hour",
+      "megawatt_hour",
+      "gigabyte",
+      "terabyte",
+      "flat_rate",
+      "person",
+      "licence",
+      "user",
+      "device",
+      "session",
+      "trip",
+      "page",
+      "sheet",
+      "package",
+      "box",
+      "carton",
+      "bottle",
+      "can",
+      "roll",
+      "bag",
+      "pallet"
+    ],
     "priceModes": [
       "net",
       "gross"
@@ -419,7 +490,9 @@
       "getInvoice",
       "listInvoices",
       "getInvoicePdf",
-      "getInvoiceXml"
+      "getInvoiceXml",
+      "getInvoiceSetupStatus",
+      "listBrands"
     ],
     "taxSchemes": [
       "normal",

package/fixtures/rechnung-api-beispiele/brands-ok.json

@@ -0,0 +1,8 @@
+{
+  "aufruf": "listBrands",
+  "beschreibung": "Marken ohne Parameter",
+  "anfrage": {},
+  "erwartet": {
+    "ok": true
+  }
+}

package/fixtures/rechnung-api-beispiele/issue-englisch.json

@@ -0,0 +1,30 @@
+{
+  "aufruf": "issueInvoice",
+  "beschreibung": "Englische Rechnung mit gewählter Marke",
+  "anfrage": {
+    "idempotencyKey": "bsp-en-1",
+    "customerId": "kunde_beispiel",
+    "taxScheme": "normal",
+    "priceMode": "net",
+    "serviceStart": "2026-09-15",
+    "language": "en",
+    "brandId": "marke_beispiel",
+    "items": [
+      {
+        "description": "Consulting",
+        "quantity": 2,
+        "unitPriceCents": 5000,
+        "vatRate": 20,
+        "unit": "hour"
+      }
+    ]
+  },
+  "erwartet": {
+    "ok": true,
+    "totals": {
+      "netCents": 10000,
+      "vatCents": 2000,
+      "grossCents": 12000
+    }
+  }
+}

package/fixtures/rechnung-api-beispiele/issue-fehler-einheit.json

@@ -0,0 +1,26 @@
+{
+  "aufruf": "issueInvoice",
+  "beschreibung": "Einheit als freier Text statt Schlüssel",
+  "anfrage": {
+    "idempotencyKey": "bsp-einheit",
+    "taxScheme": "normal",
+    "priceMode": "net",
+    "serviceStart": "2026-09-15",
+    "items": [
+      {
+        "description": "Beratung",
+        "quantity": 2,
+        "unit": "Std",
+        "unitPriceCents": 5000,
+        "vatRate": 20
+      }
+    ]
+  },
+  "erwartet": {
+    "ok": false,
+    "code": "validation",
+    "fields": [
+      "items[0].unit"
+    ]
+  }
+}

package/fixtures/rechnung-api-beispiele/issue-fehler-sprache.json

@@ -0,0 +1,26 @@
+{
+  "aufruf": "issueInvoice",
+  "beschreibung": "Unbekannte Sprache",
+  "anfrage": {
+    "idempotencyKey": "bsp-en-2",
+    "taxScheme": "normal",
+    "priceMode": "net",
+    "serviceStart": "2026-09-15",
+    "language": "fr",
+    "items": [
+      {
+        "description": "Beratung",
+        "quantity": 1,
+        "unitPriceCents": 1000,
+        "vatRate": 20
+      }
+    ]
+  },
+  "erwartet": {
+    "ok": false,
+    "code": "validation",
+    "fields": [
+      "language"
+    ]
+  }
+}

package/fixtures/rechnung-api-beispiele/issue-netto-20.json

@@ -13,7 +13,7 @@
         "quantity": 2,
         "unitPriceCents": 5000,
         "vatRate": 20,
-        "unit": "Std"
+        "unit": "hour"
       }
     ]
   },

package/fixtures/rechnung-api-beispiele/setup-status-fehler-feld.json

@@ -0,0 +1,14 @@
+{
+  "aufruf": "getInvoiceSetupStatus",
+  "beschreibung": "Der Status kennt keine Parameter",
+  "anfrage": {
+    "environment": "live"
+  },
+  "erwartet": {
+    "ok": false,
+    "code": "validation",
+    "fields": [
+      "environment"
+    ]
+  }
+}

package/fixtures/rechnung-api-beispiele/setup-status-ok.json

@@ -0,0 +1,8 @@
+{
+  "aufruf": "getInvoiceSetupStatus",
+  "beschreibung": "Einrichtung abfragen, ohne Parameter",
+  "anfrage": {},
+  "erwartet": {
+    "ok": true
+  }
+}

package/fixtures/rechnung-api.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "Kasseneck Rechnungs-API",
   "version": 1,
-  "paket": "0.15.0",
+  "paket": "0.17.0",
   "aufrufe": {
     "createCustomer": {
       "anfrage": {
@@ -79,6 +79,12 @@
                 "type": "string",
                 "minLength": 1,
                 "maxLength": 120
+              },
+              "language": {
+                "enum": [
+                  "de",
+                  "en"
+                ]
               }
             },
             "required": [
@@ -204,6 +210,12 @@
                 "type": "string",
                 "minLength": 1,
                 "maxLength": 120
+              },
+              "language": {
+                "enum": [
+                  "de",
+                  "en"
+                ]
               }
             },
             "additionalProperties": false
@@ -350,8 +362,57 @@
                   "x-decimals": 3
                 },
                 "unit": {
-                  "type": "string",
-                  "maxLength": 20
+                  "enum": [
+                    "piece",
+                    "pair",
+                    "set",
+                    "dozen",
+                    "second",
+                    "minute",
+                    "hour",
+                    "day",
+                    "night",
+                    "week",
+                    "month",
+                    "quarter",
+                    "half_year",
+                    "year",
+                    "milligram",
+                    "gram",
+                    "kilogram",
+                    "tonne",
+                    "millimetre",
+                    "centimetre",
+                    "metre",
+                    "running_metre",
+                    "kilometre",
+                    "square_metre",
+                    "hectare",
+                    "millilitre",
+                    "litre",
+                    "cubic_metre",
+                    "kilowatt_hour",
+                    "megawatt_hour",
+                    "gigabyte",
+                    "terabyte",
+                    "flat_rate",
+                    "person",
+                    "licence",
+                    "user",
+                    "device",
+                    "session",
+                    "trip",
+                    "page",
+                    "sheet",
+                    "package",
+                    "box",
+                    "carton",
+                    "bottle",
+                    "can",
+                    "roll",
+                    "bag",
+                    "pallet"
+                  ]
                 },
                 "unitPriceCents": {
                   "type": "integer",
@@ -392,6 +453,17 @@
               "type": "string",
               "maxLength": 500
             }
+          },
+          "language": {
+            "enum": [
+              "de",
+              "en"
+            ]
+          },
+          "brandId": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128
           }
         },
         "required": [
@@ -490,8 +562,57 @@
                   "x-decimals": 3
                 },
                 "unit": {
-                  "type": "string",
-                  "maxLength": 20
+                  "enum": [
+                    "piece",
+                    "pair",
+                    "set",
+                    "dozen",
+                    "second",
+                    "minute",
+                    "hour",
+                    "day",
+                    "night",
+                    "week",
+                    "month",
+                    "quarter",
+                    "half_year",
+                    "year",
+                    "milligram",
+                    "gram",
+                    "kilogram",
+                    "tonne",
+                    "millimetre",
+                    "centimetre",
+                    "metre",
+                    "running_metre",
+                    "kilometre",
+                    "square_metre",
+                    "hectare",
+                    "millilitre",
+                    "litre",
+                    "cubic_metre",
+                    "kilowatt_hour",
+                    "megawatt_hour",
+                    "gigabyte",
+                    "terabyte",
+                    "flat_rate",
+                    "person",
+                    "licence",
+                    "user",
+                    "device",
+                    "session",
+                    "trip",
+                    "page",
+                    "sheet",
+                    "package",
+                    "box",
+                    "carton",
+                    "bottle",
+                    "can",
+                    "roll",
+                    "bag",
+                    "pallet"
+                  ]
                 },
                 "unitPriceCents": {
                   "type": "integer",
@@ -614,6 +735,12 @@
             "type": "string",
             "minLength": 1,
             "maxLength": 128
+          },
+          "language": {
+            "enum": [
+              "de",
+              "en"
+            ]
           }
         },
         "required": [
@@ -643,6 +770,20 @@
         ],
         "additionalProperties": false
       }
+    },
+    "getInvoiceSetupStatus": {
+      "anfrage": {
+        "type": "object",
+        "properties": {},
+        "additionalProperties": false
+      }
+    },
+    "listBrands": {
+      "anfrage": {
+        "type": "object",
+        "properties": {},
+        "additionalProperties": false
+      }
     }
   },
   "codes": [
@@ -660,7 +801,11 @@
     "not_cancellable",
     "partial_credit_exists",
     "credit_exceeds_invoice",
-    "einvoice_incomplete"
+    "einvoice_incomplete",
+    "invoice_api_not_enabled",
+    "invoice_setup_incomplete",
+    "language_not_allowed",
+    "brand_not_found"
   ],
   "gruende": [
     "cancellation",