@kreiseck/kasseneck-api 0.14.0 → 0.15.0

package/dist/esm/rechnung/vertrag.js

@@ -0,0 +1,188 @@
+/**
+ * Der Vertrag der Rechnungs-API — als Daten, nicht als Prosa.
+ *
+ * Aus dieser Datei entstehen drei Dinge, damit sie nicht auseinanderlaufen
+ * koennen:
+ *
+ * 1. `fixtures/rechnung-api.schema.json` (`npm run fixtures:rechnung`) — das
+ *    Backend liest es aus dem vendorierten Paket und vergleicht es in beide
+ *    Richtungen mit seiner eigenen Pruefung; der Dart-Zwilling zieht es byteweise.
+ * 2. Die Listen unter `rechnung` in `fixtures/oberflaeche.json` (Codes, Gruende,
+ *    Enums) — ueber denselben Namensraum-Scan wie der Partner-Teil.
+ * 3. Die TypeScript-Typen in `typen.ts`.
+ *
+ * Nach aussen spricht die Schnittstelle Englisch: Feldnamen, Codes, Gruende.
+ * Deutsch bleibt, was ein Mensch liest (`message`, der Aufdruck eines Grundes).
+ *
+ * Beschrieben wird die Anfrage. Was der Server daraus macht — Rechnungsdatum,
+ * Nummer, Summen — ist bewusst **nicht** setzbar.
+ */
+export const RECHNUNG_VERTRAG_VERSION = 1;
+export const RECHNUNG_AUFRUFE = [
+    'createCustomer',
+    'getCustomer',
+    'updateCustomer',
+    'searchCustomers',
+    'issueInvoice',
+    'cancelInvoice',
+    'createCreditNote',
+    'getInvoice',
+    'listInvoices',
+    'getInvoicePdf',
+    'getInvoiceXml',
+];
+/**
+ * Stabile Fehlercodes. Das Fremdsystem verzweigt am Code, der Text darf sich
+ * aendern. `validation` traegt zusaetzlich `errors: [{ field, message }]`.
+ */
+export const INVOICE_ERROR_CODES = [
+    'validation',
+    'idempotency_conflict',
+    'module_inactive',
+    'customer_not_found',
+    'customer_exists',
+    'short_code_taken',
+    'short_code_immutable',
+    'recipient_required',
+    'invoice_requirements_missing',
+    'invoice_not_found',
+    'invoice_ambiguous',
+    'not_cancellable',
+    'partial_credit_exists',
+    'credit_exceeds_invoice',
+    'einvoice_incomplete',
+];
+/** Gruende einer Gutschrift. Der Server druckt den deutschen Anzeigetext. */
+export const CREDIT_NOTE_REASONS = [
+    'cancellation',
+    'price_reduction',
+    'return',
+    'incorrect_invoice',
+    'other',
+];
+export const TAX_SCHEMES = ['normal', 'smallBusiness', 'reverseCharge', 'igLieferung', 'exportThirdCountry'];
+export const PRICE_MODES = ['net', 'gross'];
+export const VAT_RATES = [0, 10, 13, 20];
+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'];
+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 };
+const idPflicht = { typ: 'string', pflicht: true, min: 1, max: 128 };
+const datum = (pflicht = false) => ({ typ: 'string', pflicht, min: 10, max: 10, format: 'date' });
+const limit = { typ: 'integer', pflicht: false, min: 1, max: 100 };
+const cursor = { typ: 'string', pflicht: false, min: 1, max: 500 };
+/** Kunde, wie das Fremdsystem ihn schickt. `vatId` ist die UID-Nummer. */
+export const KUNDE_FELDER = Object.freeze({
+    type: { typ: 'enum', pflicht: true, werte: CUSTOMER_TYPES },
+    name: text(200, true),
+    legalForm: text(40),
+    email: text(254, false, { format: 'email' }),
+    phone: text(40, false, { format: 'phone' }),
+    street: text(200),
+    houseNumber: text(20),
+    zip: text(10),
+    city: text(100),
+    country: text(2, true, { min: 2, format: 'country' }),
+    vatId: text(20, false, { format: 'vatId' }),
+    shortCode: text(8, false, { format: 'shortCode' }),
+    isAuthority: { typ: 'boolean', pflicht: false },
+    note: text(1000),
+    externalId: { typ: 'string', pflicht: false, min: 1, max: 120 },
+});
+/** Beim Aendern ist jedes Kundenfeld optional. */
+const KUNDE_PATCH = Object.freeze(Object.fromEntries(Object.entries(KUNDE_FELDER).map(([name, feld]) => [name, { ...feld, pflicht: false }])));
+/** Eine Rechnungs- oder Gutschriftsposition. Preise in ganzen Cent. */
+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),
+    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 },
+});
+const positionen = { typ: 'list', pflicht: true, min: 1, max: 500, eintrag: { typ: 'object', pflicht: true, felder: POSITION_FELDER } };
+export const RECHNUNG_ANFRAGEN = Object.freeze({
+    createCustomer: {
+        customer: { typ: 'object', pflicht: true, felder: KUNDE_FELDER },
+        idempotencyKey: idempotencyKey(false),
+    },
+    getCustomer: {
+        customerId: id,
+        externalId: { typ: 'string', pflicht: false, min: 1, max: 120 },
+    },
+    updateCustomer: {
+        customerId: idPflicht,
+        customer: { typ: 'object', pflicht: true, felder: KUNDE_PATCH },
+    },
+    searchCustomers: {
+        externalId: { typ: 'string', pflicht: false, min: 1, max: 120 },
+        vatId: text(20),
+        email: text(254),
+        name: text(200),
+        limit,
+        cursor,
+    },
+    issueInvoice: {
+        idempotencyKey: idempotencyKey(true),
+        customerId: id,
+        taxScheme: { typ: 'enum', pflicht: true, werte: TAX_SCHEMES },
+        priceMode: { typ: 'enum', pflicht: true, werte: PRICE_MODES },
+        serviceStart: datum(true),
+        serviceEnd: datum(),
+        paymentTermDays: { typ: 'integer', pflicht: false, min: 0, max: 365 },
+        orderReference: text(200),
+        intro: text(2000),
+        note: text(2000),
+        paymentReference: text(140),
+        girocode: { typ: 'boolean', pflicht: false },
+        tracking: { typ: 'boolean', pflicht: false },
+        items: positionen,
+        metadata: { typ: 'map', pflicht: false, maxSchluessel: 20, schluesselMuster: '^[a-zA-Z0-9_]{1,40}$', wertMax: 500 },
+    },
+    cancelInvoice: {
+        idempotencyKey: idempotencyKey(true),
+        invoiceId: idPflicht,
+        reason: { typ: 'enum', pflicht: true, werte: CREDIT_NOTE_REASONS },
+        note: text(2000),
+    },
+    createCreditNote: {
+        idempotencyKey: idempotencyKey(true),
+        invoiceId: idPflicht,
+        reason: { typ: 'enum', pflicht: true, werte: CREDIT_NOTE_REASONS },
+        note: text(2000),
+        items: positionen,
+    },
+    getInvoice: {
+        invoiceId: id,
+        number: { typ: 'string', pflicht: false, min: 1, max: 100 },
+    },
+    listInvoices: {
+        from: datum(),
+        to: datum(),
+        status: { typ: 'enum', pflicht: false, werte: INVOICE_LIST_STATUS },
+        docType: { typ: 'enum', pflicht: false, werte: DOC_TYPES },
+        customerId: id,
+        limit,
+        cursor,
+    },
+    getInvoicePdf: {
+        invoiceId: idPflicht,
+    },
+    getInvoiceXml: {
+        invoiceId: idPflicht,
+        format: { typ: 'enum', pflicht: false, werte: EINVOICE_FORMATS },
+    },
+});
+/** Genau eines dieser Felder muss gesetzt sein (je Aufruf, je Gruppe). */
+export const RECHNUNG_GENAU_EINS = Object.freeze({
+    getCustomer: [['customerId', 'externalId']],
+    getInvoice: [['invoiceId', 'number']],
+});
+/** Mindestens eines dieser Felder muss gesetzt sein (je Aufruf, je Gruppe). */
+export const RECHNUNG_MINDESTENS_EINS = Object.freeze({
+    searchCustomers: [['externalId', 'vatId', 'email', 'name']],
+});

package/fixtures/hobex-hps-codes.json

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

package/fixtures/kasse-texte.json

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

package/fixtures/oberflaeche.json

@@ -1,8 +1,11 @@
 {
-  "version": "0.14.0",
+  "version": "0.15.0",
   "aufrufe": [
     "activateCashregister",
+    "cancelInvoice",
     "cancelReceipt",
+    "createCreditNote",
+    "createCustomer",
     "createCustomerCashregister",
     "createPartnerCustomer",
     "checkPartnerCustomerEmail",
@@ -16,9 +19,13 @@
     "endRegisterSession",
     "financeWebService",
     "generateFullReceiptId",
+    "getCustomer",
     "getCustomerCredentials",
     "getCustomerSignatureStatus",
     "getFirstReceiptDate",
+    "getInvoice",
+    "getInvoicePdf",
+    "getInvoiceXml",
     "getKasseSettings",
     "getPartnerCustomer",
     "getPartnerInfo",
@@ -26,7 +33,9 @@
     "getReceipt",
     "hobexPayApi",
     "hobexRefundApi",
+    "issueInvoice",
     "listCustomerCashregisters",
+    "listInvoices",
     "listMyArticleGroups",
     "listMyArticles",
     "listMyCashregisters",
@@ -43,6 +52,7 @@
     "registerUserLogin",
     "renewRegisterSession",
     "requestCustomerSignature",
+    "searchCustomers",
     "sendPartnerCustomerFonLink",
     "sendPartnerWebhookTest",
     "sendReceiptEmail",
@@ -51,6 +61,7 @@
     "stripeCaptureIntent",
     "unpairRegisterDevice",
     "rotatePartnerWebhookSecret",
+    "updateCustomer",
     "updatePartnerWebhook"
   ],
   "enums": {
@@ -348,5 +359,80 @@
       "test",
       "data"
     ]
+  },
+  "rechnung": {
+    "creditNoteReasons": [
+      "cancellation",
+      "price_reduction",
+      "return",
+      "incorrect_invoice",
+      "other"
+    ],
+    "customerTypes": [
+      "private",
+      "company"
+    ],
+    "docTypes": [
+      "RE",
+      "GU"
+    ],
+    "einvoiceFormats": [
+      "ubl",
+      "cii"
+    ],
+    "invoiceErrorCodes": [
+      "validation",
+      "idempotency_conflict",
+      "module_inactive",
+      "customer_not_found",
+      "customer_exists",
+      "short_code_taken",
+      "short_code_immutable",
+      "recipient_required",
+      "invoice_requirements_missing",
+      "invoice_not_found",
+      "invoice_ambiguous",
+      "not_cancellable",
+      "partial_credit_exists",
+      "credit_exceeds_invoice",
+      "einvoice_incomplete"
+    ],
+    "invoiceListStatus": [
+      "final",
+      "paid",
+      "cancelled",
+      "open",
+      "overdue"
+    ],
+    "priceModes": [
+      "net",
+      "gross"
+    ],
+    "rechnungAufrufe": [
+      "createCustomer",
+      "getCustomer",
+      "updateCustomer",
+      "searchCustomers",
+      "issueInvoice",
+      "cancelInvoice",
+      "createCreditNote",
+      "getInvoice",
+      "listInvoices",
+      "getInvoicePdf",
+      "getInvoiceXml"
+    ],
+    "taxSchemes": [
+      "normal",
+      "smallBusiness",
+      "reverseCharge",
+      "igLieferung",
+      "exportThirdCountry"
+    ],
+    "vatRates": [
+      0,
+      10,
+      13,
+      20
+    ]
   }
 }

package/fixtures/rechnung-api-beispiele/credit-fehler-grund.json

@@ -0,0 +1,24 @@
+{
+  "aufruf": "createCreditNote",
+  "beschreibung": "Unbekannter Grund",
+  "anfrage": {
+    "idempotencyKey": "bsp-12",
+    "invoiceId": "rechnung_beispiel",
+    "reason": "storno",
+    "items": [
+      {
+        "description": "Nachlass",
+        "quantity": 1,
+        "unitPriceCents": 5000,
+        "vatRate": 20
+      }
+    ]
+  },
+  "erwartet": {
+    "ok": false,
+    "code": "validation",
+    "fields": [
+      "reason"
+    ]
+  }
+}

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

@@ -0,0 +1,20 @@
+{
+  "aufruf": "createCreditNote",
+  "beschreibung": "Teilgutschrift als Preisnachlass",
+  "anfrage": {
+    "idempotencyKey": "bsp-11",
+    "invoiceId": "rechnung_beispiel",
+    "reason": "price_reduction",
+    "items": [
+      {
+        "description": "Nachlass Beratung",
+        "quantity": 1,
+        "unitPriceCents": 5000,
+        "vatRate": 20
+      }
+    ]
+  },
+  "erwartet": {
+    "ok": true
+  }
+}

package/fixtures/rechnung-api-beispiele/customer-fehler-uid.json

@@ -0,0 +1,25 @@
+{
+  "aufruf": "createCustomer",
+  "beschreibung": "UID-Nummer im falschen Format",
+  "anfrage": {
+    "customer": {
+      "type": "company",
+      "name": "Café Muster GmbH",
+      "street": "Hauptplatz",
+      "houseNumber": "3",
+      "zip": "1010",
+      "city": "Wien",
+      "country": "AT",
+      "email": "rechnung@cafe-muster.example",
+      "externalId": "shop-4711",
+      "vatId": "ATU1"
+    }
+  },
+  "erwartet": {
+    "ok": false,
+    "code": "validation",
+    "fields": [
+      "customer.vatId"
+    ]
+  }
+}

package/fixtures/rechnung-api-beispiele/customer-get-fehler-beide.json

@@ -0,0 +1,15 @@
+{
+  "aufruf": "getCustomer",
+  "beschreibung": "Genau eine Kennung angeben",
+  "anfrage": {
+    "customerId": "kunde_beispiel",
+    "externalId": "shop-4711"
+  },
+  "erwartet": {
+    "ok": false,
+    "code": "validation",
+    "fields": [
+      "customerId"
+    ]
+  }
+}

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

@@ -0,0 +1,20 @@
+{
+  "aufruf": "createCustomer",
+  "beschreibung": "Firmenkunde mit Kennung aus dem Shop",
+  "anfrage": {
+    "customer": {
+      "type": "company",
+      "name": "Café Muster GmbH",
+      "street": "Hauptplatz",
+      "houseNumber": "3",
+      "zip": "1010",
+      "city": "Wien",
+      "country": "AT",
+      "email": "rechnung@cafe-muster.example",
+      "externalId": "shop-4711"
+    }
+  },
+  "erwartet": {
+    "ok": true
+  }
+}

package/fixtures/rechnung-api-beispiele/customer-search-fehler-leer.json

@@ -0,0 +1,14 @@
+{
+  "aufruf": "searchCustomers",
+  "beschreibung": "Suche ohne Suchbegriff",
+  "anfrage": {
+    "limit": 10
+  },
+  "erwartet": {
+    "ok": false,
+    "code": "validation",
+    "fields": [
+      "externalId"
+    ]
+  }
+}

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

@@ -0,0 +1,27 @@
+{
+  "aufruf": "issueInvoice",
+  "beschreibung": "Bruttopreis: der Server rechnet die USt heraus",
+  "anfrage": {
+    "idempotencyKey": "bsp-2",
+    "customerId": "kunde_beispiel",
+    "taxScheme": "normal",
+    "priceMode": "gross",
+    "serviceStart": "2026-09-14",
+    "items": [
+      {
+        "description": "Frühstück",
+        "quantity": 1,
+        "unitPriceCents": 1200,
+        "vatRate": 20
+      }
+    ]
+  },
+  "erwartet": {
+    "ok": true,
+    "totals": {
+      "netCents": 1000,
+      "vatCents": 200,
+      "grossCents": 1200
+    }
+  }
+}

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

@@ -0,0 +1,26 @@
+{
+  "aufruf": "issueInvoice",
+  "beschreibung": "Beträge in ganzen Cent",
+  "anfrage": {
+    "idempotencyKey": "bsp-9",
+    "customerId": "kunde_beispiel",
+    "taxScheme": "normal",
+    "priceMode": "net",
+    "serviceStart": "2026-09-14",
+    "items": [
+      {
+        "description": "Beratung",
+        "quantity": 1,
+        "unitPriceCents": 12.5,
+        "vatRate": 20
+      }
+    ]
+  },
+  "erwartet": {
+    "ok": false,
+    "code": "validation",
+    "fields": [
+      "items[0].unitPriceCents"
+    ]
+  }
+}

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

@@ -0,0 +1,26 @@
+{
+  "aufruf": "issueInvoice",
+  "beschreibung": "Menge null",
+  "anfrage": {
+    "idempotencyKey": "bsp-10",
+    "customerId": "kunde_beispiel",
+    "taxScheme": "normal",
+    "priceMode": "net",
+    "serviceStart": "2026-09-14",
+    "items": [
+      {
+        "description": "Beratung",
+        "quantity": 0,
+        "unitPriceCents": 5000,
+        "vatRate": 20
+      }
+    ]
+  },
+  "erwartet": {
+    "ok": false,
+    "code": "validation",
+    "fields": [
+      "items[0].quantity"
+    ]
+  }
+}

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

@@ -0,0 +1,26 @@
+{
+  "aufruf": "issueInvoice",
+  "beschreibung": "Negativer Preis gehört in eine Gutschrift",
+  "anfrage": {
+    "idempotencyKey": "bsp-7",
+    "customerId": "kunde_beispiel",
+    "taxScheme": "normal",
+    "priceMode": "net",
+    "serviceStart": "2026-09-14",
+    "items": [
+      {
+        "description": "Nachlass",
+        "quantity": 1,
+        "unitPriceCents": -1,
+        "vatRate": 20
+      }
+    ]
+  },
+  "erwartet": {
+    "ok": false,
+    "code": "validation",
+    "fields": [
+      "items[0].unitPriceCents"
+    ]
+  }
+}

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

@@ -0,0 +1,26 @@
+{
+  "aufruf": "issueInvoice",
+  "beschreibung": "Steuerfreies Schema mit USt-Satz",
+  "anfrage": {
+    "idempotencyKey": "bsp-6",
+    "customerId": "kunde_beispiel",
+    "taxScheme": "smallBusiness",
+    "priceMode": "net",
+    "serviceStart": "2026-09-14",
+    "items": [
+      {
+        "description": "Reparatur",
+        "quantity": 1,
+        "unitPriceCents": 5000,
+        "vatRate": 20
+      }
+    ]
+  },
+  "erwartet": {
+    "ok": false,
+    "code": "validation",
+    "fields": [
+      "items[0].vatRate"
+    ]
+  }
+}

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

@@ -0,0 +1,27 @@
+{
+  "aufruf": "issueInvoice",
+  "beschreibung": "Die Nummer vergibt der Server",
+  "anfrage": {
+    "idempotencyKey": "bsp-8",
+    "customerId": "kunde_beispiel",
+    "taxScheme": "normal",
+    "priceMode": "net",
+    "serviceStart": "2026-09-14",
+    "items": [
+      {
+        "description": "Beratung",
+        "quantity": 1,
+        "unitPriceCents": 5000,
+        "vatRate": 20
+      }
+    ],
+    "number": "2026-0001"
+  },
+  "erwartet": {
+    "ok": false,
+    "code": "validation",
+    "fields": [
+      "number"
+    ]
+  }
+}

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

@@ -0,0 +1,33 @@
+{
+  "aufruf": "issueInvoice",
+  "beschreibung": "Zwei Steuersätze auf einer Rechnung",
+  "anfrage": {
+    "idempotencyKey": "bsp-4",
+    "customerId": "kunde_beispiel",
+    "taxScheme": "normal",
+    "priceMode": "net",
+    "serviceStart": "2026-09-14",
+    "items": [
+      {
+        "description": "Beratung",
+        "quantity": 1,
+        "unitPriceCents": 10000,
+        "vatRate": 20
+      },
+      {
+        "description": "Buch",
+        "quantity": 1,
+        "unitPriceCents": 5000,
+        "vatRate": 10
+      }
+    ]
+  },
+  "erwartet": {
+    "ok": true,
+    "totals": {
+      "netCents": 15000,
+      "vatCents": 2500,
+      "grossCents": 17500
+    }
+  }
+}

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

@@ -0,0 +1,27 @@
+{
+  "aufruf": "issueInvoice",
+  "beschreibung": "Kleinunternehmer: USt-Satz 0",
+  "anfrage": {
+    "idempotencyKey": "bsp-5",
+    "customerId": "kunde_beispiel",
+    "taxScheme": "smallBusiness",
+    "priceMode": "net",
+    "serviceStart": "2026-09-14",
+    "items": [
+      {
+        "description": "Reparatur",
+        "quantity": 1,
+        "unitPriceCents": 5000,
+        "vatRate": 0
+      }
+    ]
+  },
+  "erwartet": {
+    "ok": true,
+    "totals": {
+      "netCents": 5000,
+      "vatCents": 0,
+      "grossCents": 5000
+    }
+  }
+}