@kreiseck/kasseneck-api 0.21.0 → 0.23.0

package/dist/esm/rechnung/summen.js

@@ -0,0 +1,71 @@
+/**
+ * Summen einer Rechnung vorab rechnen — genau so, wie der Server sie beim
+ * Ausstellen rechnet. Fuer Shops, die kassieren, bevor die Rechnung entsteht,
+ * und denselben Betrag brauchen, den die Rechnung spaeter ausweist.
+ *
+ * Die Regel (je USt-Satz, Betraege in Cent, kaufmaennisch gerundet):
+ *
+ * | Modus   | Netto                          | USt                        | Brutto             |
+ * |---------|--------------------------------|----------------------------|--------------------|
+ * | `net`   | round(Σ Zeilen)                | round(Σ Zeilen × Satz/100) | Netto + USt        |
+ * | `gross` | round(B × 100 / (100 + Satz))  | B − Netto                  | B = round(Σ Zeilen)|
+ *
+ * Zeile = Einzelpreis × Menge × (1 − Rabatt/100), ungerundet. Im Brutto-Modus
+ * ist das Brutto der vereinbarte Preis und bleibt, wie die Zeilen es ergeben.
+ * Bei einem steuerfreien Steuerfall zaehlt jede Zeile zu 0 %.
+ *
+ * `fixtures/rechnung-summen.json` haelt die Prueffaelle; Backend und
+ * Dart-Zwilling pruefen gegen dieselbe Datei. Verbindlich bleibt, was der
+ * Server rechnet — mit `previewInvoice` laesst sich das vorab abfragen.
+ */
+import { STEUERFREIE_FAELLE } from './rechnen.js';
+/** Aus dem Kern uebernommen, damit Kern und Huelle nie auseinanderlaufen. */
+export { STEUERFREIE_FAELLE };
+/** Auf Cent gerundete Euro — dieselbe Rundung wie am Server (halber Cent vom Nullpunkt weg). */
+function euroRund(n) {
+    return ((n < 0 ? -1 : 1) * Math.round((Math.abs(n) + Number.EPSILON) * 100)) / 100;
+}
+const euroZuCent = (euro) => Math.round(euroRund(euro) * 100) || 0;
+/** Ganze Cent kaufmaennisch; ein Gleitkomma-Rest wie x,4999999… zaehlt als halber Cent. */
+function centRund(x) {
+    const betrag = Math.round(Math.abs(x) * 1e6) / 1e6;
+    return (x < 0 ? -1 : 1) * Math.round(betrag) || 0;
+}
+/**
+ * Netto, USt und Brutto einer Rechnung in Cent, je Satz absteigend — dieselbe
+ * Form wie `invoice.totals` in den Antworten.
+ *
+ * `taxScheme` ist der Steuerfall der Rechnung; ohne Angabe `normal`. Leitet der
+ * Server einen steuerfreien Fall ab (etwa eine ig. Lieferung), gehoert dieser
+ * Fall hierher — sonst rechnet die Funktion Steuer, die die Rechnung nicht
+ * ausweist.
+ */
+export function rechnungSummen(items, priceMode, taxScheme = 'normal') {
+    const steuerfrei = STEUERFREIE_FAELLE.includes(taxScheme);
+    const bruttoPreise = priceMode === 'gross' && !steuerfrei;
+    // Ungerundete Zeilen je Satz, in Euro wie am Server.
+    const jeSatz = new Map();
+    for (const p of items) {
+        const satz = steuerfrei ? 0 : p.vatRate;
+        const zeile = (p.unitPriceCents / 100) * p.quantity * (1 - (p.discountPct ?? 0) / 100);
+        jeSatz.set(satz, (jeSatz.get(satz) ?? 0) + zeile);
+    }
+    const byRate = [];
+    for (const [rate, roh] of jeSatz) {
+        let netCents;
+        let vatCents;
+        if (bruttoPreise) {
+            const grossCents = euroZuCent(roh);
+            netCents = centRund((grossCents * 100) / (100 + rate));
+            vatCents = grossCents - netCents;
+        }
+        else {
+            netCents = euroZuCent(roh);
+            vatCents = euroZuCent((roh * rate) / 100);
+        }
+        byRate.push({ rate, netCents, vatCents, grossCents: netCents + vatCents });
+    }
+    byRate.sort((a, b) => b.rate - a.rate);
+    const summe = (feld) => byRate.reduce((s, r) => s + r[feld], 0);
+    return { netCents: summe('netCents'), vatCents: summe('vatCents'), grossCents: summe('grossCents'), byRate };
+}

package/dist/esm/rechnung/texte.d.ts

@@ -35,8 +35,12 @@ declare const DE: {
     readonly 'pdf.tabelle.ust': "UST";
     readonly 'pdf.tabelle.einzelNetto': "EINZEL NETTO";
     readonly 'pdf.tabelle.betragNetto': "BETRAG NETTO";
+    readonly 'pdf.tabelle.einzelBrutto': "EINZEL BRUTTO";
+    readonly 'pdf.tabelle.betragBrutto': "BETRAG BRUTTO";
+    readonly 'pdf.position.rabatt': "abzüglich {prozent} % Rabatt";
     readonly 'pdf.summe.zwischensumme': "Zwischensumme netto";
     readonly 'pdf.summe.umsatzsteuer': "Umsatzsteuer {satz}%";
+    readonly 'pdf.summe.darinUst': "darin {satz}% USt von {netto} netto";
     readonly 'pdf.summe.gesamt.rechnung': "Gesamtbetrag";
     readonly 'pdf.summe.gesamt.gutschrift': "Gutschriftsbetrag";
     readonly 'steuer.kleinunternehmer': "Gemäß § 6 Abs. 1 Z 27 UStG wird keine Umsatzsteuer verrechnet (Kleinunternehmer).";

package/dist/esm/rechnung/texte.js

@@ -20,8 +20,12 @@ const DE = {
     'pdf.tabelle.ust': 'UST',
     'pdf.tabelle.einzelNetto': 'EINZEL NETTO',
     'pdf.tabelle.betragNetto': 'BETRAG NETTO',
+    'pdf.tabelle.einzelBrutto': 'EINZEL BRUTTO',
+    'pdf.tabelle.betragBrutto': 'BETRAG BRUTTO',
+    'pdf.position.rabatt': 'abzüglich {prozent} % Rabatt',
     'pdf.summe.zwischensumme': 'Zwischensumme netto',
     'pdf.summe.umsatzsteuer': 'Umsatzsteuer {satz}%',
+    'pdf.summe.darinUst': 'darin {satz}% USt von {netto} netto',
     'pdf.summe.gesamt.rechnung': 'Gesamtbetrag',
     'pdf.summe.gesamt.gutschrift': 'Gutschriftsbetrag',
     'steuer.kleinunternehmer': 'Gemäß § 6 Abs. 1 Z 27 UStG wird keine Umsatzsteuer verrechnet (Kleinunternehmer).',
@@ -226,8 +230,12 @@ const EN = {
     'pdf.tabelle.ust': 'VAT',
     'pdf.tabelle.einzelNetto': 'UNIT NET',
     'pdf.tabelle.betragNetto': 'AMOUNT NET',
+    'pdf.tabelle.einzelBrutto': 'UNIT GROSS',
+    'pdf.tabelle.betragBrutto': 'AMOUNT GROSS',
+    'pdf.position.rabatt': 'less {prozent}% discount',
     'pdf.summe.zwischensumme': 'Subtotal net',
     'pdf.summe.umsatzsteuer': 'VAT {satz}%',
+    'pdf.summe.darinUst': 'incl. {satz}% VAT on {netto} net',
     'pdf.summe.gesamt.rechnung': 'Total',
     'pdf.summe.gesamt.gutschrift': 'Credit total',
     'steuer.kleinunternehmer': 'No VAT charged pursuant to § 6 (1) no. 27 UStG (small business exemption).',

package/dist/esm/rechnung/typen.d.ts

@@ -146,7 +146,7 @@ export interface InvoicePayment {
 }
 /**
  * Ein Hinweis zu einer erfolgreichen Antwort — kein Fehler, sondern etwas,
- * das der Aufrufer wissen sollte (heute nur `cash_receipt_required`).
+ * das der Aufrufer wissen sollte. Die Codes stehen in `INVOICE_NOTICE_CODES`.
  */
 export interface InvoiceNotice {
     code: InvoiceNoticeCode;
@@ -156,7 +156,11 @@ export interface RecordPaymentResult {
     invoice: Invoice;
     payment: InvoicePayment;
     replayed: boolean;
-    notice?: InvoiceNotice;
+    /**
+     * Hinweise zu dieser Zahlung — eine **Liste** wie bei `issueInvoice`
+     * (bis 0.21.0 ein einzelnes Objekt). Fehlt, wenn es keinen gibt.
+     */
+    notice?: InvoiceNotice[];
 }
 export interface CancelInvoiceRequest {
     idempotencyKey: string;
@@ -167,15 +171,23 @@ export interface CancelInvoiceRequest {
 export interface CreditNoteRequest extends CancelInvoiceRequest {
     items: InvoiceItemInput[];
 }
+/**
+ * Summen einer Rechnung in Cent, **immer positiv** — auch bei einer Gutschrift
+ * (`docType: 'GU'`); das Vorzeichen steht im Belegtyp, nicht im Betrag.
+ * Gerechnet wird je Satz wie in [rechnungSummen].
+ */
 export interface InvoiceTotals {
     netCents: number;
     vatCents: number;
     grossCents: number;
-    byRate: {
-        rate: number;
-        netCents: number;
-        vatCents: number;
-    }[];
+    /** Je USt-Satz, absteigend. `grossCents` ist `netCents + vatCents` (seit 0.22.0 mitgeliefert). */
+    byRate: InvoiceRateTotals[];
+}
+export interface InvoiceRateTotals {
+    rate: number;
+    netCents: number;
+    vatCents: number;
+    grossCents: number;
 }
 export interface EInvoiceStatus {
     level: string;
@@ -299,6 +311,38 @@ export interface IssueResult {
      */
     notice?: InvoiceNotice[];
 }
+/**
+ * Was `issueInvoice` mit dieser Anfrage ausstellen wuerde — ohne Nummer, ohne
+ * Dokument, ohne Zahlung. Der Probelauf prueft wie das Ausstellen (Einrichtung,
+ * Kunde, Steuerfall, Pflichtangaben, Marke, Zahlung) und scheitert mit
+ * denselben Fehlercodes.
+ */
+export interface InvoicePreview {
+    docType: 'RE';
+    /** Heutiger Wiener Tag — der Tag, den eine sofort ausgestellte Rechnung truege. */
+    invoiceDate: string;
+    dueDate: string | null;
+    customerId: string | null;
+    /** Der abgeleitete Steuerfall. */
+    taxScheme: TaxScheme;
+    /** Warum dieser Fall gilt (z. B. `customer_country_eu_with_vat_id`). */
+    taxSchemeReason: string;
+    reverseChargeReason: ReverseChargeReason | null;
+    taxCountry: string;
+    priceMode: PriceMode;
+    totals: InvoiceTotals;
+    language: InvoiceLanguage;
+    brand: {
+        id: string | null;
+        name: string | null;
+    } | null;
+    einvoice: EInvoiceStatus;
+}
+export interface PreviewResult {
+    preview: InvoicePreview;
+    /** Dieselben Hinweise, die das Ausstellen liefern wuerde. */
+    notice?: InvoiceNotice[];
+}
 export interface CancelResult {
     creditNote: Invoice;
     original: {

package/dist/esm/rechnung/vertrag.d.ts

@@ -24,7 +24,7 @@ export type RechnungAufruf = (typeof RECHNUNG_AUFRUFE)[number];
  * Stabile Fehlercodes. Das Fremdsystem verzweigt am Code, der Text darf sich
  * aendern. `validation` traegt zusaetzlich `errors: [{ field, message }]`.
  */
-export declare const INVOICE_ERROR_CODES: readonly ["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", "invoice_api_not_enabled", "invoice_setup_incomplete", "language_not_allowed", "brand_not_found", "not_payable", "payment_exceeds_invoice", "tax_scheme_mismatch", "vat_rate_not_in_country", "reverse_charge_reason_required", "reverse_charge_threshold", "mixed_supply_not_allowed", "oss_not_enabled"];
+export declare const INVOICE_ERROR_CODES: readonly ["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", "invoice_api_not_enabled", "invoice_setup_incomplete", "language_not_allowed", "brand_not_found", "not_payable", "payment_exceeds_invoice", "tax_scheme_mismatch", "vat_rate_not_in_country", "reverse_charge_reason_required", "reverse_charge_threshold", "mixed_supply_not_allowed", "oss_not_enabled", "einvoice_unavailable", "amount_too_large"];
 export type InvoiceErrorCode = (typeof INVOICE_ERROR_CODES)[number];
 /** Gruende einer Gutschrift. Der Server druckt den deutschen Anzeigetext. */
 export declare const CREDIT_NOTE_REASONS: readonly ["cancellation", "price_reduction", "return", "incorrect_invoice", "other"];

package/dist/esm/rechnung/vertrag.js

@@ -66,6 +66,8 @@ export const INVOICE_ERROR_CODES = [
     'reverse_charge_threshold',
     'mixed_supply_not_allowed',
     'oss_not_enabled',
+    'einvoice_unavailable', // zu dieser Rechnung entsteht keine E-Rechnung, Grund in `reason`
+    'amount_too_large', // Betrag ueber der Grenze des Ganzzahlkerns; erst ab dessen Umstieg gesendet
 ];
 /** Gruende einer Gutschrift. Der Server druckt den deutschen Anzeigetext. */
 export const CREDIT_NOTE_REASONS = [
@@ -417,6 +419,12 @@ export const RECHNUNG_ANFRAGEN = Object.freeze({
          * und ein sofort geholtes PDF Zahlungsinformationen traegt.
          */
         payment: { typ: 'object', pflicht: false, felder: PAYMENT_FELDER },
+        /**
+         * Probelauf: alles pruefen und rechnen wie beim Ausstellen, aber nichts
+         * festschreiben — keine Nummer, kein Dokument, keine Zahlung, kein
+         * Idempotenz-Eintrag. Die Antwort traegt `preview` statt `invoice`.
+         */
+        dryRun: { typ: 'boolean', pflicht: false },
     },
     cancelInvoice: {
         idempotencyKey: idempotencyKey(true),

package/fixtures/hobex-hps-codes.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.21.0",
+  "version": "0.23.0",
   "gemessenAn": {
     "tid": "3600335",
     "hpsVersion": "1.10.0",

package/fixtures/kasse-texte.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.21.0",
+  "version": "0.23.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.21.0",
+  "version": "0.23.0",
   "aufrufe": [
     "activateCashregister",
     "cancelInvoice",
@@ -410,7 +410,9 @@
       "reverse_charge_reason_required",
       "reverse_charge_threshold",
       "mixed_supply_not_allowed",
-      "oss_not_enabled"
+      "oss_not_enabled",
+      "einvoice_unavailable",
+      "amount_too_large"
     ],
     "invoiceLanguages": [
       "de",
@@ -519,6 +521,14 @@
       "listBrands",
       "recordInvoicePayment"
     ],
+    "steuerfreieFaelle": [
+      "smallBusiness",
+      "reverseCharge",
+      "igLieferung",
+      "exportThirdCountry",
+      "domesticReverseCharge",
+      "outsideScope"
+    ],
     "taxSchemes": [
       "normal",
       "smallBusiness",

package/fixtures/position-aus-euro.json

@@ -0,0 +1,107 @@
+{
+  "beschreibung": "Prüffälle des Umwandlers positionAusEuro (Euro-Position → Ganzzahl-Form). Preis in Millionstel Euro, Menge in Tausendstel, Rabatt und Satz in Hundertstel-Prozent. Umgewandelt wird über den kürzesten Dezimaltext der Zahl, nie per Gleitkomma-Multiplikation — Gleitkomma-Rauschen wie 0,30000000000000004 muss abgelehnt werden.",
+  "regel": "Fehlende Menge und fehlender Satz gelten als 0 (so rechnet der Server ab). Ein fehlender Preis ist nie 0, sondern ein Grund (kein_zahlwert). Ein Minus am Preis wandert an die Menge.",
+  "faelle": [
+    {
+      "name": "Ueblicher Fall: Preis, Menge, Satz und Rabatt zusammen",
+      "item": { "unitPrice": 9.9, "quantity": 3, "vatRate": 10, "discountPct": 5, "description": "Reinigung" },
+      "erwartet": {
+        "ok": true,
+        "position": { "unitPriceMicros": 9900000, "quantityMilli": 3000, "discountBp": 500, "vatRateBp": 1000, "description": "Reinigung" }
+      }
+    },
+    {
+      "name": "Schon Ganzzahl-Form kommt unveraendert zurueck",
+      "item": { "unitPriceMicros": 12345678, "quantityMilli": -500, "vatRateBp": 2000 },
+      "erwartet": {
+        "ok": true,
+        "position": { "unitPriceMicros": 12345678, "quantityMilli": -500, "vatRateBp": 2000 }
+      }
+    },
+    {
+      "name": "Fehlende Menge gilt als 0",
+      "item": { "unitPrice": 5.5, "vatRate": 10 },
+      "erwartet": {
+        "ok": true,
+        "position": { "unitPriceMicros": 5500000, "quantityMilli": 0, "discountBp": 0, "vatRateBp": 1000 }
+      }
+    },
+    {
+      "name": "Fehlender Satz gilt als 0",
+      "item": { "unitPrice": 3.33, "quantity": 4 },
+      "erwartet": {
+        "ok": true,
+        "position": { "unitPriceMicros": 3330000, "quantityMilli": 4000, "discountBp": 0, "vatRateBp": 0 }
+      }
+    },
+    {
+      "name": "Fehlender Preis ist nie 0",
+      "item": { "quantity": 2, "vatRate": 20 },
+      "erwartet": { "ok": false, "feld": "unitPrice", "grund": "kein_zahlwert" }
+    },
+    {
+      "name": "Negativer Preis wandert an die Menge",
+      "item": { "unitPrice": -7.5, "quantity": 3, "vatRate": 10 },
+      "erwartet": {
+        "ok": true,
+        "position": { "unitPriceMicros": 7500000, "quantityMilli": -3000, "discountBp": 0, "vatRateBp": 1000 }
+      }
+    },
+    {
+      "name": "Negative Menge bleibt negativ",
+      "item": { "unitPrice": 4, "quantity": -6 },
+      "erwartet": {
+        "ok": true,
+        "position": { "unitPriceMicros": 4000000, "quantityMilli": -6000, "discountBp": 0, "vatRateBp": 0 }
+      }
+    },
+    {
+      "name": "Gleitkomma-Rauschen am Preis (8,333333333333334) wird abgelehnt",
+      "item": { "unitPrice": 8.333333333333334 },
+      "erwartet": { "ok": false, "feld": "unitPrice", "grund": "nachkommastellen" }
+    },
+    {
+      "name": "Gleitkomma-Rauschen am Rabatt (0,30000000000000004) wird abgelehnt",
+      "item": { "unitPrice": 1, "quantity": 1, "discountPct": 0.30000000000000004 },
+      "erwartet": { "ok": false, "feld": "discountPct", "grund": "nachkommastellen" }
+    },
+    {
+      "name": "Menge mit 4 Nachkommastellen wird abgelehnt",
+      "item": { "unitPrice": 2, "quantity": 1.2345 },
+      "erwartet": { "ok": false, "feld": "quantity", "grund": "nachkommastellen" }
+    },
+    {
+      "name": "Rabatt 12,345 % wird abgelehnt",
+      "item": { "unitPrice": 1, "quantity": 1, "discountPct": 12.345 },
+      "erwartet": { "ok": false, "feld": "discountPct", "grund": "nachkommastellen" }
+    },
+    {
+      "name": "Text statt Zahl beim Preis",
+      "item": { "unitPrice": "9,99" },
+      "erwartet": { "ok": false, "feld": "unitPrice", "grund": "kein_zahlwert" }
+    },
+    {
+      "name": "Satz 120 % liegt ausserhalb",
+      "item": { "unitPrice": 1, "quantity": 1, "vatRate": 120 },
+      "erwartet": { "ok": false, "feld": "vatRate", "grund": "ausserhalb" }
+    },
+    {
+      "name": "Preis ueber 10^12 Mikro-Euro liegt ausserhalb",
+      "item": { "unitPrice": 1000001, "quantity": 1 },
+      "erwartet": { "ok": false, "feld": "unitPrice", "grund": "ausserhalb" }
+    },
+    {
+      "name": "Satz mit zwei Nachkommastellen (4,95 %) ist verlustfrei",
+      "item": { "unitPrice": 1, "quantity": 1, "vatRate": 4.95 },
+      "erwartet": {
+        "ok": true,
+        "position": { "unitPriceMicros": 1000000, "quantityMilli": 1000, "discountBp": 0, "vatRateBp": 495 }
+      }
+    },
+    {
+      "name": "Satz mit drei Nachkommastellen (4,955 %) wird abgelehnt",
+      "item": { "unitPrice": 1, "quantity": 1, "vatRate": 4.955 },
+      "erwartet": { "ok": false, "feld": "vatRate", "grund": "nachkommastellen" }
+    }
+  ]
+}

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.21.0",
+  "paket": "0.23.0",
   "aufrufe": {
     "createCustomer": {
       "anfrage": {
@@ -523,6 +523,9 @@
               "method"
             ],
             "additionalProperties": false
+          },
+          "dryRun": {
+            "type": "boolean"
           }
         },
         "required": [
@@ -926,7 +929,9 @@
     "reverse_charge_reason_required",
     "reverse_charge_threshold",
     "mixed_supply_not_allowed",
-    "oss_not_enabled"
+    "oss_not_enabled",
+    "einvoice_unavailable",
+    "amount_too_large"
   ],
   "gruende": [
     "cancellation",