![\"Kasseneck:](\"https://raw.githubusercontent.com/kreiseck-at/kasseneck-api/main/doc/kasseneck.gif\")
\n\n \n
\n Austrian fiscal cash register (RKSV) for JavaScript and TypeScript: signed receipts, card payments, receipt printing.\n
\n\n\n ![\"npm\"](\"https://img.shields.io/npm/v/%40kreiseck%2Fkasseneck-api?color=136B6B&label=npm\")
![\"RKSV\"](\"https://img.shields.io/badge/RKSV-%C2%A7%20131b%20BAO-136B6B\"){kind=icon}
![\"Apache-2.0\"](\"https://img.shields.io/badge/License-Apache--2.0-136B6B\"){kind=icon}
![\"kasseneck.at\"](\"https://img.shields.io/badge/Kasseneck-kasseneck.at-132A2A\"){kind=icon}
![\"Kreiseck](\"https://img.shields.io/badge/by-Kreiseck-132A2A\"){kind=icon}
\n Deutsch: README.de.md\n
\n\n**Kasseneck** is a fiscal cash register (*Registrierkasse*) for Austria that\nimplements the RKSV, the Austrian cash register security regulation. This\npackage is its JavaScript and TypeScript client: your code issues receipts,\nthe Kasseneck backend handles receipt signing and chaining, and the package\nreturns the results as typed objects. It also cancels receipts, takes card\npayments, lays out and prints receipts on thermal printers, and covers the\npartner and invoice APIs. It is the twin of the Flutter package\n[`kasseneck_api`](https://pub.dev/packages/kasseneck_api): same endpoints, same\nmodels, same enum values, checked against each other in tests.\n\n## Contents\n\n- [Quick start](#quick-start)\n- [What a fiscal cash register in Austria must do](#what-a-fiscal-cash-register-in-austria-must-do)\n- [Try it first, or use the ready-made register](#try-it-first-or-use-the-ready-made-register)\n- [Requirements and subpaths](#requirements-and-subpaths)\n- [Base URLs and the `/v3` marker](#base-urls-and-the-v3-marker)\n- [Authentication](#authentication)\n- [Amounts are integer cents](#amounts-are-integer-cents)\n- [Errors](#errors)\n- [Receipts](#receipts)\n- [Cancellation (Storno)](#cancellation-storno)\n- [Sending a receipt by email](#sending-a-receipt-by-email)\n- [Receipt printing: QR code, logo, printers](#receipt-printing-qr-code-logo-printers)\n- [Register settings, articles and printers (`./pos`)](#register-settings-articles-and-printers-pos)\n- [Stored documents (`./stored`)](#stored-documents-stored)\n- [Card payments](#card-payments)\n- [Partner API (`./partner`)](#partner-api-partner)\n- [Invoice API (`./invoice`)](#invoice-api-invoice)\n- [Migrating from 0.x](#migrating-from-0x)\n- [Development](#development)\n- [Contract files for the twin packages](#contract-files-for-the-twin-packages)\n- [Glossary](#glossary)\n- [License](#license)\n\n## Quick start\n\n```bash\nnpm install @kreiseck/kasseneck-api\n```\n\nSell two items, then build the printed receipt (*Beleg*) from the response:\n\n```ts\nimport {\n createKasseneckApi,\n apiKeyAuth,\n KeckPaymentMethod,\n VatRate,\n receiptDueCents,\n receiptLayoutFromResult,\n} from '@kreiseck/kasseneck-api';\nimport { renderReceiptGrid, escPosLayoutBytes } from '@kreiseck/kasseneck-api/receipt';\n\nconst api = createKasseneckApi({\n auth: apiKeyAuth({ apiKey: 'kr_live_…', cashregisterToken: 'cb_live_…' }),\n});\n\nconst items = [\n { name: 'Café Latte', quantity: 2, vat: VatRate.vat20, priceCents: 390 },\n { name: 'Marmeladeweckerl', quantity: 1, vat: VatRate.vat10, priceCents: 250 },\n];\n// Optional tip in cents; the backend books it as a signed tip line.\n// With its own payment method or recipients: { cents, paymentMethod, recipients }.\nconst tip = 100;\n\n// The payments must add up to exactly this amount (whole cents). Who gets a\n// tip without recipients is the logged-in register user: 'owner' or 'staff'.\nconst dueCents = receiptDueCents(items, [], 'standard', { tip, tipRecipient: 'staff' }); // 1130\n\n// Sell, and get the company data and the receipt layout in the same call.\nconst result = await api.sellReceiptWithCompany({\n items,\n tip,\n payments: [{ method: KeckPaymentMethod.cash, amountCents: dueCents, tenderedCents: 2000 }],\n});\n\n// Layout: a plain data model (lines, alignment, columns, QR code). The server\n// sends it as `layout` (80 mm), and it always wins; only without it does\n// receiptLayoutFromResult build one from the same response (test banners\n// included) in `fallbackPaperSize` (default 'mm58'). The print width is chosen\n// by the print path (`paperSize` below), never by this helper.\nconst layout = receiptLayoutFromResult(result);\n\n// Character grid: exactly 32 (58 mm) or 48 (80 mm) characters per line.\n// Screen, printed receipt and PDF all use this one grid.\nconst grid = renderReceiptGrid(layout, { charsPerLine: 32 }); // grid.lines[i].text, .bold, .kind, .qr\n\n// ESC/POS bytes for a thermal printer; they print exactly the grid lines.\nconst bytes = escPosLayoutBytes(layout, { paperSize: 'mm58' });\n```\n\nThe receipt returned by `sellReceiptWithCompany` (or `sellReceipt`) has already\nbeen signed, chained and stored in the data capture log (*DEP*) by the backend.\n\n**Payments are mandatory.** Every sale carries `payments[]` (several per receipt:\ncard plus cash and so on); card details (`provider`, `providerPaymentId`,\n`providerData`) belong to the single payment. `receiptDueCents` computes the\namount the payments must match, exactly as the backend does (tax buckets,\ndiscount vouchers, tips, value vouchers). If they do not match, the backend\nrejects the receipt with `payments_sum_mismatch` without using up a receipt\nnumber; `paymentsExpectedCents(error)` gives its amount. The package never\nretries on its own: a card payment has already been charged.\n\nThe list may be empty only when the amount due is 0. The single\n`paymentMethod` of 0.x and the card fields beside it (`creditCardProvider`,\n`cardPaymentId`, `cardPaymentData`) are rejected before anything is sent.\n`receiptDueCents` needs `tipRecipient` (`'owner'` or `'staff'`, the role of the\nsigned-in register user) as soon as a tip has no `recipients`: an owner's tip\nis turnover, spread over the VAT rates of the goods and discounted with them,\nwhile a staff tip goes untouched into the 0 % bucket. Only the register knows\nwhich one applies, so the helper never guesses.\n\nInput the amount cannot be computed from (a tip with an amount but no goods,\na tip on a null receipt, a missing `tipRecipient` …) throws a\n`ReceiptDueError` with `code: 'receipt_due_unavailable'`, the cause in\n`reason` (`RECEIPT_DUE_ERROR_REASONS`) and `outcome: 'rejected'`: nothing has\nbeen sent. Tell the cashier before the card terminal is started.\n\n## What a fiscal cash register in Austria must do\n\nThe obligation to use a fiscal cash register and to issue receipts is set out\nin § 131b of the Austrian Federal Fiscal Code (*Bundesabgabenordnung*, BAO).\nThe technical requirements for the security device are in the cash register\nsecurity regulation (*Registrierkassensicherheitsverordnung*, RKSV). The table\nshows which of the resulting tasks **this software** takes over and which stay\nwith the business:\n\n| Task | Where it is handled |\n| --- | --- |\n| [Signature creation unit (*Signaturerstellungseinheit*)](https://kasseneck.at/wissen/signaturerstellungseinheit): every receipt is signed | Kasseneck, nothing to install |\n| [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 |\n| [Start receipt, monthly receipt, annual receipt (*Startbeleg, Monatsbeleg, Jahresbeleg*)](https://kasseneck.at/wissen/startbeleg-monatsbeleg-jahresbeleg) | Kasseneck, automatic |\n| [Notifications to FinanzOnline](https://kasseneck.at/wissen/finanzonline): registration, failure, decommissioning (*Außerbetriebnahme*) with its final receipt (*Schlussbeleg*) | Kasseneck backend submits them |\n| [Obligation to issue receipts (*Belegerteilungspflicht*)](https://kasseneck.at/wissen/belegerteilungspflicht): every customer gets a receipt | **this package**: printed receipt, PDF, screen or link |\n| [Signature unit failure (*Ausfall der Signatureinheit*)](https://kasseneck.at/wissen/ausfall): collective receipt, notification, subsequent signing | Kasseneck, automatic |\n| [Cash register audit (*Kassennachschau*)](https://kasseneck.at/wissen/kassennachschau): the auditor asks for the DEP | Kasseneck, export on request |\n| Duty to register the cash register, retention of records, tax assessment | **the business owner** |\n\nIn short: you build the point-of-sale interface, not the security device. The\nsignature chain is tested against the official verification tool of the\nAustrian Federal Ministry of Finance (BMF).\n\n> **Not legal or tax advice.** This section describes what the software does.\n> It does not replace professional advice and is no assurance that a particular\n> business meets all its obligations with it. The BAO, the RKSV and the rulings\n> of the BMF are binding. Registering and operating the cash register and\n> retaining the records remain the duty of the business owner, also where the\n> software submits the notifications. More detail with sources (in German):\n> [kasseneck.at/wissen](https://kasseneck.at/wissen).\n> As of: September 2026.\n\n## Try it first, or use the ready-made register\n\nThere is a test environment with its own key and test signatures, separate\nfrom live operation. The HTTP interface is described at\n[kasseneck.at/api-doku](https://kasseneck.at/api-doku).\n\nThis package is for people who build their own application. If you just want\nto take payments, there is nothing to program:\n\n- **[Kasseneck, the ready-made fiscal cash register](https://kasseneck.at)** for\n phone, tablet and browser, including the signature creation unit and the\n FinanzOnline registration.\n- **[Solutions by industry](https://kasseneck.at/branchen)**\n- **[Pricing](https://kasseneck.at/preise)**\n- **[Contact](https://kasseneck.at/kontakt)**, also for switching registers,\n partnerships and custom integrations.\n\n## Requirements and subpaths\n\n**Runs in the browser and in Node.js.** ESM is the main format, CommonJS ships\nalongside it, both with their own type declarations. Node 20.18 or later\n(`fetch` must be available). There are no runtime dependencies. React 18 or\nlater is an optional peer dependency, needed only for `./react`.\n\nImport only the subpath you need, so a Node program never pulls in the React\nadapter:\n\n| Subpath | Contents |\n|-----------|--------|\n| `@kreiseck/kasseneck-api` | Endpoints, authentication, transport, models, enums, errors: everything that talks to the backend. |\n| `…/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). |\n| `…/printing` | ESC/POS generation (byte sequences for thermal printers), QR sizing, printing over WebUSB. |\n| `…/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). |\n| `…/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. |\n| `…/pos` | 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. |\n| `…/partner` | Partner API (`/v3`, English): create businesses, FinanzOnline link, signature, cash registers, credentials, webhooks with signature verification. **Belongs on a server.** |\n| `…/stored` | Stored Firestore documents (inner form, German) as the same English models the `/v3` wire returns: receipts with company and layout, register settings, articles. For clients that read Firestore directly, such as the admin panel. |\n| `…/invoice` | 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.** |\n| `…/invoice/calc` | Pure calculation core for invoice totals (integers, no transport, no dependency beyond types). Safe to run in the browser. |\n| `…/react` | Thin React adapter that renders a receipt layout or a receipt sheet. Needs React. |\n| `…/fixtures/*` | Golden receipts (JSON): inputs `receipts/