@kreiseck/kasseneck-api 0.26.0 → 0.27.2

package/CHANGELOG.md

@@ -4,6 +4,44 @@ Was vor 0.7.0 geschah, steht in der Commit-Historie (`git log`); ab hier wird
 es hier geführt. Ein Eintrag nennt die Änderung **und ihren Grund** —
 nur der Grund überlebt den nächsten Umbau.
 
+## 0.27.2
+
+- **README auf Englisch** und jede Angabe gegen den Code geprüft. Anfragen kommen inzwischen auch
+  aus dem Ausland, und auf npm ist Englisch die Erwartung. RKSV-Begriffe bleiben deutsch und
+  werden beim ersten Vorkommen erklärt; ein Glossar am Ende nennt dieselben Begriffe wie der
+  Dart-Zwilling. Eine kurze deutsche Einstiegsseite liegt als `README.de.md` im Repo.
+- Dabei berichtigt: Beispiele, die nicht kompilierten (`business` statt `betrieb`, `automatic`
+  statt `automatisch`, Einheit `'Std'`, optionale `logoUrl`), die Option `regelwerk` statt
+  `layoutRegeln`, die Druckwege (WebUSB, ePOS, Druckaufträge gehören zum Paket), `refund` und
+  `cancel` am HPS-Terminal, sechs statt drei anmeldungsfreie Aufrufe und § 131b **BAO**.
+- `package.json`: Beschreibung englisch zuerst, weitere englische Schlagwörter.
+
+## 0.27.1
+
+- Drei Beispiele zum Mikropreis in `fixtures/rechnung-api-beispiele/`: der Sub-Cent-Fall
+  (3.500.000 × 0,000004 € = 14,00 € netto), beide Preise gesetzt und kein Preis gesetzt. Sie sind
+  zugleich die Prüfvektoren, die Server und Dart-Zwilling gegen ihre eigene Prüfung fahren — ein
+  Beispiel, das nur in der Doku steht, veraltet unbemerkt.
+
+## 0.27.0
+
+- **Rechnungs-API: der Einzelpreis einer Position darf in Mikro-Euro stehen** (`unitPriceMicros`,
+  10⁻⁶ €). Genau eines von `unitPriceCents` und `unitPriceMicros` — beide Felder sind dafür
+  optional, und die neue Genau-eins-Regel am Positions-Objekt wird im JSON Schema zu
+  `oneOf: [{required:['unitPriceCents']}, {required:['unitPriceMicros']}]`. Grund: Preise unterhalb
+  eines Cents (Verbrauchsabrechnung, Stückpreise im Zehntelcent) mussten bisher schon beim
+  Einreichen gerundet werden; der Rundungsfehler steckte danach in jeder Zeile.
+  **Bricht die Form:** wer den Typ `IssueInvoiceItem` selbst baut, bekommt `unitPriceCents` jetzt
+  als optionales Feld. Anfragen, die es setzen, bleiben unverändert gültig.
+- Der Mikropreis deckt denselben Betragsbereich wie die Cent-Angabe (10¹² Mikro-Euro = 10⁸ Cent =
+  10.000.000,00 €). Eine eigene Obergrenze wäre eine stille Bereichsänderung, je nachdem welches
+  Feld ein Aufrufer benutzt.
+- Die Menge reicht bis 10⁹ statt 10⁶, passend zu `quantityMilli` der gespeicherten Form.
+- **Noch nicht enthalten:** `rechnungSummen` rechnet weiterhin wie bisher, nicht über den exakten
+  Kern. Das gehört zum Stichtag der Umstellung (Schalter `ganzzahlPflicht`): solange der Server
+  eine Rechnung nach dem alten Weg ausstellt, darf eine Vorschau im Aufrufer nicht schon exakt
+  runden — sie zeigte sonst an Halbcent-Grenzen einen anderen Cent als die Rechnung.
+
 ## 0.26.0
 
 - Beleg: Am Ende steht das Kasseneck-Logo als Bild statt der Zeile „erstellt mit Kasseneck".

package/README.de.md

@@ -0,0 +1,77 @@
+# @kreiseck/kasseneck-api (Deutsch)
+
+**Registrierkasse nach RKSV für JavaScript und TypeScript.** Kasseneck ist eine
+österreichische Registrierkasse; dieses Paket ist der Client dafür. Ihr Code
+stellt Belege aus, das Kasseneck-Backend signiert und verkettet sie, und das
+Paket liefert das Ergebnis als typisierte Objekte. Dazu kommen Storno,
+Kartenzahlung, Beleg-Layout und Bondruck (ESC/POS, Epson ePOS, WebUSB), die
+Partner-API und die Rechnungs-API.
+
+Die vollständige Dokumentation steht auf Englisch in der
+[README.md](https://github.com/kreiseck-at/kasseneck-api/blob/main/README.md).
+
+## Installation
+
+```bash
+npm install @kreiseck/kasseneck-api
+```
+
+Node ab 20.18, läuft auch im Browser; keine Laufzeitabhängigkeiten. React ist
+optional und nur für `@kreiseck/kasseneck-api/react` nötig.
+
+## Ein Beleg in wenigen Zeilen
+
+```ts
+import { createKasseneckApi, apiKeyAuth, KeckPaymentMethod, VatRate } from '@kreiseck/kasseneck-api';
+import { buildReceiptLayout, escPosLayoutBytes } from '@kreiseck/kasseneck-api/receipt';
+
+const api = createKasseneckApi({
+  auth: apiKeyAuth({ apiKey: 'kr_live_…', cashregisterToken: 'cb_live_…' }),
+});
+
+const { receipt, company, testKasse, testSignatur, pruefangaben } = await api.sellReceiptWithCompany({
+  paymentMethod: KeckPaymentMethod.cash,
+  items: [{ name: 'Café Latte', quantity: 2, vat: VatRate.vat20, priceCents: 390 }],
+});
+
+const layout = buildReceiptLayout(receipt, company, { paperSize: 'mm58', testKasse, testSignatur, pruefangaben });
+const bytes = escPosLayoutBytes(layout);   // für den Bondrucker
+```
+
+Beträge sind immer ganze Cent (`priceCents`), Mengen am Beleg ganze Zahlen.
+Fehler kommen als geworfene Ausnahme; fachliche Fehler tragen einen stabilen
+`code`, an dem man entscheidet, nicht am Text.
+
+## Welche RKSV-Pflichten die Software abdeckt
+
+| Aufgabe | Wo sie erledigt wird |
+| --- | --- |
+| [Signaturerstellungseinheit](https://kasseneck.at/wissen/signaturerstellungseinheit) | Kasseneck, nichts zu installieren |
+| [Verkettung und DEP](https://kasseneck.at/wissen/dep), Umsatzzähler | Kasseneck-Backend |
+| [Startbeleg, Monatsbeleg, Jahresbeleg](https://kasseneck.at/wissen/startbeleg-monatsbeleg-jahresbeleg) | Kasseneck, automatisch |
+| [Meldungen an FinanzOnline](https://kasseneck.at/wissen/finanzonline): Anmeldung, Ausfall, Außerbetriebnahme | Kasseneck-Backend übermittelt sie |
+| [Belegerteilungspflicht](https://kasseneck.at/wissen/belegerteilungspflicht) | **dieses Paket**: Bon, PDF, Bildschirm oder Link |
+| [Ausfall der Signatureinheit](https://kasseneck.at/wissen/ausfall) | Kasseneck, automatisch |
+| [Kassennachschau](https://kasseneck.at/wissen/kassennachschau): DEP-Export | Kasseneck |
+| Anmeldepflicht der Kasse, Aufbewahrung, steuerliche Würdigung | **beim Unternehmer** |
+
+> **Kein Rechts- oder Steuerrat.** Die Tabelle beschreibt, was die Software
+> tut. Sie ersetzt keine Beratung und sichert nicht zu, dass ein bestimmter
+> Betrieb damit alle Pflichten erfüllt. Verbindlich sind BAO, RKSV und die
+> Erlässe des BMF; Anmeldung, Betrieb und Aufbewahrung bleiben Sache des
+> Unternehmers, auch wo die Software die Meldungen übermittelt. Ausführlich
+> und mit Quellen: [kasseneck.at/wissen](https://kasseneck.at/wissen).
+> Stand: September 2026.
+
+## Weiter
+
+- Vollständige Dokumentation (Englisch):
+  [README.md](https://github.com/kreiseck-at/kasseneck-api/blob/main/README.md)
+- Schnittstelle: [kasseneck.at/api-doku](https://kasseneck.at/api-doku)
+- Fertige Registrierkasse ohne Programmieren: [kasseneck.at](https://kasseneck.at)
+- Kontakt für Integrationen und Partnerschaften:
+  [kasseneck.at/kontakt](https://kasseneck.at/kontakt)
+
+**Kasseneck** ist ein Produkt von
+[Kreiseck Software Solutions](https://kreiseck.com) aus Salzburg.
+Lizenz: Apache-2.0.