@kreiseck/kasseneck-api 0.26.0 → 0.27.2

package/README.md

@@ -1,328 +1,541 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/kreiseck-at/kasseneck-api/main/doc/kasseneck.gif" alt="Kasseneck — RKSV-Registrierkasse aus Österreich" width="420">
+  <img src="https://raw.githubusercontent.com/kreiseck-at/kasseneck-api/main/doc/kasseneck.gif" alt="Kasseneck: RKSV fiscal cash register from Austria" width="420">
 </p>
 
 <h1 align="center">@kreiseck/kasseneck-api</h1>
 
 <p align="center">
-  <b>Austrian fiscal cash register (RKSV) for JavaScript and TypeScript — signed receipts, card payments, receipt printing.</b>
+  <b>Austrian fiscal cash register (RKSV) for JavaScript and TypeScript: signed receipts, card payments, receipt printing.</b>
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@kreiseck/kasseneck-api"><img src="https://img.shields.io/npm/v/%40kreiseck%2Fkasseneck-api?color=136B6B&label=npm" alt="npm"></a>
   <img src="https://img.shields.io/badge/RKSV-%C2%A7%20131b%20BAO-136B6B" alt="RKSV">
-  <img src="https://img.shields.io/badge/Lizenz-Apache--2.0-136B6B" alt="Apache-2.0">
+  <img src="https://img.shields.io/badge/License-Apache--2.0-136B6B" alt="Apache-2.0">
   <a href="https://kasseneck.at"><img src="https://img.shields.io/badge/Kasseneck-kasseneck.at-132A2A" alt="kasseneck.at"></a>
-  <a href="https://kreiseck.com"><img src="https://img.shields.io/badge/von-Kreiseck-132A2A" alt="Kreiseck Software Solutions"></a>
+  <a href="https://kreiseck.com"><img src="https://img.shields.io/badge/by-Kreiseck-132A2A" alt="Kreiseck Software Solutions"></a>
 </p>
 
-**Kasseneck** ist eine österreichische Registrierkasse nach RKSV. Dieses Paket ist
-der JavaScript-/TypeScript-Client dafür: Ihr Code stellt Belege aus, storniert sie,
-nimmt Kartenzahlungen entgegen und druckt Bons. Es ist der Zwilling des
-Flutter-Pakets [`kasseneck_api`](https://pub.dev/packages/kasseneck_api):
-dieselben Endpunkte, dieselben Modelle, dieselben Enum-Werte, im Test
-gegeneinander geprüft.
-
-## Was eine Registrierkasse in Österreich können muss
-
-Die Registrierkassen- und Belegerteilungspflicht steht in § 131b der
-Bundesabgabenordnung, die technischen Anforderungen an die Sicherheitseinrichtung
-in der Registrierkassensicherheitsverordnung (RKSV). Daraus ergibt sich eine
-ganze Kette von Aufgaben — die Tabelle zeigt, welche davon **diese Software**
-übernimmt und welche beim Betrieb selbst bleiben:
+<p align="center">
+  Deutsch: <a href="https://github.com/kreiseck-at/kasseneck-api/blob/main/README.de.md">README.de.md</a>
+</p>
 
-| Aufgabe | Wo sie erledigt wird |
-| --- | --- |
-| [Signaturerstellungseinheit](https://kasseneck.at/wissen/signaturerstellungseinheit) — jede Barzahlung wird signiert | Kasseneck, nichts zu installieren |
-| [Verkettung und DEP](https://kasseneck.at/wissen/dep) — jeder Beleg trägt den vorigen, das Protokoll ist exportierbar | 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 |
-| [Belegerteilungspflicht](https://kasseneck.at/wissen/belegerteilungspflicht) — jeder Kunde bekommt einen Beleg | **dieses Paket** — Bon, PDF, Bildschirm oder Link |
-| [Ausfall der Signatureinheit](https://kasseneck.at/wissen/ausfall) — Sammelbeleg, Meldung, Nachsignatur | Kasseneck, automatisch |
-| [Kassennachschau](https://kasseneck.at/wissen/kassennachschau) — der Prüfer verlangt das DEP | Kasseneck, Export auf Knopfdruck |
-| Anmeldung der Kasse, Aufbewahrung, steuerliche Würdigung | **beim Unternehmer** |
-
-Kurz: Sie bauen die Kassenoberfläche, nicht die Sicherheitseinrichtung. Ein Aufruf
-von `createReceipt(...)` erzeugt einen signierten, verketteten und im DEP
-abgelegten Beleg. Die Signaturkette wird gegen das offizielle Prüfwerkzeug des
-BMF getestet.
-
-> **Kein Rechts- oder Steuerrat.** Dieser Abschnitt beschreibt, was die Software
-> tut. Er ersetzt keine Beratung und begründet keine Zusicherung, dass ein
-> bestimmter Betrieb damit alle Pflichten erfüllt. Verbindlich sind die
-> Bundesabgabenordnung, die RKSV und die Erlässe des BMF; die Verantwortung für
-> Anmeldung, Betrieb und Aufbewahrung bleibt beim Unternehmer. Ausführlicher und
-> mit Quellen: [kasseneck.at/wissen](https://kasseneck.at/wissen).
-> Stand: September 2026.
-
-## Erst ausprobieren
-
-Es gibt eine Test-Umgebung mit eigenem Schlüssel und Test-Signaturen, getrennt
-vom Echtbetrieb — die aktuellen Konditionen stehen auf
-[kasseneck.at/preise](https://kasseneck.at/preise), die Schnittstelle ist unter
-[kasseneck.at/api-doku](https://kasseneck.at/api-doku) beschrieben.
-
-## Lieber eine fertige Kasse?
-
-Dieses Paket ist für alle, die eine eigene Anwendung bauen. Wer einfach kassieren
-will, muss nichts davon programmieren:
-
-- **[Kasseneck — die fertige Registrierkasse](https://kasseneck.at)** für Telefon,
-  Tablet und Browser, inklusive Signaturerstellungseinheit und
-  FinanzOnline-Anmeldung.
-- **[Lösungen nach Branche](https://kasseneck.at/branchen)** — vom Lokal bis zum Taxi.
-- **[Preise](https://kasseneck.at/preise)**
-- **[Kontakt](https://kasseneck.at/kontakt)** — auch für Kassenwechsel,
-  Partnerschaften und eigene Integrationen.
-
-## Was drin ist
-
-Belege ausstellen und stornieren, Belege und Kassen auflisten, Berichte
-herunterladen, Status bei FinanzOnline abfragen, Stripe-Zahllinks und
-Hobex-Cloud-Zahlungen, das Beleg-Layout und die ESC/POS-Erzeugung für den
-Bondrucker — und unter `./partner` die **Partner-API**: Betriebe anlegen und bis
-zur laufenden Kasse begleiten.
-
-**Es läuft im Browser und in Node.** ESM ist das Hauptformat, CommonJS liegt
-daneben; beides mit eigenen Typdeklarationen. Node ab 20.18 (`fetch` muss
-vorhanden sein). Es gibt keine Laufzeitabhängigkeiten.
-
-## Installation
+**Kasseneck** is a fiscal cash register (*Registrierkasse*) for Austria that
+implements the RKSV, the Austrian cash register security regulation. This
+package is its JavaScript and TypeScript client: your code issues receipts,
+the Kasseneck backend handles receipt signing and chaining, and the package
+returns the results as typed objects. It also cancels receipts, takes card
+payments, lays out and prints receipts on thermal printers, and covers the
+partner and invoice APIs. It is the twin of the Flutter package
+[`kasseneck_api`](https://pub.dev/packages/kasseneck_api): same endpoints, same
+models, same enum values, checked against each other in tests.
+
+## Contents
+
+- [Quick start](#quick-start)
+- [What a fiscal cash register in Austria must do](#what-a-fiscal-cash-register-in-austria-must-do)
+- [Try it first, or use the ready-made register](#try-it-first-or-use-the-ready-made-register)
+- [Requirements and subpaths](#requirements-and-subpaths)
+- [Authentication](#authentication)
+- [Amounts are integer cents](#amounts-are-integer-cents)
+- [Errors](#errors)
+- [Receipts](#receipts)
+- [Cancellation (Storno)](#cancellation-storno)
+- [Sending a receipt by email](#sending-a-receipt-by-email)
+- [Receipt printing: QR code, logo, printers](#receipt-printing-qr-code-logo-printers)
+- [Card payments](#card-payments)
+- [Partner API (`./partner`)](#partner-api-partner)
+- [Invoice API (`./rechnung`)](#invoice-api-rechnung)
+- [Development](#development)
+- [Contract files for the twin packages](#contract-files-for-the-twin-packages)
+- [Glossary](#glossary)
+- [License](#license)
+
+## Quick start
 
 ```bash
 npm install @kreiseck/kasseneck-api
 ```
 
-React ist eine optionale Peer-Abhängigkeit und nur für den Unterpfad `./react`
-nötig.
+Sell two items, then build the printed receipt (*Beleg*) from the response:
+
+```ts
+import {
+  createKasseneckApi,
+  apiKeyAuth,
+  KeckPaymentMethod,
+  VatRate,
+} from '@kreiseck/kasseneck-api';
+import { buildReceiptLayout, renderReceiptGrid, escPosLayoutBytes } from '@kreiseck/kasseneck-api/receipt';
+
+const api = createKasseneckApi({
+  auth: apiKeyAuth({ apiKey: 'kr_live_…', cashregisterToken: 'cb_live_…' }),
+});
+
+// Sell, and get the company data for the receipt header in the same call.
+const { receipt, company, testKasse, testSignatur, pruefangaben } = await api.sellReceiptWithCompany({
+  paymentMethod: KeckPaymentMethod.cash,
+  items: [
+    { name: 'Café Latte', quantity: 2, vat: VatRate.vat20, priceCents: 390 },
+    { name: 'Marmeladeweckerl', quantity: 1, vat: VatRate.vat10, priceCents: 250 },
+  ],
+  // Optional tip in cents; the backend books it as a signed tip line.
+  // With its own payment method or recipients: { cents, paymentMethod, recipients }.
+  tip: 100,
+});
+
+// Layout: a plain data model (lines, alignment, columns, QR code).
+// testKasse / testSignatur add the "not a valid receipt" banner where needed.
+const layout = buildReceiptLayout(receipt, company, { paperSize: 'mm58', testKasse, testSignatur, pruefangaben });
+
+// Character grid: exactly 32 (58 mm) or 48 (80 mm) characters per line.
+// Screen, printed receipt and PDF all use this one grid.
+const grid = renderReceiptGrid(layout);          // grid.lines[i].text, .bold, .kind, .qr
+
+// ESC/POS bytes for a thermal printer; they print exactly the grid lines.
+const bytes = escPosLayoutBytes(layout);
+```
+
+The receipt returned by `sellReceiptWithCompany` (or `sellReceipt`) has already
+been signed, chained and stored in the data capture log (*DEP*) by the backend.
 
-## Die zwei Anmeldewege
+## What a fiscal cash register in Austria must do
 
-Der Client nimmt eine **austauschbare Anmeldung** entgegen — ein Objekt, das
-pro Anfrage die Kopfzeilen liefert. Es gibt zwei, und keiner ist der
-bevorzugte:
+The obligation to use a fiscal cash register and to issue receipts is set out
+in § 131b of the Austrian Federal Fiscal Code (*Bundesabgabenordnung*, BAO).
+The technical requirements for the security device are in the cash register
+security regulation (*Registrierkassensicherheitsverordnung*, RKSV). The table
+shows which of the resulting tasks **this software** takes over and which stay
+with the business:
 
-| Weg | Wer | Wie |
+| Task | Where it is handled |
+| --- | --- |
+| [Signature creation unit (*Signaturerstellungseinheit*)](https://kasseneck.at/wissen/signaturerstellungseinheit): every receipt is signed | Kasseneck, nothing to install |
+| [Chaining and the data capture log (*DEP*)](https://kasseneck.at/wissen/dep): each receipt carries a value derived from the previous one, the encrypted turnover counter (*Umsatzzähler*) runs along, the log can be exported | Kasseneck backend |
+| [Start receipt, monthly receipt, annual receipt (*Startbeleg, Monatsbeleg, Jahresbeleg*)](https://kasseneck.at/wissen/startbeleg-monatsbeleg-jahresbeleg) | Kasseneck, automatic |
+| [Notifications to FinanzOnline](https://kasseneck.at/wissen/finanzonline): registration, failure, decommissioning (*Außerbetriebnahme*) with its final receipt (*Schlussbeleg*) | Kasseneck backend submits them |
+| [Obligation to issue receipts (*Belegerteilungspflicht*)](https://kasseneck.at/wissen/belegerteilungspflicht): every customer gets a receipt | **this package**: printed receipt, PDF, screen or link |
+| [Signature unit failure (*Ausfall der Signatureinheit*)](https://kasseneck.at/wissen/ausfall): collective receipt, notification, subsequent signing | Kasseneck, automatic |
+| [Cash register audit (*Kassennachschau*)](https://kasseneck.at/wissen/kassennachschau): the auditor asks for the DEP | Kasseneck, export on request |
+| Duty to register the cash register, retention of records, tax assessment | **the business owner** |
+
+In short: you build the point-of-sale interface, not the security device. The
+signature chain is tested against the official verification tool of the
+Austrian Federal Ministry of Finance (BMF).
+
+> **Not legal or tax advice.** This section describes what the software does.
+> It does not replace professional advice and is no assurance that a particular
+> business meets all its obligations with it. The BAO, the RKSV and the rulings
+> of the BMF are binding. Registering and operating the cash register and
+> retaining the records remain the duty of the business owner, also where the
+> software submits the notifications. More detail with sources (in German):
+> [kasseneck.at/wissen](https://kasseneck.at/wissen).
+> As of: September 2026.
+
+## Try it first, or use the ready-made register
+
+There is a test environment with its own key and test signatures, separate
+from live operation. The HTTP interface is described at
+[kasseneck.at/api-doku](https://kasseneck.at/api-doku).
+
+This package is for people who build their own application. If you just want
+to take payments, there is nothing to program:
+
+- **[Kasseneck, the ready-made fiscal cash register](https://kasseneck.at)** for
+  phone, tablet and browser, including the signature creation unit and the
+  FinanzOnline registration.
+- **[Solutions by industry](https://kasseneck.at/branchen)**
+- **[Pricing](https://kasseneck.at/preise)**
+- **[Contact](https://kasseneck.at/kontakt)**, also for switching registers,
+  partnerships and custom integrations.
+
+## Requirements and subpaths
+
+**Runs in the browser and in Node.js.** ESM is the main format, CommonJS ships
+alongside it, both with their own type declarations. Node 20.18 or later
+(`fetch` must be available). There are no runtime dependencies. React 18 or
+later is an optional peer dependency, needed only for `./react`.
+
+Import only the subpath you need, so a Node program never pulls in the React
+adapter:
+
+| Subpath | Contents |
+|-----------|--------|
+| `@kreiseck/kasseneck-api` | Endpoints, authentication, transport, models, enums, errors: everything that talks to the backend. |
+| `…/receipt` | Receipt layout as a data model (framework-free), the character grid, the receipt sheet with logo, and the bridges to ESC/POS and Epson ePOS (XML and direct printing over HTTP). |
+| `…/printing` | ESC/POS generation (byte sequences for thermal printers), QR sizing, printing over WebUSB. |
+| `…/payments` | Stripe payment links, Hobex cloud (both HTTP endpoints of the backend), and Hobex **HPS** via **Kasseneck Connect** (local device agent that talks to the terminal). |
+| `…/register` | Sign-in for the browser register: pair and unpair a device, list its users and sessions, sign in by PIN, renew and end the session. |
+| `…/kasse` | Tile register: register settings (business-wide and per device), article groups and articles for tiles, discount distribution per VAT rate, scopes of register permissions, network printers and print jobs, tip recipients, the register's message catalogue. |
+| `…/partner` | Partner API: create businesses, FinanzOnline link, signature, cash registers, credentials, webhooks with signature verification. **Belongs on a server.** |
+| `…/rechnung` | Invoice API: create and search customers, issue finalised invoices, credit notes and cancellation, PDF and e-invoice XML, the contract as data. **Belongs on a server.** |
+| `…/rechnung/rechnen` | Pure calculation core for invoice totals (integers, no transport, no dependency beyond types). Safe to run in the browser. |
+| `…/react` | Thin React adapter that renders a receipt layout or a receipt sheet. Needs React. |
+| `…/fixtures/*` | Golden receipts (JSON): inputs `belege/<name>.json`, promised line output `erwartet/<name>.lines.json`, `manifest.json` with checksums. The backend, the browser register and the Flutter package check against the same files. |
+
+Every exported function carries its documentation as TSDoc in the shipped type
+declarations, so your editor shows it on hover. That is also the reference for
+the partner and invoice endpoints; this README shows how to use the client.
+
+## Authentication
+
+The client takes an **exchangeable authentication**: an object that supplies
+the headers for each request. There are two, and neither is preferred:
+
+| Mode | For | How |
 |-----|-----|-----|
-| `apiKeyAuth` | Geräte, POS-Apps, Dritte | `api_key` als Bearer + `cashregister-token`-Kopfzeile |
-| `registerUserAuth` | Browser-Kasse | ID-Token des Anmeldediensts als Bearer + `register-session`-Kopfzeile, Kasse als Parameter |
+| `apiKeyAuth` | devices, POS apps, third parties | `api_key` as bearer token plus the `cashregister-token` header |
+| `registerUserAuth` | browser register | ID token of the sign-in service as bearer token plus the `register-session` header, cash register as the `cashregisterId` parameter |
 
 ```ts
 import { apiKeyAuth, registerUserAuth } from '@kreiseck/kasseneck-api';
 
-// Gerät/POS: der api_key gehört auf ein Gerät, nie in einen Browser.
-const geraet = apiKeyAuth({ apiKey: 'kr_live_…', cashregisterToken: 'cb_live_…' });
+// Device/POS: the api_key belongs on a device, never in a browser.
+const device = apiKeyAuth({ apiKey: 'kr_live_…', cashregisterToken: 'cb_live_…' });
 
-// Browser-Kasse: das Paket kennt den Anmeldedienst nicht — es bekommt Funktionen, die
-// ein gültiges Token bzw. die laufende Sitzung liefern. Beide werden bei JEDEM
-// Aufruf befragt (ID-Tokens laufen nach einer Stunde ab, die Kassen-Sitzung
-// nach 90 Sekunden).
-const kasse = registerUserAuth({
+// Browser register: the package does not know the sign-in service. It gets
+// functions that return a valid token and the current session. Both are asked
+// on EVERY call (ID tokens expire after one hour, the register session after
+// 90 seconds).
+const register = registerUserAuth({
   getIdToken: () => auth.currentUser!.getIdToken(),
-  getSessionId: () => sitzungHalter.aktuelleId(),
+  getSessionId: () => sessionHolder.currentId(),
   cashregisterId: 'kasse-1',
 });
 ```
 
-### Und ein dritter Fall: gar keine Anmeldung
+### Calls without any authentication
+
+Six calls run **without any identity**, because they are how an identity comes
+into being or how a device manages itself. They live in `…/register` and take
+**no authentication**, only the connection settings (base URL, timeout,
+`fetch`):
 
-Drei Endpunkte laufen **ohne jede Identität** — sie sind der Weg, auf dem eine
-Identität überhaupt erst entsteht: ein Gerät koppeln, seine Kassen-Benutzer
-auflisten, einen davon per PIN anmelden. Sie stehen unter `…/register` und
-nehmen deshalb **keine Anmeldung** entgegen, sondern nur die Verbindungsangaben:
+| Call | Proof instead of authentication |
+|---|---|
+| `pairRegisterDevice` | the pairing code from the panel |
+| `listRegisterUsersForDevice`, `listRegisterSessionsForDevice` | the device credentials from pairing |
+| `unpairRegisterDevice` | the device credentials; locks the device in the backend |
+| `registerUserLogin` | device credentials, user and PIN |
+| `registerPinLogin` | device credentials and PIN, without choosing a user |
 
 ```ts
 import { pairRegisterDevice, registerUserLogin } from '@kreiseck/kasseneck-api/register';
 
-const geraet = await pairRegisterDevice({ code: 'K7NPQR34', label: 'Schank' });
-const sitzung = await registerUserLogin({ ...geraet, userId: 'ru-1', pin: '1234' });
+const paired = await pairRegisterDevice({ code: 'K7NPQR34', label: 'Bar' });
+const session = await registerUserLogin({ ...paired, userId: 'ru-1', pin: '1234' });
 ```
 
-Mit `sitzung.customToken` meldet sich der Verbraucher beim Anmeldedienst an; das
-daraus entstehende ID-Token und `sitzung.sessionId` ergeben `registerUserAuth`.
+With `session.customToken` the app signs in to the sign-in service; the
+resulting ID token together with `session.sessionId` feeds `registerUserAuth`.
+`renewRegisterSession` and `endRegisterSession` then run with
+`registerUserAuth` and are also available on `createKasseneckApi`.
 
-Eine anmeldungsfreie Anmeldung gibt es dafür **nicht** — sie wäre ein
-Schlupfloch, mit dem sich jeder andere Aufruf des Pakets ohne Anmeldung bauen
-ließe. Die drei bringen ihren Transport selbst mit.
+The package deliberately exports **no** "empty" authentication: it would be a
+loophole for building every other call without authentication. The six calls
+build their transport internally.
 
-**Welcher Weg für welchen Endpunkt gilt, entscheidet das Backend, nicht dieses
-Paket.** Die Endpunkt-Module nennen im Kommentar jeweils, was dort gilt. Zwei
-Fälle, die regelmäßig überraschen:
+### Which mode works for which endpoint
 
-- `listMyCashregisters` und `listMyReceipts` laufen über den Kunden-Pfad und
-  brauchen ein **ID-Token** — mit `apiKeyAuth` sind sie nicht erreichbar.
-- `getFirstReceiptDate` und die beiden Bericht-Downloads stehen dem
-  Kassen-Benutzer **nicht** offen; sie brauchen `apiKeyAuth`.
+**The backend decides, not this package.** The endpoint modules say in their
+comments what applies. Cases that regularly surprise:
 
-## Beträge sind ganze Cent
+- `listMyCashregisters` and `listMyReceipts` need an **ID token**
+  (`registerUserAuth` works); with `apiKeyAuth` they are not reachable.
+- `getFirstReceiptDate` and the two report downloads (`downloadDailyReport`,
+  `downloadMonthlyReport`) are **not** open to register users; they need
+  `apiKeyAuth`. The same holds for the Stripe and Hobex cloud endpoints.
 
-Geld wird in diesem Paket ausnahmslos als **ganzzahliger Cent-Betrag**
-gerechnet — `priceCents`, `valueCents`, `totalCents`, `amountCents`. Es gibt
-keine Euro-Fließkommazahlen in der Oberfläche. Wo das Backend Euro liefert
-(z. B. `total` in der Belegliste) oder erwartet (Hobex), wird genau an dieser
-Grenze einmal umgerechnet.
+## Amounts are integer cents
 
-Der Grund ist nicht Ordnungsliebe: Netto, Umsatzsteuer und Brutto einer
-Belegzeile müssen sich exakt aufheben, und ein Storno muss seinen Beleg auf den
-Cent spiegeln. Mit Fließkomma geht das in etwa jedem hundertsten Betrag schief.
+In the receipt API, money is always an **integer amount in cents**:
+`priceCents`, `valueCents`, `totalCents`, `amountCents`. Where the backend
+returns euros (for example `total` in the receipt list) or expects them
+(Hobex), the package converts exactly once at that boundary.
 
-Aus demselben Grund ist `quantity` eine **ganze** Menge. Eine gebrochene wird
-abgelehnt, bevor etwas gesendet wird.
+The reason: net, VAT (*USt*) and gross of a receipt line have to add up
+exactly, and a cancellation has to mirror its receipt to the cent. With
+floating point that goes wrong for roughly one amount in a hundred.
 
-## Schnellstart: Beleg verkaufen und drucken
+For the same reason a receipt line's `quantity` is a **whole number**. A
+fractional one is rejected before anything is sent.
 
-```ts
-import {
-  createKasseneckApi,
-  apiKeyAuth,
-  KeckPaymentMethod,
-  VatRate,
-} from '@kreiseck/kasseneck-api';
-import { buildReceiptLayout, renderReceiptGrid, escPosLayoutBytes } from '@kreiseck/kasseneck-api/receipt';
+The invoice API has its own units: unit prices in cents or micro-euros,
+quantities with up to three decimals. See [Invoice API](#invoice-api-rechnung).
 
-const api = createKasseneckApi({
-  auth: apiKeyAuth({ apiKey: 'kr_live_…', cashregisterToken: 'cb_live_…' }),
-});
+## Errors
 
-// Verkaufen — und in einem Aufruf die Firmendaten für den Belegkopf mitnehmen.
-const { receipt, company } = await api.sellReceiptWithCompany({
-  paymentMethod: KeckPaymentMethod.cash,
-  items: [
-    { name: 'Café Latte', quantity: 2, vat: VatRate.vat20, priceCents: 390 },
-    { name: 'Marmeladeweckerl', quantity: 1, vat: VatRate.vat10, priceCents: 250 },
-  ],
-  // Trinkgeld in Cent (optional): das Backend bucht daraus eine signierte
-  // Position „Trinkgeld“ — Mitarbeiter 0 % als Durchläufer, Inhaber als Umsatz.
-  // Als Objekt mit eigener Zahlart/Empfängern: { cents, paymentMethod, recipients }.
-  tip: 100,
-});
+A failure always arrives as a **thrown error**, never as a return value; you
+never check a `status` field yourself. There are five error classes, each with
+a type guard:
 
-// Layout bauen (reines Datenmodell: Zeilen, Ausrichtung, Spalten, QR-Code) …
-// Layout-Regelwerk: gespeicherte Belege tragen ihre Version (`layoutRegeln`);
-// ohne Angabe gilt das aktuelle (2: Nullbelege mit Block „Prüfangaben“ —
-// die Registrierdaten dafür liefert `getReceiptWithCompany` als `pruefangaben`).
-const layout = buildReceiptLayout(receipt, company, { paperSize: 'mm58' });
+| Class | Guard | Meaning |
+|---|---|---|
+| `KasseneckApiError` | `isKasseneckApiError` | The backend received the request and rejected it (locked register, missing module, invalid parameter). Retrying does not help. Carries `code` (where the endpoint defines one), `serverMessage` (German display text) and `details`. |
+| `KasseneckHttpError` | `isKasseneckHttpError` | The response was not a usable envelope: HTTP 404/500, empty body, HTML instead of JSON. `reason` tells the cases apart. |
+| `KasseneckNetworkError` | `isKasseneckNetworkError` | No response at all: network down, DNS, aborted connection or timeout (`timedOut`). |
+| `KasseneckAuthError` | `isKasseneckAuthError` | The request was never sent because authentication failed (missing credentials, or the token or session provider threw). |
+| `KasseneckValidationError` | `isKasseneckValidationError` | Wrong shape. `scope: 'request'`: your input breaks a rule the package knows before sending. `scope: 'response'`: the backend reported success but the payload lacked what the call promises. |
 
-// … das Zeichenraster (exakt 32/48 Zeichen je Zeile — die eine Wahrheit für
-// Bildschirm, Bondruck und PDF: Spalten in ganzen Zeichen, rechte Spalte bündig,
-// wortweiser Umbruch) …
-const grid = renderReceiptGrid(layout);          // grid.lines[i].text, .bold, .kind, .qr
+**None of them ever contains a secret**: no key, no token, neither the sent nor
+the received body.
 
-// … und daraus die Bytes für den Bondrucker (druckt genau die Rasterzeilen).
-// Der Transport zum Drucker ist bewusst nicht Teil dieses Pakets.
-const bytes = escPosLayoutBytes(layout);
-```
+**Decide on the code, not the text.** Where an endpoint has a catalogue of
+error codes (cancellation, receipt email, partner and invoice API), branch on
+`error.code`. The German `serverMessage` is for display and may change.
+
+## Receipts
+
+The facade from `createKasseneckApi` offers `sellReceipt` and
+`sellReceiptWithCompany`, `zeroReceipt` for a zero receipt (*Nullbeleg*),
+`getReceipt` and `getReceiptWithCompany`, `listMyReceipts`, `cancelReceipt`,
+`sendReceiptEmail`, the report downloads, the FinanzOnline status queries
+(`getCashboxStatus`, `getSignatureStatus`) and the Stripe and Hobex cloud
+payments.
+
+**Layout rule sets.** `buildReceiptLayout` sets receipts according to a
+numbered rule set. Without the `regelwerk` option the current one applies
+(`AKTUELLES_REGELWERK`, currently 2: zero receipts carry a block
+"Prüfangaben" with the registration data, which `getReceiptWithCompany`
+returns as `pruefangaben`). The backend stores the rule set with each receipt,
+and `getReceiptWithCompany` also returns the backend-built `layout` in that
+rule set, so an old receipt looks the way it did when it was issued.
 
-Ein Misserfolg kommt immer als **geworfener Fehler**, nie als Rückgabewert;
-niemand muss selbst auf ein `status`-Feld prüfen. Es gibt fünf Fehlerarten mit
-je einem Wächter (`isKasseneckApiError` und Geschwister): fachlicher Fehler,
-HTTP-/Formfehler, Netz-/Zeitfehler, Anmeldefehler, Formfehler der Ein- oder
-Ausgabe. **In keinem davon steht je ein Geheimnis** — weder Schlüssel noch
-Token, weder gesendete noch empfangene Rümpfe.
+Times on receipts are read as **Vienna wall-clock time**
+(`parseServerTimeStamp`), never through `new Date(text)`.
 
-## Storno: voll oder in Teilen
+## Cancellation (Storno)
+
+A cancellation (*Storno*) refers to the original receipt, in full or in part:
 
 ```ts
-const ergebnis = await api.cancelReceipt({
-  receipt: beleg,                       // oder: cashregisterId + originalReceiptId
-  reason: 'fehleingabe',                // Katalog: CANCELLATION_REASONS
-  items: [{ index: 0, quantity: 1 }],   // weglassen = Vollstorno der Restmengen
-  note: 'Kunde wollte nur eine',        // intern, wird nie gedruckt
+const result = await api.cancelReceipt({
+  receipt: original,                    // or: cashregisterId + originalReceiptId
+  reason: 'fehleingabe',                // catalogue: CANCELLATION_REASONS
+  items: [{ index: 0, quantity: 1 }],   // omit = cancel all remaining quantities
+  note: 'Customer only wanted one',     // internal, stored, never printed
 });
-ergebnis.receipt;         // der signierte Storno-Beleg (receiptType cancellation)
-ergebnis.cancellationOf;  // Bezug auf das Original
-ergebnis.remaining;       // Restmengen des Originals danach
+result.receipt;         // the signed cancellation receipt (receiptType cancellation)
+result.cancellationOf;  // reference to the original
+result.remaining;       // remaining quantities of the original afterwards
 ```
 
-**Veraltet:** `createCancelReceipt` (Storno über `createReceipt` mit frei
-übergebenen, negierten Positionen) bleibt aus Kompatibilität erreichbar, ist aber
-`@deprecated` — kein Bezug zum Original, keine Restmengen, kein Schutz vor
-doppeltem Storno, keine Gutscheine. Das Backend legt bei diesem Weg
-`deprecation` in die Antwort.
-
-Der Server negiert die Positionen, prüft Restmengen und Rechte („nur eigene
-Belege" oder „alle") und verkettet Original und Storno. Ein Storno-Beleg lässt
-sich nicht stornieren, ein voll stornierter Beleg nicht noch einmal. Am
-gelesenen Original liefert `remainingQuantities(receipt)` die Reste vorab (für
-den Storno-Dialog); die Wahrheit hat der Server.
+The server negates the lines, checks remaining quantities and permissions
+("own receipts only" or "all") and chains original and cancellation.
+Cancellation, zero, start and training receipts cannot be cancelled, and a
+fully cancelled receipt cannot be cancelled again. On a receipt you have read,
+`remainingQuantities(receipt)` gives the remaining quantities up front (for the
+cancellation dialog); the server has the final word.
 
-**Fehler entscheidet man am Code, nicht am Text.** Jeder fachliche Fehler von
-`cancelReceipt` trägt `KasseneckApiError.code` aus `CANCELLATION_ERROR_CODES`
-(z. B. `bereits_storniert`, `menge_ueber_rest`, `nur_eigene_belege`). Die
-deutsche Meldung (`serverMessage`) ist Anzeige und darf sich ändern.
+Every business error of `cancelReceipt` carries `KasseneckApiError.code` from
+`CANCELLATION_ERROR_CODES` (for example `bereits_storniert`,
+`menge_ueber_rest`, `nur_eigene_belege`):
 
 ```ts
 import { isKasseneckApiError, isCancellationErrorCode } from '@kreiseck/kasseneck-api';
 
 try {
-  await api.cancelReceipt({ receipt: beleg, reason: 'fehleingabe' });
-} catch (fehler) {
-  if (isKasseneckApiError(fehler) && isCancellationErrorCode(fehler.code)) {
-    switch (fehler.code) {
-      case 'bereits_storniert':  // Beleg im Dialog als „storniert" zeigen, Knopf sperren
-      case 'menge_ueber_rest':   // Restmengen neu laden (jemand war schneller)
-      case 'nur_eigene_belege':  // Chef holen
-        break;
-    }
+  await api.cancelReceipt({ receipt: original, reason: 'fehleingabe' });
+} catch (error) {
+  if (!isKasseneckApiError(error) || !isCancellationErrorCode(error.code)) throw error;
+  switch (error.code) {
+    case 'bereits_storniert':  // show the receipt as cancelled, disable the button
+    case 'menge_ueber_rest':   // reload the remaining quantities (someone was faster)
+    case 'nur_eigene_belege':  // ask a manager
+      showHint(error.code);
+      break;
+    default:
+      throw error;
   }
-  throw fehler;
 }
 ```
 
-**Gutscheine.** Ein Wertgutschein wird nur beim Vollstorno (ohne `items`)
-gespiegelt — er ist unteilbar. Ein Rabattgutschein ist am Original bereits in
-den Umsatz eingerechnet; **jeder** Storno nimmt ihn anteilig der stornierten
-Menge zurück: bei 3 Stück à 10 € mit 6 € Rabatt sind 8 € je Stück Entgelt, der
-Storno-Beleg trägt dann „−10,00" plus eine Zeile „Gutschein-Ausgleich +2,00".
-Was ein Storno gewährt hat, steht am Eintrag in `receipt.cancellations[]` als
-`promoAdjustmentCents` (Cent je Steuertopf) — die Kasse kann es im Dialog
-zeigen, rechnen muss sie nichts.
+**Deprecated:** `createCancelReceipt` (cancellation through `createReceipt`
+with freely passed, negated lines) remains available for compatibility but is
+`@deprecated`: no reference to the original, no remaining quantities, no
+protection against double cancellation, no voucher handling. The backend adds
+`deprecation` to its response on this path.
+
+**Vouchers.** A value voucher is only mirrored on a full cancellation (without
+`items`); it cannot be split. A discount voucher is already part of the
+original's turnover, and **every** cancellation takes it back in proportion to
+the cancelled quantity. Example: 3 items at € 10 with a € 6 discount means € 8
+was paid per item, so the cancellation receipt shows "−10,00" plus a line
+"Gutschein-Ausgleich +2,00". What a cancellation granted is stored on its entry
+in `receipt.cancellations[]` as `promoAdjustmentCents` (cents per VAT bucket
+of the backend). The register can show it in the dialog; it does not have to
+calculate anything.
+
+**Printed receipt.** The header of a cancellation receipt names the original,
+its date and the reason: "STORNOBELEG / Stornobuchung zu Beleg KASSE1-ID-42 /
+vom 11.08.2026, 09:02 Uhr / Grund: Fehleingabe". The date comes from
+`cancellationOf.timeStamp` (backend since 2026-09-04); older receipts without
+it omit that line.
+
+## Sending a receipt by email
+
+```ts
+const confirmation = await api.sendReceiptEmail({
+  fullReceiptId: original.fullReceiptId, // or: await api.generateFullReceiptId(receiptId)
+  to: 'guest@example.at',
+  sprache: 'de',                         // optional; the backend currently only uses 'de'
+});
+confirmation.to;   // address as the backend logged it (trimmed, lower case)
+confirmation.at;   // time, ISO with Vienna offset
+confirmation.via;  // 'eigen' | 'plattform' | 'plattform-fallback' | null
+```
+
+The email contains a **link to the public receipt page**, not a PDF
+attachment: the receipt page uses the same line model as screen and printed
+receipt and offers a PDF there. The receipt itself stays untouched (BAO § 131,
+RKSV); the backend keeps the sending log next to it.
+
+The cash register comes from the authentication (`cashregister-token` header or
+the parameter set by `registerUserAuth`), not from the options. A receipt of
+another register therefore gets the same answer as a receipt that does not
+exist. The codes are in `RECEIPT_EMAIL_ERROR_CODES` (`isReceiptEmailErrorCode`):
+`adresse_ungueltig`, `beleg_nicht_gefunden`, `zu_oft` (5 emails per receipt in
+24 hours, 30 per register per hour) and `versand_fehlgeschlagen`.
 
-**Bon.** Der Kopfblock des Storno-Bons nennt Bezug, Datum des Originals und
-Grund: „STORNOBELEG / Stornobuchung zu Beleg KASSE1-ID-42 / vom 11.08.2026,
-09:02 Uhr / Grund: Fehleingabe". Das Datum kommt aus `cancellationOf.timeStamp`
-(Backend seit 2026-09-04); Altbelege ohne bleiben ohne die Zeile.
+## Receipt printing: QR code, logo, printers
 
-## Beleg per E-Mail an den Gast
+### The QR code fits the paper
+
+The native QR command is given a module size in dots and does not check
+whether the symbol plus quiet zone fits the roll. Too wide means, on most
+thermal printers, not "cut off" but **no QR code at all**: on a mandatory
+receipt the worst possible result. So this package calculates the size instead
+of setting it:
 
 ```ts
-const bestaetigung = await api.sendReceiptEmail({
-  fullReceiptId: beleg.fullReceiptId,   // oder api.generateFullReceiptId(receiptId)
-  to: 'gast@example.at',
-  sprache: 'de',                        // optional; heute wertet das Backend nur 'de' aus
+import { qrGroesseFuer, QR_DRUCK_PUNKTE } from '@kreiseck/kasseneck-api/printing';
+
+const qrSize = qrGroesseFuer({ nutzlast: receipt.qr, papierbreitePunkte: QR_DRUCK_PUNKTE.mm58 });
+// qrSize.punkte: dots per module; null = does not fit even with the exception size
+// qrSize.unterMindestmass: printed, but below 4 dots per module
+```
+
+On the receipt path this happens automatically. `qrGroesse` is a **cap**, not
+a target: the largest size that fits is printed, at most the cap. `auto` (the
+default) caps at 6 dots per module, as in the Dart twin and on the Epson path;
+`klein` caps at 4, `mittel` at 6, `gross` at 8. All print paths use error
+correction level M.
+
+```ts
+import { escPosLayoutErgebnis } from '@kreiseck/kasseneck-api/receipt';
+
+const { bytes, qrFehler, qrAusweich } = escPosLayoutErgebnis(layout, {
+  qrGroesse: 'gross',        // 'auto' | 'klein' | 'mittel' | 'gross'
+  qrModus: 'nativeModel1',   // older printers that only support model 1
+  qrMatrix: matrixFor,       // fallback: the QR code as an image instead of none
 });
-bestaetigung.to;   // Adresse, wie das Backend sie protokolliert hat
-bestaetigung.at;   // Zeitpunkt, ISO mit Wiener Zonenoffset
-bestaetigung.via;  // 'eigen' | 'plattform' | 'plattform-fallback' | null
 ```
 
-Verschickt wird ein **Link auf die öffentliche Belegseite**, kein PDF im
-Anhang: die Belegseite führt dasselbe Zeilenmodell wie Bildschirm und Bon und
-liefert dort auf Wunsch ein PDF. Der Beleg selbst bleibt unberührt (BAO §131 /
-RKSV) — das Versandprotokoll führt das Backend neben ihm.
+The Epson ePOS path (`eposPrintXml` / `eposDirectPrint`) calculates the same
+way; `eposPrintXmlErgebnis` returns `{ xml, qrFehler, qrAusweich }`. The default
+there is also `auto`.
 
-Die Kasse kommt aus der Anmeldung (Kopfzeile `cashregister-token` bzw. der
-Parameter, den `registerUserAuth` setzt), nicht aus den Optionen; ein Beleg
-einer anderen Kasse ist deshalb dieselbe Auskunft wie ein Beleg, den es nicht
-gibt. Auch hier gilt: **am Code entscheiden, nicht am Text.** Die Codes stehen
-in `RECEIPT_EMAIL_ERROR_CODES` (`isReceiptEmailErrorCode`):
-`adresse_ungueltig`, `beleg_nicht_gefunden`, `zu_oft` (5 Mails je Beleg in 24
-Stunden, 30 je Kasse und Stunde) und `versand_fehlgeschlagen`.
+`qrFehler` means "receipt without QR code": tell the customer. `qrAusweich`
+means "printed, but the configured mode does not suit this device": tell the
+manager. The image fallback only runs with a `qrMatrix` function that turns
+the payload into a finished matrix; the package itself neither encodes QR
+codes nor processes images for it.
 
-## Partner-API (`./partner`)
+### The receipt sheet: the same receipt everywhere
 
-Für Softwarehäuser, die Kasseneck in ihr eigenes Produkt einbauen: Betriebe
-anlegen, bis zur laufenden Kasse begleiten und danach in ihrem Namen Belege
-signieren.
+Screen, ESC/POS, ePOS and PDF all set the same **sheet**: grid lines, company
+logo, QR code and the Kasseneck logo at the end, with sizes as a share of the
+sheet width and in lines (one line = two character widths).
 
-**Was die Endpunkte tun, steht in der Referenz** —
-`docs/api/partner.md` (ausführlich) und `docs/api/partner.llms.txt` (kompakt,
-für Werkzeuge und Sprachmodelle). Dieses README wiederholt sie nicht; hier
-steht, wie man den Client benutzt.
+```tsx
+import { BelegBlattView } from '@kreiseck/kasseneck-api/react';
 
-Der Partner-Schlüssel (`pk_live_…`) gehört auf einen **Server**. Er kann
-Betriebe anlegen und — mit dem Zusatz-Scope `credentials:read` — deren
-Geheimnisse holen.
+const { receipt, company, logoStufe } = await api.getReceiptWithCompany(receiptId);
+const layout = buildReceiptLayout(receipt, company);
+
+<BelegBlattView
+  layout={layout}
+  logo={company.logoUrl ? { url: company.logoUrl, stufe: logoStufe } : null}
+  marke={company.showKreiseckLogo}
+  renderQr={(data) => <QrSvg data={data} />}
+/>
+```
+
+```ts
+import { escPosLayoutBytes, logoMass, logoRaster } from '@kreiseck/kasseneck-api/receipt';
+
+const logoSize = logoMass({ stufe: 'M', pxBreite: image.width, pxHoehe: image.height }, 48);
+const raster = logoRaster(imageData.data, image.width, image.height, logoSize, 48);
+escPosLayoutBytes(layout, { paperSize: 'mm80', logo: { stufe: 'M', pxBreite: image.width, pxHoehe: image.height, raster }, marke: true });
+```
+
+Logo sizes: S 42 % × 5 lines, M 62 % × 8, L 80 % × 12, XL 94 % × 16, always
+fitted, never scaled up. Banners (TESTKASSE, STORNOBELEG, …) are framed by
+`=` lines, the same on every path. The package rasterises finished RGBA pixels;
+loading and decoding the image (PNG, JPEG) stays with your application.
+
+### Getting the bytes to the printer
+
+The package generates ESC/POS bytes and ePOS XML, and it ships three ways to
+deliver them: **WebUSB** (`usbConnectPrinter`, `usbPrint` in `…/printing`, for
+Chromium-based browsers), **Epson ePOS over HTTP** (`eposDirectPrint` in
+`…/receipt`) and **print jobs** for network printers managed by the backend
+(`listMyPrinters`, `createPrintJob` in `…/kasse`). Bluetooth, serial ports and
+raw TCP sockets are up to your application. PDF generation is not part of the
+package.
+
+## Card payments
+
+`…/payments` covers three ways to take card payments from a browser or a Node
+process:
+
+- **Stripe payment links** (`createStripeLink`, `stripeCaptureIntent`): remote
+  payment by link or QR code, through the backend.
+- **Hobex cloud** (`hobexPay`, `hobexRefund`): a terminal registered with
+  Hobex, controlled over the network through the backend. Amounts are passed in
+  cents; the package converts to euros for Hobex.
+- **Hobex HPS via Kasseneck Connect**, described below.
+
+### Hobex HPS via Kasseneck Connect
+
+A browser has no raw TCP sockets, so **direct** terminal contact as in the
+Flutter package `kasseneck_api` (`HpsClient`) stays out of reach of this
+package. **Kasseneck Connect** is a local device agent with a plain HTTP
+interface that talks to the terminal on behalf of the register, and that is
+the way in:
+
+```ts
+import { createHpsConnectClient, createHpsPayments } from '@kreiseck/kasseneck-api/payments';
+
+const client = createHpsConnectClient({ token: pairingToken });
+const terminal = createHpsPayments(client, { host: '192.168.1.50', tid: '3600335' });
+
+const payment = await terminal.pay({ amountCents: 1050 });
+// payment.outcome: 'approved' | 'declined' | 'unresolved', never guessed.
+// payment.transactionId is ALWAYS set, also for 'unresolved'.
+
+// Refund, and void of an earlier payment, work the same way:
+await terminal.refund({ amountCents: 1050, originalTransactionId: payment.transactionId });
+await terminal.cancel({ transactionId: payment.transactionId, amountCents: 1050 });
+```
+
+The outcome is always one of three: `approved`, `declined` (provably nothing
+charged) or `unresolved` (outcome unknown; a retry could charge a second time).
+What that means and why it is built this way is documented in
+`src/payments/hobex-hps/payments.ts`; that documentation is authoritative, not
+this README.
+
+Terminals that can only be driven through a vendor's Android SDK cannot be
+reached from a browser and are not part of this package.
+
+## Partner API (`./partner`)
+
+For software vendors who build Kasseneck into their own product: create
+businesses, accompany them until the cash register is live, and then sign
+receipts on their behalf.
+
+The partner key (`pk_live_…`) belongs on a **server**. It can create
+businesses and, with the extra scope `credentials:read`, fetch their secrets.
 
 ```ts
 import { createPartnerApi, istPartnerFehler } from '@kreiseck/kasseneck-api/partner';
@@ -331,78 +544,76 @@ const partner = createPartnerApi({ partnerKey: process.env.KASSENECK_PARTNER_KEY
 
 const { customerId } = await partner.createPartnerCustomer({
   appId: 'app_…',
-  idempotencyKey: kundennummer,   // die eigene — schützt vor Doppelanlage
-  betrieb: { /* Stammdaten, siehe Referenz */ } as never,
-  // env: 'test' — auch mit einem LIVE-Schlüssel erlaubt: so probt man die
-  // ganze Kette, ohne sich einen zweiten Schlüssel zu holen. Umgekehrt nie.
+  idempotencyKey: customerNumber, // your own number; protects against duplicates
+  business,                       // master data (type Betrieb): name, legal form, address, tax details, contacts
+  // env: 'test' is allowed even with a LIVE key: that is how you rehearse the
+  // whole chain without a second key. Never the other way round.
 });
 
 await partner.sendPartnerCustomerFonLink(customerId);
-// … auf das Ereignis customer.fon_verified warten …
+// … wait for the event customer.fon_verified …
 await partner.requestCustomerSignature(customerId);
-// … auf signature.ready warten …
-await partner.createCustomerCashregister({ customerId });  // automatisch:true ist Vorgabe
+// … wait for signature.ready …
+await partner.createCustomerCashregister({ customerId });  // automatic: true is the default
 ```
 
-Die Reihenfolge ist hart, und jeder Schritt beschwert sich mit einem eigenen
-Code, wenn ein vorheriger fehlt. Sie steht als Daten im Paket
-(`PARTNER_ABLAUF`), und zu jedem Code gibt es einen Handlungssatz:
+The order is strict, and each step complains with its own code if an earlier
+one is missing. The order ships as data (`PARTNER_ABLAUF`), and for every code
+there is an action hint:
 
 ```ts
 try {
   await partner.activateCashregister(customerId, cashregisterId);
-} catch (fehler) {
-  if (istPartnerFehler(fehler, 'signature_not_ready')) {
-    // Die Signatur DIESER Kasse ist noch nicht bereit — auf signature.ready warten.
+} catch (error) {
+  if (istPartnerFehler(error, 'signature_not_ready')) {
+    // The signature of THIS register is not ready yet: wait for signature.ready.
     console.error(partner.fehlerRat('signature_not_ready'));
   }
 }
 ```
 
-### Eine Probe ist keine Kasse
+### A test event is not a cash register
 
-`sendPartnerWebhookTest(webhookId, 'cashregister.live')` löst genau das
-Ereignis aus, das der eigene Handler behandeln soll — eine Leitungsprobe
-beweist nichts über die Behandlung des Ernstfalls. Damit niemand eine Probe
-für echt hält, trägt sie `test: true` im Umschlag:
+`sendPartnerWebhookTest(webhookId, 'cashregister.live')` fires exactly the
+event your handler is meant to handle; a mere connectivity check proves
+nothing about handling the real case. So that nobody takes a test for real, it
+carries `test: true` in the envelope:
 
 ```ts
-const geprueft = await parseWebhookEvent({ secret, signatureHeader, body, });
-if (!geprueft.ok) return antwort(400);
+const checked = await parseWebhookEvent({ secret, signatureHeader, body });
+if (!checked.ok) return reply(400);
 
-if (geprueft.event.test) return antwort(200);   // Probe: nichts weiter tun
+if (checked.event.test) return reply(200);   // test event: do nothing else
 ```
 
-Ohne diese Zeile schreibt jemand seinem Kunden, die Kasse sei fertig.
+Without that line someone tells their customer the register is ready.
 
-### Zugangsdaten sind Geheimnisse eines Dritten
+### Credentials are a third party's secrets
 
-`getCustomerCredentials` liefert den `api_key` des Betriebs und die Token
-seiner Kassen. Wer sie hat, kann in seinem Namen Belege signieren — und ein
-Beleg ist nach RKSV nicht zurücknehmbar. Sie kommen deshalb **nicht als
-`string`**, sondern in einer Hülle, die sich nicht versehentlich ausgeben
-lässt:
+`getCustomerCredentials` returns the business's `api_key` and the tokens of its
+cash registers. Whoever holds them can sign receipts in its name, and under the
+RKSV a receipt cannot be taken back. They therefore do **not** come as
+`string`, but in a wrapper that cannot be printed by accident:
 
 ```ts
-const zugang = await partner.getCustomerCredentials(customerId);
+const credentials = await partner.getCustomerCredentials(customerId);
 
-console.log(zugang);                     // [apiKey «verborgen»] — kein Klartext
-JSON.stringify(zugang);                  // ebenso
-`${zugang.apiKey}`;                      // ebenso
+console.log(credentials.apiKey);          // [apiKey «verborgen»], no plain text
+JSON.stringify(credentials);              // every secret inside is masked the same way
+`${credentials.apiKey}`;                  // same
 
-speichereVerschluesselt(zugang.apiKey.reveal());   // der einzige Weg heraus
+storeEncrypted(credentials.apiKey.reveal());   // the only way out
 ```
 
-Nur verschlüsselt speichern, nie protokollieren, nie in eine Mail oder einen
-Fehlerbericht. Jeder Abruf wird mitgeschrieben und ist für den Betrieb
-sichtbar.
+Store them encrypted only, never log them, never put them in an email or an
+error report. Every fetch is recorded and visible to the business.
 
-### Eingehende Webhooks prüfen
+### Verifying incoming webhooks
 
-Das ist die Stelle, an der Integrationen am häufigsten scheitern — deshalb
-liegt sie fertig im Paket. Vier Dinge müssen stimmen: der **rohe** Rumpf, das
-Zeitfenster gegen Wiedereinspielung, ein zeitkonstanter Vergleich, und jede
-Ausnahme als Ablehnung.
+This is where integrations fail most often, so it ships ready-made. Four
+things must hold: the **raw** body, a time window against replays (300 seconds
+by default), a constant-time comparison, and every exception treated as a
+rejection.
 
 ```ts
 import express from 'express';
@@ -410,435 +621,338 @@ import { parseWebhookEvent } from '@kreiseck/kasseneck-api/partner';
 
 const app = express();
 
-// express.raw VOR jedem JSON-Parser: signiert sind die Bytes, die ankommen.
+// express.raw BEFORE any JSON parser: the signature covers the bytes as received.
 app.post('/kasseneck-webhook', express.raw({ type: '*/*' }), async (req, res) => {
-  const ergebnis = await parseWebhookEvent({
+  const result = await parseWebhookEvent({
     secret: process.env.KASSENECK_WEBHOOK_SECRET!,
     signatureHeader: req.header('X-Kasseneck-Signature'),
-    body: req.body,           // Buffer — nicht req.body nach JSON.parse
+    body: req.body,           // Buffer, not req.body after JSON.parse
   });
-  if (!ergebnis.ok) return res.status(400).send(ergebnis.reason);
+  if (!result.ok) return res.status(400).send(result.reason);
 
-  // Innerhalb von 10 s antworten, Arbeit danach. Zustellungen können sich
-  // wiederholen: auf event.id entdoppeln.
+  // Answer within 10 s, work afterwards. Deliveries can repeat:
+  // deduplicate on event.id.
   res.sendStatus(200);
-  await verarbeite(ergebnis.event);
+  await handle(result.event);
 });
 ```
 
-## Rechnungs-API (`./rechnung`)
-
-Für Shops, Buchhaltungs- und Branchensoftware: **Rechnungen** (§ 11 UStG) —
-keine Belege — mit dem `api_key` eines Kontos ausstellen. Eine Rechnung ist
-nach dem Aufruf **festgeschrieben**: sie trägt ihre fortlaufende Nummer, ist
-unveränderlich und lässt sich nur noch per Gutschrift korrigieren.
+## Invoice API (`./rechnung`)
 
-**Was die Endpunkte tun, steht in der Referenz** — `docs/api/rechnungen.md`
-im Backend. Hier steht, wie man den Client benutzt. Der Schlüssel gehört auf
-einen **Server**.
+For shops, accounting and industry software: issue **invoices** (*Rechnung*,
+§ 11 UStG), not receipts, with the `api_key` of an account. An invoice is
+**finalised** by the call: it carries its sequential number, cannot be changed
+and can only be corrected by a credit note. The key belongs on a **server**.
 
 ```ts
 import { createRechnungApi, istRechnungFehler } from '@kreiseck/kasseneck-api/rechnung';
 
-const rechnungen = createRechnungApi({ apiKey: process.env.KASSENECK_API_KEY! });
+const invoices = createRechnungApi({ apiKey: process.env.KASSENECK_API_KEY! });
 
-// 1. Kunde einmal anlegen — externalId ist die eigene Kundennummer.
-let kunde;
+// 1. Create the customer once; externalId is your own customer number.
+let customer;
 try {
-  kunde = await rechnungen.createCustomer({
+  customer = await invoices.createCustomer({
     type: 'company', name: 'Café Muster GmbH', country: 'AT',
     street: 'Hauptplatz', houseNumber: '3', zip: '1010', city: 'Wien',
     externalId: 'shop-4711',
   });
-} catch (fehler) {
-  if (!istRechnungFehler(fehler, 'customer_exists')) throw fehler;
-  kunde = await rechnungen.getCustomer({ externalId: 'shop-4711' });
+} catch (error) {
+  if (!istRechnungFehler(error, 'customer_exists')) throw error;
+  customer = await invoices.getCustomer({ externalId: 'shop-4711' });
 }
 
-// 2. Ausstellen. Beträge in ganzen Cent; das Rechnungsdatum setzt der Server.
-const { invoice, replayed } = await rechnungen.issueInvoice({
-  idempotencyKey: `bestellung-${bestellnummer}`,   // gleiche Bestellung = gleiche Rechnung
-  customerId: kunde.id,
-  taxScheme: 'normal',
+// 2. Issue. The server sets the invoice date and derives the tax case.
+const { invoice, replayed } = await invoices.issueInvoice({
+  idempotencyKey: `order-${orderNumber}`,   // same order = same invoice
+  customerId: customer.id,
   priceMode: 'net',
   serviceStart: '2026-09-14',
-  items: [{ description: 'Beratung', quantity: 2, unit: 'Std', unitPriceCents: 5000, vatRate: 20 }],
+  items: [{ description: 'Consulting', quantity: 2, unit: 'hour', unitPriceCents: 5000, vatRate: 20 }],
 });
 // invoice.number, invoice.totals.grossCents (12000), invoice.statusUrl
 
-// 3. Dateien holen.
-const pdf = await rechnungen.getInvoicePdf(invoice.id);      // Uint8Array, mit Factur-X
-const xml = await rechnungen.getInvoiceXml(invoice.id, 'ubl'); // Peppol-UBL als Text
+// 3. Fetch the files.
+const pdf = await invoices.getInvoicePdf(invoice.id);      // Uint8Array, with Factur-X
+const xml = await invoices.getInvoiceXml(invoice.id, 'ubl'); // Peppol UBL as text
 
-// 4. Korrigieren — nur per Gutschrift.
-await rechnungen.createCreditNote({
-  idempotencyKey: `nachlass-${bestellnummer}`,
+// 4. Correct, only by credit note.
+await invoices.createCreditNote({
+  idempotencyKey: `discount-${orderNumber}`,
   invoiceId: invoice.id,
   reason: 'price_reduction',
-  items: [{ description: 'Nachlass Beratung', quantity: 1, unitPriceCents: 2000, vatRate: 20 }],
+  items: [{ description: 'Discount on consulting', quantity: 1, unitPriceCents: 2000, vatRate: 20 }],
 });
 ```
 
-**Vor dem ersten Ausstellen die Einrichtung abfragen.** Die Rechnungs-API muss
-für das Konto von Kasseneck freigegeben sein (live), und Firmenname, Anschrift,
-UID, Bankverbindung und Nummernformat müssen stehen — sonst antwortet
-`issueInvoice` mit `invoice_api_not_enabled` bzw. `invoice_setup_incomplete`:
+**Prices and quantities.** Each line takes exactly one of `unitPriceCents`
+(whole cents) and `unitPriceMicros` (micro-euros, 10⁻⁶ €, for prices below one
+cent), in the invoice's `priceMode` (net or gross). `quantity` allows up to
+three decimals, `discountPct` up to two. `taxScheme` is optional: the server
+derives the tax case and checks a given value against it.
+
+**Check the setup before the first invoice.** The invoicing module must be
+active, the invoice API enabled for the account by Kasseneck, the account live,
+and company name, address, VAT ID, bank account and number format must be
+filled in. Otherwise `issueInvoice` answers with `invoice_api_not_enabled` or
+`invoice_setup_incomplete`:
 
 ```ts
-const status = await rechnungen.getInvoiceSetupStatus();
+const status = await invoices.getInvoiceSetupStatus();
 if (!status.ready) console.warn(status.missing.map((m) => m.message).join('\n'));
 ```
 
-**Sprache und Marke.** Eine Rechnung hat eine Nummer und **eine** Sprache (`de`
-oder `en`, `INVOICE_LANGUAGES`): die der Anfrage, sonst die des Kunden
-(`customer.language`), sonst Deutsch. Sie wird beim Ausstellen eingefroren;
-Gutschriften übernehmen Sprache und Marke ihrer Rechnung. Behörden bekommen
-immer Deutsch (`language_not_allowed`). Datum und Beträge bleiben in jeder
-Sprache österreichisch formatiert.
+**Language and brand.** An invoice has one number and **one** language (`de`
+or `en`, `INVOICE_LANGUAGES`): the one in the request, otherwise the customer's
+(`customer.language`), otherwise German. It is frozen when the invoice is
+issued; credit notes take over language and brand of their invoice. Public
+authorities always get German (`language_not_allowed`). Dates and amounts keep
+Austrian formatting in every language.
 
 ```ts
-const [marke] = await rechnungen.listBrands();              // [{ id, name, isDefault }]
-const { invoice } = await rechnungen.issueInvoice({
-  idempotencyKey: `bestellung-${bestellnummer}`,
-  customerId: kunde.id,
-  taxScheme: 'normal', priceMode: 'net', serviceStart: '2026-09-15',
-  language: 'en',                                          // sonst die Sprache des Kunden
-  brandId: marke.id,                                       // sonst die Standardmarke
+const [brand] = await invoices.listBrands();                // [{ id, name, isDefault }]
+const { invoice } = await invoices.issueInvoice({
+  idempotencyKey: `order-${orderNumber}`,
+  customerId: customer.id,
+  priceMode: 'net', serviceStart: '2026-09-15',
+  language: 'en',                                           // otherwise the customer's language
+  brandId: brand.id,                                        // otherwise the default brand
   items: [{ description: 'Consulting', quantity: 2, unitPriceCents: 5000, vatRate: 20 }],
 });
-// Dieselbe Rechnung als deutsche Übersetzung — KEINE zweite Rechnung:
-const kopie = await rechnungen.getInvoicePdf(invoice.id, { language: 'de' });
+// The same invoice as a German translation, NOT a second invoice:
+const copy = await invoices.getInvoicePdf(invoice.id, { language: 'de' });
 ```
 
-Die Übersetzungskopie trägt dieselbe Nummer, ist auf jeder Seite als
-„Übersetzung – keine eigene Rechnung" gekennzeichnet und hat keine eingebettete
-E-Rechnung. Eine zweite Rechnung mit eigener Nummer für dieselbe Leistung
-wäre umsatzsteuerlich ein Problem (UStR Rz 1527); die Kopie ist das nicht (Rz 1528).
-Die Texte beider Sprachen liegen als `RECHNUNG_TEXTE` bzw.
-`fixtures/rechnung-texte.json` im Paket.
+The translated copy carries the same number, is marked on every page as a
+translation that is not an invoice of its own ("Übersetzung – keine eigene
+Rechnung"), and has no embedded e-invoice. The texts of both languages ship as
+`RECHNUNG_TEXTE` and `fixtures/rechnung-texte.json`.
 
-**Einheiten sind Schlüssel, kein freier Text.** `items[].unit` nimmt einen Wert aus
-`INVOICE_UNITS` (`piece`, `hour`, `day`, `flat_rate`, `kilogram`, `square_metre`, …;
-ohne Angabe `piece`). Gedruckt wird das Kürzel in der Sprache der Rechnung — `Stk`
-bzw. `pcs` —, und die E-Rechnung trägt den UN/ECE-Code aus
-`RECHNUNG_EINHEITEN_CODES` (`C62`, `HUR`, …). Freier Text wie `"Std"` ist
-`validation` mit Feld `items[0].unit`.
+**Units are keys, not free text.** `items[].unit` takes a value from
+`INVOICE_UNITS` (`piece`, `hour`, `day`, `flat_rate`, `kilogram`,
+`square_metre`, …; default `piece`). The printed abbreviation follows the
+invoice language (`Stk` or `pcs`), and the e-invoice carries the UN/ECE code
+from `RECHNUNG_EINHEITEN_CODES` (`C62`, `HUR`, …). Free text such as `"Std"` is
+a `validation` error on field `items[0].unit`.
 
-**Schon bezahlt?** Wer online kassiert und danach die Rechnung stellt, gibt die
-Zahlung gleich mit: sie entsteht in derselben Transaktion wie das Festschreiben,
-und das PDF trägt dann keinen Zahlungskasten und keinen Giro-QR.
+**Already paid?** If you take the payment online and invoice afterwards, pass
+the payment along: it is recorded in the same transaction as the
+finalisation, and the PDF then has no payment box and no giro QR code.
 
 ```ts
-const { invoice } = await rechnungen.issueInvoice({
-  idempotencyKey: `bestellung-${bestellnummer}`,
-  customerId: kunde.id,
-  taxScheme: 'normal', priceMode: 'net', serviceStart: '2026-09-16',
-  items: [{ description: 'Beratung', quantity: 2, unitPriceCents: 5000, vatRate: 20, unit: 'hour' }],
-  payment: { method: 'card', reference: zahlung.id },      // ohne amountCents: voll bezahlt
-});                                                        // invoice.openCents === 0
-
-// Trifft das Geld erst später ein (Überweisung, Teilzahlung):
-await rechnungen.recordInvoicePayment({
-  idempotencyKey: `zahlung-${zahlung.id}`,                 // Pflicht: sonst bucht eine Wiederholung zweimal
+const { invoice } = await invoices.issueInvoice({
+  idempotencyKey: `order-${orderNumber}`,
+  customerId: customer.id,
+  priceMode: 'net', serviceStart: '2026-09-16',
+  items: [{ description: 'Consulting', quantity: 2, unitPriceCents: 5000, vatRate: 20, unit: 'hour' }],
+  payment: { method: 'card', reference: payment.id },      // without amountCents: paid in full
+});                                                         // invoice.openCents === 0
+
+// If the money arrives later (bank transfer, partial payment):
+await invoices.recordInvoicePayment({
+  idempotencyKey: `payment-${payment.id}`,                  // required: otherwise a retry books twice
   invoiceId: invoice.id, method: 'transfer', amountCents: 12000, paidAt: '2026-09-20',
 });
 ```
 
-`reference` wird gespeichert, aber **nicht gedruckt**; Kartendaten gehören
-ohnehin nicht auf eine Rechnung.
+`reference` is stored but **not printed**; card data does not belong on an
+invoice anyway.
 
-**Vorab rechnen.** Wer kassiert, bevor die Rechnung entsteht, braucht den
-Betrag, den die Rechnung später ausweist. `rechnungSummen` rechnet ihn genau
-wie der Server; `previewInvoice` fragt den Server selbst — ein Probelauf, der
-prüft wie das Ausstellen, aber nichts festschreibt und den `idempotencyKey`
-nicht verbraucht:
+**Cash sales.** The API treats `method: 'cash'`, and `method: 'card'` with
+`onSite: true` (terminal at the point of sale), as a cash sale (*Barumsatz*,
+§ 131b (1) no. 3 BAO). A card payment in an online shop is sent without
+`onSite`:
 
 ```ts
-import { rechnungSummen } from '@kreiseck/kasseneck-api/rechnung';
-
-const posten = [
-  { description: 'Maniküre', quantity: 1, unitPriceCents: 1479, vatRate: 20 as const },
-  { description: 'Lack', quantity: 1, unitPriceCents: 1500, vatRate: 20 as const },
-];
-rechnungSummen(posten, 'gross');
-// { netCents: 2483, vatCents: 496, grossCents: 2979, byRate: [{ rate: 20, … }] }
-
-const anfrage = { idempotencyKey: `bestellung-${bestellnummer}`, customerId: kunde.id,
-  priceMode: 'gross' as const, serviceStart: '2026-09-16', items: posten };
-const { preview, notice } = await rechnungen.previewInvoice(anfrage);
-// preview.totals, preview.taxScheme, preview.taxSchemeReason — dann:
-await rechnungen.issueInvoice(anfrage);
-```
-
-Im **Brutto-Modus** ist das Brutto je Satz der vereinbarte Preis: Netto =
-round(B × 100 / (100 + Satz)), USt = B − Netto. Im **Netto-Modus** wird die USt
-je Satz aus der Nettosumme gerundet. Gerundet wird kaufmännisch (halber Cent
-aufwärts), je Satz, dann summiert. Die Prüffälle liegen in
-`fixtures/rechnung-summen.json`. Die Summen sind auch bei Gutschriften positiv —
-das Vorzeichen steht im Belegtyp (`docType: 'GU'`).
-
-**Vorab rechnen, ohne Server.** `@kreiseck/kasseneck-api/rechnung/rechnen` ist
-der reine Rechenkern dahinter: kein Transport, kein Zugangsschlüssel, läuft
-auch im Browser (Panel). Er rechnet intern mit ganzen Zahlen (BigInt) statt
-Gleitkomma und rundet genau einmal je USt-Satz — Preise in Millionstel Euro
-(`unitPriceMicros`), Mengen in Tausendstel (`quantityMilli`), Rabatt und Satz
-in Hundertstel-Prozent (`discountBp`, `vatRateBp`):
-
-```ts
-import { rechnungRechnen } from '@kreiseck/kasseneck-api/rechnung/rechnen';
-
-rechnungRechnen(
-  [{ unitPriceMicros: 14_790_000, quantityMilli: 1000, vatRateBp: 2000 }],
-  { priceMode: 'gross' },
-);
-// { netCents: 1233, vatCents: 246, grossCents: 1479, byRate: [{ rateBp: 2000, … }], lines: […] }
+payment: { method: 'card', onSite: true }   // terminal at the point of sale
+payment: { method: 'card' }                 // card payment in the online shop
 ```
 
-`positionAusEuro(item)` wandelt eine Euro-Position (`unitPrice`, `quantity`,
-`vatRate`, `discountPct`) verlustfrei in diese Form um oder nennt Feld und
-Grund, wenn das nicht geht. Die Prüffälle liegen in
-`fixtures/rechnung-rechnen.json`, `fixtures/rechnung-rechnen-zufall.json` und
-`fixtures/position-aus-euro.json`. **Noch nicht zusammengeführt** mit
-`rechnungSummen`: bis 0.24.0 rechnen beide parallel und weichen an
-Halbcent-Grenzen bewusst voneinander ab — **je USt-Satz** bis zu 1 Cent bei
-einmal gerundeten Werten (Netto und USt im Netto-Modus, Brutto im
-Brutto-Modus) und bis zu 2 Cent bei abgeleiteten (Summe zweier Rundungen). Bei
-mehreren Sätzen summiert sich das: eine Rechnung über drei Sätze kann deshalb
-3 Cent auseinanderliegen. Der Kern rundet dort richtig, `rechnungSummen`
-rechnet weiterhin wie der Server heute. Verbindlich
-für den ausgewiesenen Betrag bleibt bis dahin `previewInvoice`.
-
-**Hinweise** (`notice`) sind immer eine Liste — bei `issueInvoice`,
-`previewInvoice` und `recordInvoicePayment`. Eine ig. Lieferung trägt
-`recapitulative_statement_due` (Zusammenfassende Meldung), eine bar bezahlte
-Rechnung zusätzlich `cash_receipt_required`.
-
-**Barumsatz ist nicht nur Bargeld.** Als Barzahlung gilt auch die Karte **vor
-Ort** an der Kasse (§ 131b Abs. 1 Z 3 UStG) — dieselbe Karte im Internet
-dagegen nicht. Weil `card` und `online` beides sein können, sagt es das
-Fremdsystem selbst:
+For those cases the response's `notice` list contains `cash_receipt_required`:
+a cash sale needs a receipt (§ 132a BAO), from the fiscal cash register where
+the business is obliged to use one. The note on the invoice does not replace
+it. `transfer` with `onSite` is a field error. Whether a payment counts as a
+cash sale is for the business to assess; the flag only tells the API how it
+was classified.
 
-```ts
-payment: { method: 'card', onSite: true }   // Terminal an der Kasse
-payment: { method: 'card' }                 // Kartenzahlung im Shop
-```
+**Notices** (`notice`) are always a list, for `issueInvoice`,
+`previewInvoice` and `recordInvoicePayment`. An intra-Community supply carries
+`recapitulative_statement_due` (recapitulative statement).
 
-Bei `cash` (immer) und bei `onSite: true` trägt die Antwort in der Liste
-`notice` den Eintrag `cash_receipt_required`: ein Barumsatz braucht einen Beleg
-(§ 132a BAO), bei Registrierkassenpflicht über die Registrierkasse — der
-Vermerk an der Rechnung ersetzt ihn nicht. `transfer` mit `onSite` ist ein
-Feldfehler, eine Überweisung erfolgt nicht vor Ort.
+**After a timeout, retry with the same `idempotencyKey`**, never with a new one:
+you then get the invoice that was already issued (`replayed: true`). The same
+key with different data gives `idempotency_conflict`.
 
-**Nach einem Zeitlimit mit demselben `idempotencyKey` wiederholen**, nie mit
-einem neuen: dann kommt die schon ausgestellte Rechnung zurück
-(`replayed: true`). Derselbe Schlüssel mit anderen Daten ergibt
-`idempotency_conflict`.
+Validation errors arrive as `validation` with field paths
+(`rechnungFeldFehler(error)` → `[{ field: 'items[0].vatRate', message }]`).
+The contract itself ships as data (`RECHNUNG_ANFRAGEN`) and as a JSON Schema at
+`@kreiseck/kasseneck-api/fixtures/rechnung-api.schema.json`; the backend
+validates against exactly this file.
 
-Formfehler kommen als `validation` mit Feldpfaden (`rechnungFeldFehler(fehler)`
-→ `[{ field: 'items[0].vatRate', message }]`). Der Vertrag selbst liegt als
-Daten im Paket (`RECHNUNG_ANFRAGEN`) und als JSON Schema unter
-`@kreiseck/kasseneck-api/fixtures/rechnung-api.schema.json`; das Backend prüft
-gegen genau diese Datei.
+### Calculating invoice totals in advance
 
-## Unterpfade
-
-| Unterpfad | Inhalt |
-|-----------|--------|
-| `@kreiseck/kasseneck-api` | Endpunkte, Anmeldung, Transport, Modelle, Enums, Fehler — alles, was mit dem Backend spricht. |
-| `…/receipt` | Beleg-Layout als Datenmodell (framework-frei) und die Brücke zu ESC/POS. |
-| `…/printing` | ESC/POS-Erzeugung: Bytefolgen für Bondrucker, ohne jeden Transport. |
-| `…/payments` | Stripe-Zahllinks, Hobex-Cloud (beides HTTP-Endpunkte des Backends) und Hobex **HPS** über **Kasseneck Connect** (lokaler Geräte-Agent, spricht mit dem Terminal). |
-| `…/register` | Anmeldung der Browser-Kasse: Gerät koppeln und entkoppeln, Benutzer auflisten, per PIN anmelden, Sitzung erneuern und beenden. |
-| `…/kasse` | Kachel-Kasse: Kassen-Einstellungen (betriebsweit / je Gerät), Artikelgruppen und Artikel für Kacheln, Rabattverteilung je Steuersatz, Reichweiten der Kassen-Rechte |
-| `…/partner` | Partner-API: Betriebe anlegen, FinanzOnline-Link, Signatur, Kassen, Zugangsdaten, Webhooks samt Signaturprüfung. **Gehört auf einen Server.** |
-| `…/rechnung` | Rechnungs-API: Kunden anlegen und suchen, Rechnungen festgeschrieben ausstellen, Gutschrift und Storno, PDF und E-Rechnung-XML; der Vertrag als Daten. **Gehört auf einen Server.** |
-| `…/rechnung/rechnen` | Reiner Rechenkern für Rechnungssummen (Ganzzahlen, kein Transport, keine Abhängigkeit außer Typen) — darf auch im Browser laufen. |
-| `…/react` | Dünner React-Adapter, der ein Beleg-Layout zeichnet. Braucht React. |
-| `…/fixtures/*` | Golden-Belege (JSON): Eingaben `belege/<name>.json`, zugesagte Zeilenausgabe `erwartet/<name>.lines.json`, `manifest.json` mit Prüfsummen — dieselben Dateien prüfen Backend, Browser-Kasse und Flutter-Paket. |
-
-So zieht sich niemand den React-Adapter in ein Node-Programm.
-
-## Der QR-Code passt aufs Papier
-
-Der native QR-Befehl bekommt eine Modulgröße in Druckpunkten mit und rechnet
-selbst nicht nach, ob das Symbol samt Ruhezone auf die Rolle geht. Zu breit
-heißt bei den meisten Bondruckern nicht „abgeschnitten", sondern **gar kein
-QR** — auf einem Pflichtbeleg der schlechteste aller Ausgänge. Deshalb rechnet
-dieses Paket die Größe, statt sie zu setzen:
+If you charge before the invoice exists, you need the amount the invoice will
+show. `previewInvoice` asks the server itself: a dry run that validates like
+issuing but finalises nothing and does not use up the `idempotencyKey`. Its
+result is authoritative.
 
 ```ts
-import { qrGroesseFuer, QR_DRUCK_PUNKTE } from '@kreiseck/kasseneck-api/printing';
-
-const mass = qrGroesseFuer({ nutzlast: beleg.qr, papierbreitePunkte: QR_DRUCK_PUNKTE.mm58 });
-// mass.punkte: Punkte je Modul, null = passt auch mit der Ausnahmegröße nicht
-// mass.unterMindestmass: gedruckt, aber unter 4 Punkten je Modul
-```
-
-Am Belegweg passiert das von selbst. `qrGroesse` ist ein **Deckel**, keine
-Vorgabe: gedruckt wird die größte Größe, die noch passt, höchstens aber der
-Deckel. `auto` (Vorgabe) deckelt bei 6 Punkten je Modul — wie im Dart-Zwilling
-und am Epson-Weg; `klein` deckelt bei 4. Alle Druckwege setzen den QR mit
-Fehlerkorrektur M.
-
-```ts
-import { escPosLayoutErgebnis } from '@kreiseck/kasseneck-api/receipt';
-
-const { bytes, qrFehler, qrAusweich } = escPosLayoutErgebnis(layout, {
-  qrGroesse: 'gross',        // 'auto' | 'klein' | 'mittel' | 'gross'
-  qrModus: 'nativeModel1',   // ältere Drucker, die nur Modell 1 können
-  qrMatrix: rasterFuer,      // Notausgang: der QR als Bild statt gar nicht
-});
+const items = [
+  { description: 'Manicure', quantity: 1, unitPriceCents: 1479, vatRate: 20 as const },
+  { description: 'Nail polish', quantity: 1, unitPriceCents: 1500, vatRate: 20 as const },
+];
+const request = { idempotencyKey: `order-${orderNumber}`, customerId: customer.id,
+  priceMode: 'gross' as const, serviceStart: '2026-09-16', items };
+const { preview, notice } = await invoices.previewInvoice(request);
+// preview.totals, preview.taxScheme, preview.taxSchemeReason, then:
+await invoices.issueInvoice(request);
 ```
 
-Der Epson-Weg (`eposPrintXml` / `eposDirectPrint`) rechnet genauso;
-`eposPrintXmlErgebnis` gibt dort `{ xml, qrFehler, qrAusweich }`. Die Vorgabe
-ist auch dort `auto`.
-
-`qrFehler` heißt „Beleg ohne QR" — das gehört dem Kunden gesagt. `qrAusweich`
-heißt „gedruckt, aber der eingestellte Weg taugt für dieses Gerät nicht" — das
-gehört dem Chef gesagt. Den Bildweg fährt das Paket nur mit einem `qrMatrix`,
-das die Nutzlast in ein fertiges Raster übersetzt: hier wird bewusst weder ein
-QR gerechnet noch ein Bild verarbeitet.
-
-## Das Beleg-Blatt: überall derselbe Beleg
-
-Bildschirm, Bon, ePOS und PDF setzen dasselbe **Blatt**: Rasterzeilen, Firmenlogo,
-QR und die Marke „erstellt mit Kasseneck", mit Größen als Anteil der Blattbreite
-und in Zeilen (eine Zeile = zwei Zeichenbreiten).
-
-```tsx
-import { BelegBlattView } from '@kreiseck/kasseneck-api/react';
-
-<BelegBlattView layout={layout} logo={{ url: company.logoUrl, stufe: 'M' }} marke={company.showKreiseckLogo} renderQr={(d) => <QrSvg data={d} />} />
-```
+**Without the server.** `@kreiseck/kasseneck-api/rechnung/rechnen` is the pure
+calculation core: no transport, no key, runs in the browser too. It calculates
+with integers (BigInt) instead of floating point and rounds exactly once per
+VAT rate. Prices are in micro-euros (`unitPriceMicros`), quantities in
+thousandths (`quantityMilli`), discount and VAT rate in hundredths of a
+percent (`discountBp`, `vatRateBp`):
 
 ```ts
-import { escPosLayoutBytes, logoMass, logoRaster } from '@kreiseck/kasseneck-api/receipt';
-
-const mass = logoMass({ stufe: 'M', pxBreite: bild.width, pxHoehe: bild.height }, 48);
-const raster = logoRaster(imageData.data, bild.width, bild.height, mass, 48);
-escPosLayoutBytes(layout, { paperSize: 'mm80', logo: { stufe: 'M', pxBreite: bild.width, pxHoehe: bild.height, raster }, marke: true });
-```
-
-Logo-Stufen: S 42 % × 5 Zeilen, M 62 % × 8, L 80 % × 12, XL 94 % × 16 — eingepasst,
-nie hochgerechnet. Der Aufdruck (TESTKASSE, STORNOBELEG …) ist ein Rahmen aus
-`=`-Zeilen, auf jedem Weg gleich.
-
-## Hobex HPS über Kasseneck Connect
-
-Ein Browser hat weiterhin keine rohen TCP-Sockets — ein **direkter**
-Terminal-Kontakt wie beim Flutter-Paket `kasseneck_api` (`HpsClient`) bleibt
-deshalb außerhalb der Reichweite dieses Pakets. **Kasseneck Connect** ist aber
-ein lokaler Geräte-Agent mit gewöhnlicher HTTP-Schnittstelle, der für die Kasse
-mit dem Terminal spricht — und darüber geht es:
+import { rechnungRechnen, positionAusEuro } from '@kreiseck/kasseneck-api/rechnung/rechnen';
 
-```ts
-import { createHpsConnectClient, createHpsPayments } from '@kreiseck/kasseneck-api/payments';
-
-const client = createHpsConnectClient({ token: kopplungsToken });
-const zahlweg = createHpsPayments(client, { host: '192.168.1.50', tid: '3600335' });
+rechnungRechnen(
+  [{ unitPriceMicros: 14_790_000, quantityMilli: 1000, vatRateBp: 2000 }],
+  { priceMode: 'gross' },
+);
+// { netCents: 1233, vatCents: 246, grossCents: 1479, byRate: [{ rateBp: 2000, … }], lines: […] }
 
-const ergebnis = await zahlweg.pay({ amountCents: 1050 });
-// ergebnis.outcome: 'approved' | 'declined' | 'unresolved' — nie geraten.
-// ergebnis.transactionId ist IMMER gesetzt, auch bei 'unresolved'.
+positionAusEuro({ unitPrice: 14.79, quantity: 1, vatRate: 20 });
+// { ok: true, position: { unitPriceMicros: 14790000, quantityMilli: 1000, discountBp: 0, vatRateBp: 2000 } }
 ```
 
-Der Ausgang ist immer einer von drei: `approved`, `declined` (beweisbar nichts
-belastet) oder `unresolved` (Ausgang unbekannt, eine Wiederholung könnte ein
-zweites Mal belasten). Was das bedeutet und warum es so gebaut ist, steht in
-`src/payments/hobex-hps/payments.ts` — dort ist die Dokumentation der Maßstab,
-nicht dieses README.
-
-**Nur `pay` — bewusst kein `refund`/`cancel`.** Kasseneck Connect exponiert
-dafür (noch) keinen Endpunkt; eine Gutschrift oder ein Storno am HPS-Terminal
-braucht weiterhin die Flutter-App. **myPOS** und **SumUp** bleiben
-Android-SDKs ohne Entsprechung hier.
-
-## Was hier grundsätzlich nicht dazugehört
-
-Die Druckeransteuerung selbst (dieses Paket erzeugt die Bytes, es verschickt
-sie nicht) und die PDF-Erzeugung. Bilder dekodieren (PNG/JPEG): das Paket
-rastert fertige RGBA-Pixel, das Laden des Bilds bleibt bei der Anwendung.
-
-## Entwicklung
+`positionAusEuro(item)` converts a euro line (`unitPrice`, `quantity`,
+`vatRate`, `discountPct`) into this form without loss, or names the field and
+the reason when that is not possible. Since 23 September 2026 the server
+calculates every new invoice with this core. In **gross mode** the gross amount
+per rate is the agreed price: net = round(gross × 100 / (100 + rate)),
+VAT = gross − net. In **net mode** the VAT per rate is rounded from the net
+sum. Rounding is commercial (half a cent rounds away from zero). Totals are
+positive for credit notes too; the sign is in the document type
+(`docType: 'GU'`). Test cases: `fixtures/rechnung-rechnen.json`,
+`fixtures/rechnung-rechnen-zufall.json`, `fixtures/position-aus-euro.json`.
+
+**`rechnungSummen` still uses the previous formula.** The older helper in
+`…/rechnung` works on `unitPriceCents` lines and does not yet run through the
+core. At half-cent boundaries it can differ from an invoice issued today by
+one cent per VAT rate, and by a few cents across several rates. Example:
+€ 21.35 net at 10 % gives € 23.48 gross with `rechnungSummen`, but € 23.49
+with the core and on the invoice. Use `rechnungRechnen` or `previewInvoice` in
+new code. Test cases for the old formula: `fixtures/rechnung-summen.json`.
+
+## Development
 
 ```bash
-npm test              # Testsuite in drei Zeitzonen (Wien, UTC, Kiritimati)
-npm run build         # ESM- und CJS-Bau nach dist/, inkl. Prüfung der exports
-npm run check:consumer # baut den Tarball und übersetzt zwei Verbraucher (CJS/ESM)
-npm run check:erreichbar # fragt die öffentliche Adresse: antwortet dort zu jedem Aufruf eine Function?
+npm test              # test suite in three time zones (Vienna, UTC, Kiritimati)
+npm run build         # ESM and CJS build into dist/, including a check of the exports
+npm run check:consumer # packs the tarball and compiles two consumers (CJS/ESM)
+npm run check:erreichbar # asks the public address: is there a function behind every call?
 ```
 
-Die drei Zeitzonen sind kein Übereifer: Zeitfehler sind auf einer Wiener
-Maschine zufällig richtig. Belegzeiten werden konsequent als **Wiener
-Wanduhrzeit** gedeutet (`parseServerTimeStamp`), nie über `new Date(text)`.
+The three time zones are not overkill: time bugs happen to be correct on a
+machine in Vienna.
 
-### `check:erreichbar` — spricht als einzige mit `api.kasseneck.at`
+### `check:erreichbar`: the only check that talks to `api.kasseneck.at`
 
-Testsuite und `check:consumer` laufen gegen Attrappen bzw. gegen den Tarball;
-keine von beiden setzt je einen Aufruf ab. Fehlt einem Aufruf die
-Hosting-Weiterleitung, liefert die veröffentlichte Adresse die
-HTML-Auffangseite statt der Function — und das sieht keine Attrappe.
+The test suite and `check:consumer` run against mocks or against the tarball;
+neither ever makes a call. If a call lacks its hosting rewrite, the published
+address returns the HTML fallback page instead of the function, and no mock
+sees that.
 
-Die Prüfung braucht **keine Zugangsdaten**. Ein Aufruf ohne Anmeldung
-antwortet, wenn dort eine Function steht, mit
+The check needs **no credentials**. A call without authentication answers,
+when there is a function behind it, with
 `{"status":"error","message":"Ungültiger Request: Authorization key erwartet."}`.
-Genau das ist der Beweis: Der Aufruf wurde angenommen und die Anmeldung
-geprüft. Eine HTML-Seite oder ein 404 ist der Beweis, dass dort keine Function
-steht. Deshalb prüft das Skript auf ein `status`-Feld und nicht auf Erfolg.
-
-Bewusst außerhalb von `npm test`: Sie braucht Netz. Ist keines da, sagt sie es
-und endet mit 0. Aufrufe, die unter `/v1` absichtlich keine Weiterleitung
-haben — der Kassen-Weg über `kasse.kasseneck.at/api`, die Aufrufe mit
-ID-Token — stehen mit Grund in `scripts/erreichbarkeit-ausnahmen.json`.
-Wird eine Ausnahme erreichbar, schlägt die Prüfung an: Sonst sänke die Zahl nie.
-
-## Vertragsdateien für die Zwillinge
-
-Dieses Paket ist die Quelle für das Dart-Paket `kasseneck_api` und den
-Backend-Validator `kasse-settings-core.js`. Drei Dateien in `fixtures/` reisen
-im Tarball mit und sagen in Maschinenform, worauf sich beide Seiten geeinigt haben:
-
-| Datei | Inhalt |
+That is the proof: the call was accepted and authentication was checked. An
+HTML page or a 404 proves that there is no function. That is why the script
+looks for a `status` field and not for success.
+
+It is deliberately outside `npm test` because it needs the network. Without a
+network it says so and exits with 0. Calls that deliberately have no rewrite
+under `/v1` (the register path via `kasse.kasseneck.at/api`, the calls with an
+ID token) are listed with a reason in `scripts/erreichbarkeit-ausnahmen.json`.
+If an exception becomes reachable, the check fails; otherwise the list would
+never shrink.
+
+## Contract files for the twin packages
+
+This package is the source for the Dart package `kasseneck_api` and for
+validators in the backend. Files in `fixtures/` ship in the tarball and state
+in machine form what both sides agreed on, among them:
+
+| File | Contents | Generated by |
+|---|---|---|
+| `kasse-settings-standard.json` | field names and defaults of the register settings | `npm run fixtures:kasse` |
+| `oberflaeche.json` | call names, enum values, permission keys, key actions, partner lists | `npm run fixtures:oberflaeche` |
+| `hobex-hps-codes.json` | measured HPS result codes, their meaning and whether they settle an outcome (the contract behind `isConclusive`) | `npm run fixtures:hobex-hps-codes` |
+| `kasse-texte.json` | the register's message catalogue | `npm run fixtures:texte` |
+| `rechnung-texte.json` | invoice texts in both languages | `npm run fixtures:rechnungstexte` |
+| `rechnung-api.schema.json` | JSON Schema of the invoice API | `npm run fixtures:rechnung` |
+
+They are generated and never edited by hand. CI regenerates the register
+settings and `oberflaeche.json` and fails if they differ from the committed
+files; the test suite checks the others against the code.
+
+`oberflaeche.json`, `hobex-hps-codes.json`, `kasse-texte.json` and
+`rechnung-texte.json` carry the package version. **After every `npm version`,
+regenerate them and commit them along**, otherwise the tests fail.
+
+### And the other direction
+
+The contract in `fixtures/` is checked **over there**: the Dart repository
+pulls it and holds its lists against it. A gap would therefore only show up in
+the next twin run in the other repository, on another day. Against that there
+are two hand-maintained snapshots of the Dart side under `test/fixtures/`,
+each with a `_quelle` field:
+
+| File | Checks |
 |---|---|
-| `kasse-settings-standard.json` | Feldnamen und Standardwerte der Kassen-Einstellungen |
-| `oberflaeche.json` | Aufrufnamen, Enum-Werte, Rechte-Schlüssel, Tasten-Aktionen |
-| `hobex-hps-codes.json` | Gemessene HPS-Ergebniscodes, ihre Bedeutung und ob sie einen Ausgang festschreiben — der Vertrag hinter `.../payments/hobex-hps`s `isConclusive`. |
+| `dart-enums.json` | receipt type, VAT rate, payment method, card provider, voucher, Stripe mode |
+| `dart-partner.json` | environments, error codes (API and portal), webhook events, fields of the webhook envelope including the `test` flag, business fields, retry plan |
 
-| `oberflaeche.json` | Aufrufnamen, Enum-Werte, Rechte-Schlüssel, Tasten-Aktionen, Partner-Listen |
+They make `npm test` fail as soon as a value arrives in only one of the two
+languages.
 
-Alle drei werden erzeugt (`npm run fixtures:kasse`, `npm run fixtures:oberflaeche`,
-`npm run fixtures:hobex-hps-codes`) und nie von Hand geändert; die CI prüft
-nach jedem Lauf, dass sie zum Code passen.
+## Glossary
 
-`oberflaeche.json` und `hobex-hps-codes.json` tragen die Paketversion. **Nach
-jedem `npm version` müssen deshalb alle drei Dateien neu erzeugt und
-mitcommittet werden**, sonst wird die CI rot.
+German terms used in this package, in its identifiers and on the linked pages:
 
-### Und die Gegenrichtung
-
-Der Vertrag in `fixtures/` wird **drüben** geprüft: das Dart-Repo zieht ihn und
-hält seine Listen dagegen. Eine Lücke fiele hier deshalb erst im nächsten
-Zwillingslauf im anderen Repo auf — an einem anderen Tag. Dagegen stehen zwei
-von Hand gepflegte Abzüge der Dart-Seite unter `test/fixtures/`, jeder mit
-`_quelle`:
-
-| Datei | prüft |
+| German | English |
 |---|---|
-| `dart-enums.json` | Belegtyp, Steuersatz, Zahlungsart, Kartenanbieter, Gutschein, Stripe-Modus |
-| `dart-partner.json` | Umgebungen, Fehlercodes (API und Portal), Webhook-Ereignisse, Felder des Webhook-Umschlags samt der Marke `test`, Betriebsfelder, Wiederholungsplan |
-
-Sie machen `npm test` rot, sobald ein Wert nur in einer der beiden Sprachen
-ankommt.
-
-## Lizenz
-
-Apache-2.0 — siehe `LICENSE` und `NOTICE`.
+| Beleg | receipt |
+| Startbeleg | start receipt |
+| Nullbeleg | zero receipt |
+| Monatsbeleg | monthly receipt |
+| Jahresbeleg | annual receipt |
+| Schlussbeleg | final receipt |
+| Storno | cancellation |
+| Signaturerstellungseinheit | signature creation unit |
+| DEP (Datenerfassungsprotokoll) | data capture log (DEP) |
+| Kassennachschau | cash register audit |
+| Belegerteilungspflicht | obligation to issue receipts |
+| Registrierkasse | fiscal cash register |
+| Umsatzzähler | turnover counter |
+| Außerbetriebnahme | decommissioning |
+| Ausfall der Signatureinheit | signature unit failure |
+| Rechnung | invoice |
+| USt | VAT |
+| FinanzOnline | name of the online portal of the Austrian tax administration |
+| BMF | name of the Austrian Federal Ministry of Finance |
+
+## License
+
+Apache-2.0, see `LICENSE` and `NOTICE`.
 
 ---
 
-**Kasseneck** ist ein Produkt von
-[Kreiseck Software Solutions](https://kreiseck.com) aus Salzburg — Apps,
-Kassensysteme und Automatisierungen. Fragen zur Schnittstelle, zu eigenen
-Integrationen oder zu einer Partnerschaft:
+**Kasseneck** is a product of
+[Kreiseck Software Solutions](https://kreiseck.com) from Salzburg, Austria:
+apps, point-of-sale systems and automation. Questions about the interface,
+custom integrations or a partnership:
 [kasseneck.at/kontakt](https://kasseneck.at/kontakt).