@kreiseck/kasseneck-api 1.4.0 → 1.5.1

package/CHANGELOG.md

@@ -4,6 +4,172 @@ Was vor 0.7.0 geschah, steht in der Commit-Historie (`git log`); ab hier wird
 es hier geführt. Ein Eintrag nennt die Änderung **und ihren Grund** —
 nur der Grund überlebt den nächsten Umbau.
 
+## 1.5.1
+
+Every call with an effect reports `outcome: 'unknown'` when it fails after
+sending began: network error, timeout, HTTP 5xx, HTTP 200 with the `/v3`
+marker but an empty, non-JSON or status-less body, and HTML with the marker.
+Reason: until 1.5.0 only the six signing and money calls did; a goods receipt,
+a reservation or `issueInvoice` came back as `'rejected'` ("did not happen")
+although the server may have booked it. Whoever believed that and resent with
+a **new** `idempotencyKey` booked twice.
+
+A change to the safe side, no change on the wire; requests send the same body
+as in 1.5.0 (only the `Kasseneck-Client` header carries the new version).
+
+- **Which calls**: `UNKNOWN_OUTCOME_CALLS` (exported, sorted), also in
+  `fixtures/surface.json` as `unknownOutcomeCalls` for the Dart twin. New in it:
+  inventory writes (`createArticle`, `updateArticle`, `deactivateArticle`,
+  `receiveGoods`, `transferStock`, `recordStockLoss`, `changeStockCondition`,
+  `reverseStockMovement`), reservations (`createReservation`,
+  `extendReservation`, `releaseReservation`), inventory and partner webhooks
+  (create, update, delete, rotate the secret, test delivery), the invoice API
+  (`issueInvoice`, `cancelInvoice`, `createCreditNote`, `recordInvoicePayment`,
+  `createCustomer`, `updateCustomer`), invoice items and SEPA mandates
+  (`createInvoiceItem`, `updateInvoiceItem`, `withdrawInvoiceItem`,
+  `setCustomerMandate`, `revokeCustomerMandate`), the partner calls with an
+  effect (`createPartnerCustomer`, `sendPartnerCustomerFonLink`,
+  `requestCustomerSignature`, `createCustomerCashregister`,
+  `activateCashregister`, `reportCustomerContract`), and on the register
+  `pairRegisterDevice`, `unpairRegisterDevice`, `setMyKasseSettings`,
+  `setMyKasseLogo`, `setMyRegisterDeviceSettings`,
+  `setMyCashregisterStockLocation`, `createPrintJob`, `sendReceiptEmail`.
+- **Which stay `'rejected'`**: reading calls, dry runs (`previewGoodsReceipt`,
+  `previewInvoice`, `issueInvoice` with `dryRun: true`), the register sign-in
+  sessions (`registerUserLogin`, `registerPinLogin`, `renewRegisterSession`,
+  `endRegisterSession`) and `createPaymentLinkStripe`: a repeat books nothing.
+  A timeout already during sign-in stays `'rejected'` as before: nothing was
+  sent.
+- **What to do**: with an `idempotencyKey`, send the same request with the
+  **same** key; it takes effect once and returns the stored answer.
+  `createInvoiceItem` is recognised by `source` + `reference`: the same values
+  again are safe. Without a key (receipts, cancellations, money calls,
+  settings, webhooks, changing or withdrawing invoice items, mandates), read
+  the state first. The rule for receipts and payments is unchanged: look it up,
+  never resend.
+- **Per call**: the transport takes a fifth argument `{ hasEffect }`
+  (`TransportCallOptions`). `true` marks a call with an effect that this
+  package does not know. `false` only counts together with
+  `params.dryRun === true` (a dry run under the name of the real call; the
+  package's own previews use it); without `dryRun: true` a call from the list
+  stays `'unknown'`, so no option can turn a real booking into `'rejected'`.
+  Without the option the list decides, and an unknown name counts as having no
+  effect.
+- **Guard**: every call the package knows (`ALL_CALLS`, `PUBLIC_CALLS`,
+  `POS_CALLS`) is classified as with or without effect; a new call without a
+  classification fails the tests.
+- `CALLS_WITH_EFFECT` of the register texts and `fixtures/pos-texts.json` are
+  unchanged; `messageOutcome` follows the transport first, so the register
+  shows the careful sentence for every call above.
+
+## 1.5.0
+
+Inventory API, write side and reservations: `./inventory` gains the 13
+endpoints of backend stage 5b, and the invoice API learns `reservationId`.
+Reason: a shop that only reads stock still oversells. It has to hold the goods
+at checkout, book what arrives and leaves, keep its articles in sync, and turn
+the reservation into a sale when the order is invoiced, all with retries that
+never book twice. The invoice API also catches up with the VAT ID check of
+the backend (stage 4, in the 0.x line since 0.33.0).
+
+Additive, no breaking change; existing calls send the same bytes as in 1.4.0.
+New response fields are added to the models.
+
+- **Articles**: `createArticle`, `updateArticle`, `deactivateArticle`, each
+  answering with the article as `getArticle` returns it. Fields: `name`,
+  `description`, `unitPriceCents`, `vatRate`, `unit`, `number`, `ean` (with
+  `ean` a foreign article with that code, otherwise the server assigns the next
+  own code), `groupId`, `revenueGroupId`, `stockTracked`, `stockLocationIds`,
+  `minStockByLocation`, `minStock` (legacy, triggers nothing), `stockKind`,
+  `purchasePriceMicros` (only with the permission `costs`), `externalIds` and
+  `metadata`. In an update `null` clears an optional field; `externalIds` and
+  `metadata` are replaced, `minStockByLocation` is merged per location.
+- **Booking**: `receiveGoods`, `transferStock`, `recordStockLoss`,
+  `changeStockCondition`, `reverseStockMovement`, each answering with a
+  `StockOperation` (`operationId`, `movementIds`, `lotIds`, `warnings[]`).
+  `previewGoodsReceipt` is `receiveGoods` with `dryRun: true`: it books nothing,
+  needs no key (a `null` key counts as none and is not sent) and returns the
+  values only with the permission `costs`. `receiveGoods` with `dryRun: true`
+  is refused before sending: a preview answers without an operation, so it
+  goes through `previewGoodsReceipt`.
+  Transfers, losses and condition changes never overdraw (`exceeds_stock`).
+  Catalogs `STOCK_LOSS_REASONS`, `WITHDRAWAL_TYPES`, `LANDED_COST_TYPES`,
+  `LANDED_COST_ALLOCATIONS`; warnings `INVENTORY_WARNING_CODES`
+  (`insufficient_stock`, `below_minimum`, `return_exceeds_sale`,
+  `reservation_exceeded`) with `isInventoryWarningCode`. A warning is not an
+  error: the booking took effect.
+- **Reservations**: `createReservation` (all or nothing, measured against
+  `available`; `insufficient_available` lists the missing positions in
+  `inventoryShortfalls(error)`), `extendReservation`, `releaseReservation` (all,
+  or per position), `getReservation`, `listReservations` and
+  `iterateReservations`. `Reservation` carries `status` (`active`, `redeemed`,
+  `released`, `expired`; `RESERVATION_STATUSES`), `reference`, `items[]` with
+  `quantity`, `redeemed`, `released`, and `expiresAt`. `expiresInMinutes` is
+  5 to 43,200.
+- **Idempotency**: every write takes `idempotencyKey` (1 to 120 characters,
+  required in the type). The client refuses to send a write without a valid
+  key, because a write without one cannot be retried safely; it never trims or
+  shortens the key. Retry after a timeout with the **same** key: the call takes
+  effect once and returns the stored answer; the same key with other content
+  gives `idempotency_conflict`.
+- **Checked before sending**, nothing else: the key, required ids, integer
+  quantities, amounts and prices (`1.5` is never 1.5 pieces), the range of
+  `expiresInMinutes`, an update without a field, an empty release list,
+  `receiveGoods` with `dryRun: true` (use `previewGoodsReceipt`). All of
+  these throw `KasseneckValidationError` with `scope: 'request'`.
+- **Models**: `Article` gains `description`, `stockKind` and
+  `minStockByLocation` (missing on an older server: `null`, `null`, `{}`).
+  `StockMovement` gains `reservedDelta` (0 for every movement that is not a
+  reservation) and `stockAfter.reserved` (only on reservation movements,
+  otherwise `null`); the movement type `reservation` has `quantityDelta: 0`.
+  The minimum stock (`below_minimum`, `listStock({ belowMinimum })`,
+  `stock.below_minimum`) is now measured against `available = onHand −
+  reserved`, so a reservation alone can trigger it. A fractional value in any
+  of these fields throws `KasseneckValidationError` with `scope: 'response'`.
+- **Events**: `reservation.expired`, `reservation.released` and
+  `reservation.redeemed` in `INVENTORY_WEBHOOK_EVENTS` and
+  `parseInventoryWebhookEvent`, carrying the reservation with its status
+  afterwards. `released` and `redeemed` fire on every effective release or
+  redemption, also a partial one (status stays `active`).
+- **Errors**: `INVENTORY_ERROR_CODES` keeps its 12 codes in front and appends
+  the codes of the write side in contract order (`idempotency_key_required`,
+  `idempotency_conflict`, `exceeds_stock`, `code_taken`,
+  `external_id_taken`, `stock_kind_locked`, `article_inactive`,
+  `insufficient_available`, `reservation_not_found`,
+  `reservation_not_active` …).
+- **Invoice API, reservations**: `issueInvoice` items take `reservationId`
+  (`IssueInvoiceItemInput`, needs `articleId`; not on credit notes, where the
+  server rejects it). New codes at the end of `INVOICE_ERROR_CODES`:
+  `reservation_not_found`, `reservation_mismatch`, `reservation_not_active`;
+  new notice `reservation_expired` (with `reservationId`): the invoice is
+  issued anyway and sells without the reservation. Three new examples in
+  `fixtures/invoice-api-examples/`.
+- **Invoice API, VAT ID check**: an invoice without VAT that relies on the
+  customer's VAT ID (intra-Community supply, reverse charge) is only issued
+  with a result of the VAT ID check (FinanzOnline, otherwise VIES) on the day
+  of issue. Reason: the caller has to decide by the code whether to retry
+  later or not to issue at all.
+  - Codes `vat_id_invalid` and `vat_id_check_pending` in
+    `INVOICE_ERROR_CODES`, after `amount_too_large` and before the
+    reservation codes (the backend order). `vat_id_check_pending` carries
+    `details.retryAfter` (seconds until the next sensible attempt, with the
+    same `idempotencyKey`).
+  - `IssueInvoiceRequest.acceptVatIdRisk` (optional boolean): issues despite
+    a pending check, the issuer bears the risk. An invalid VAT ID blocks even
+    with it. It does not count towards the idempotency of the request.
+  - `Invoice.vatIdProof` (`InvoiceVatIdProof`: `checkedOn`, `source`
+    `finanzonline` | `vies`, `level` 1 | 2, `code`) and `Invoice.vatIdRisk`
+    (`InvoiceVatIdRisk`: `acceptedOn`), otherwise `null`.
+  - `fixtures/invoice-api.schema.json` regenerated (`acceptVatIdRisk`, the
+    two codes), two new examples `issue-vat-id-risk.json` and
+    `issue-error-vat-id-risk.json`.
+- **Contract**: `fixtures/v3/` pulled again from the backend (the 13 new
+  endpoints, catalogs, `warningCodes`, events and the 5b cases in
+  `antworten/lager.json`, the VAT ID cases in `antworten/rechnungen.json`);
+  `PUBLIC_CALLS` and `ALL_CALLS` gain the 13 names (87 public calls);
+  `surface.json` gains the new lists under `inventory` and the two invoice
+  codes.
+
 ## 1.4.0
 
 Inventory API, read side and account webhooks: new subpath `./inventory`.

package/README.md

@@ -212,7 +212,7 @@ adapter:
 | `…/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. |
 | `…/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.** |
 | `…/invoice/calc` | Pure calculation core for invoice totals (integers, no transport, no dependency beyond types). Safe to run in the browser. |
-| `…/inventory` | Inventory API: read articles, locations, stock and the stock ledger, manage account webhooks, verify and parse incoming stock and article events. **Belongs on a server.** |
+| `…/inventory` | Inventory API: read articles, locations, stock and the stock ledger; create and update articles, book goods receipts, transfers and losses, reserve stock at checkout; manage account webhooks, verify and parse incoming stock, article and reservation events. **Belongs on a server.** |
 | `…/react` | Thin React adapter that renders a receipt layout or a receipt sheet. Needs React. |
 | `…/fixtures/*` | Golden receipts (JSON): inputs `receipts/<name>.json`, promised line output `expected/<name>.lines.json`, `manifest.json` with checksums. The backend, the browser register and the Flutter package check against the same files. |
 
@@ -433,30 +433,42 @@ receipt email, and values outside a settings field's value list throw a
 `KasseneckValidationError` before anything is sent, instead of being dropped
 silently. For a layout option of 0.x the message names its English successor.
 
-### `outcome: 'unknown'`: never retry, look it up
+### `outcome: 'unknown'`: never resend blindly
 
 `KasseneckApiError`, `KasseneckHttpError` and `KasseneckNetworkError` carry
 `outcome`. `'rejected'` means the server turned the request down; whether
 anything else is safe to do depends on the code, and on the money calls it
 is only set for the codes listed below. `'unknown'` means the operation **may have been carried out**, for
-`createReceipt` a signed receipt in the chain. Then never send it again: read
-the result back (`getReceipt`, `listMyReceipts`, the original of a
-cancellation) and continue from there. `isOutcomeUnknown(error)` covers all
-three classes. The outcome is unknown for:
+`createReceipt` a signed receipt in the chain. Then never send it again blindly:
+read the result back (`getReceipt`, `listMyReceipts`, the original of a
+cancellation) and continue from there. A call with an `idempotencyKey` (or,
+for invoice items, the same `source` and `reference`) is the exception: send
+it again unchanged (see below).
+`isOutcomeUnknown(error)` covers all three classes. The outcome is unknown for:
 
 - `dialect_mismatch`, `receipt_outcome_unknown`, `cancellation_outcome_unknown`;
 - `response_translation_failed`, unless `details.handled === false`;
 - `response_unreadable`: a signing or money-moving call reported success,
   but the response lacks what the call promises (no receipt, no reference, no
   remaining quantities, no Hobex receipt, no captured payment intent);
-- on the calls with an effect: the signing calls `createReceipt`,
-  `cancelReceipt` and `financeWebService`, and the money calls `hobexPay`
-  (`hobexPayApi`, charges a card), `hobexRefund` (`hobexRefundApi`) and
-  `stripeCaptureIntent`: a network error or timeout after sending began, HTTP
-  5xx, and HTTP 200 with the `Kasseneck-Api-Version: v3` marker but an empty,
+- on every call with an effect (`UNKNOWN_OUTCOME_CALLS`, also in
+  `fixtures/surface.json` as `unknownOutcomeCalls`): the signing calls
+  `createReceipt`, `cancelReceipt` and `financeWebService`, the money calls
+  `hobexPay` (`hobexPayApi`, charges a card), `hobexRefund`
+  (`hobexRefundApi`) and `stripeCaptureIntent`, and since 1.5.1 every other
+  call that books, issues, creates, changes, deletes or sends something:
+  inventory writes and reservations, webhooks, invoices, credit notes,
+  recorded payments, customers, invoice items and SEPA mandates, partner
+  businesses, register settings, pairing, print jobs and receipt emails.
+  There it is a network error or timeout after sending began, HTTP 5xx, and
+  HTTP 200 with the `Kasseneck-Api-Version: v3` marker but an empty,
   non-JSON (also `text/html`) or status-less body (`KasseneckHttpError`,
   `reason` `empty-body`, `not-json` or `missing-status`). HTML without the
-  marker stays `route_missing` with `'rejected'`: no function saw the call;
+  marker stays `route_missing` with `'rejected'`: no function saw the call.
+  Reading calls and dry runs (`previewGoodsReceipt`, `previewInvoice`) stay
+  `'rejected'`, and so do the register sign-in sessions and
+  `createPaymentLinkStripe`: a repeat books nothing (a second short-lived
+  session, a second link nobody else has seen);
 - on the money calls: every error envelope **without a code**, and every
   code that is not one of the rejection codes below. The Hobex and Stripe
   handlers also answer with a plain error message after the provider was
@@ -490,17 +502,33 @@ failed `hobexRefund` throws a `KasseneckApiError`; it never returns `false`,
 because a `false` on an unclear outcome invites a second refund. Even a
 `'rejected'` is no invitation to resend blindly: fix the cause first.
 
-**Never retry these six calls, and never put a retrying layer under the
-package.** A `fetch` passed in `options.fetch` (or a proxy or service worker in
-front of it) must not resend a request by itself after a network error, a
-timeout or a 5xx: a silent second send is a second signed receipt, a second
-charge or a second refund, and the package cannot see it. Look the result up
-instead (`getReceipt`, `listMyReceipts`, the Hobex transaction by its
-`transactionId`, the Stripe session).
-
-`outcome` only covers signing and the money calls. After a network error on
-`issueInvoice` an invoice may still have been issued; retry it with the same
-`idempotencyKey`.
+**Never retry a call with an effect blindly, and never put a retrying layer
+under the package.** A `fetch` passed in `options.fetch` (or a proxy or service
+worker in front of it) must not resend a request by itself after a network
+error, a timeout or a 5xx: a silent second send is a second signed receipt, a
+second charge, a second refund or a second booking, and the package cannot
+see it. Look the result up instead (`getReceipt`, `listMyReceipts`, the Hobex
+transaction by its `transactionId`, the Stripe session).
+
+**With an `idempotencyKey`** (inventory writes and reservations, `issueInvoice`,
+`cancelInvoice`, `createCreditNote`, `recordInvoicePayment`, `createCustomer`
+and `createPartnerCustomer` with a key) the safe retry after `'unknown'` is the
+same request with the **same** key: it takes effect exactly once and returns
+the stored answer (invoices and partner customers mark it with
+`replayed: true`; inventory writes return the stored answer unchanged). Never a
+new key: that books a second time. `createInvoiceItem` has no key; the server recognises a repeat by
+`source` + `reference`, so the same request with the same values is safe
+(`replayed: true`; other data gives `item_reference_conflict`). Without a key
+(receipts, cancellations, money calls, settings, webhooks, `updateCustomer`,
+`createCustomer` and `createPartnerCustomer` without one, `updateInvoiceItem`,
+`withdrawInvoiceItem`, `setCustomerMandate`, `revokeCustomerMandate`) read the
+state first (for invoice items `getInvoiceItem`) and only then decide.
+
+A call through the open transport that this package does not know counts as
+having no effect; say so with `transport(name, params, undefined, undefined,
+{ hasEffect: true })`. `hasEffect: false` only counts together with
+`params.dryRun === true` (a dry run under the name of the real call); without
+it a call with an effect stays `'unknown'`.
 
 ```ts
 import { isOutcomeUnknown, paymentsExpectedCents } from '@kreiseck/kasseneck-api';
@@ -944,7 +972,7 @@ process:
 `hobexPay`, `hobexRefund` and `stripeCaptureIntent` move money. They are never
 retried, neither by the app nor by a retrying `fetch` under the package: on
 `isOutcomeUnknown(error)` look the payment up (see
-[`outcome: 'unknown'`](#outcome-unknown-never-retry-look-it-up)).
+[`outcome: 'unknown'`](#outcome-unknown-never-resend-blindly)).
 - **Hobex HPS via Kasseneck Connect**, described below.
 
 ### Hobex HPS via Kasseneck Connect
@@ -1351,9 +1379,35 @@ was classified.
 `previewInvoice` and `recordInvoicePayment`. An intra-Community supply carries
 `recapitulative_statement_due` (recapitulative statement).
 
+**VAT ID check.** An invoice without VAT that relies on the customer's VAT ID
+(intra-Community supply, reverse charge) is only issued with a result of the
+VAT ID check (FinanzOnline, otherwise VIES) on the day of issue.
+`vat_id_invalid` blocks the invoice. `vat_id_check_pending` means there is no
+result yet: retry after `retryAfter` seconds with the same `idempotencyKey`,
+or send `acceptVatIdRisk: true` to issue anyway, at the issuer's risk. The
+invoice then carries `vatIdRisk` (`acceptedOn`), otherwise the frozen proof
+`vatIdProof` (`checkedOn`, `source`, `level`, `code`); both are `null` where
+nothing was checked.
+
+```ts
+try {
+  await invoices.issueInvoice(request);
+} catch (error) {
+  if (!isInvoiceError(error, 'vat_id_check_pending')) throw error;
+  const retryAfter = error.details['retryAfter'];           // seconds
+  // later: same request and key, or with acceptVatIdRisk: true
+}
+```
+
 **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`.
+key with different data gives `idempotency_conflict`. Since 1.5.1 every invoice
+call with an effect (`issueInvoice`, `cancelInvoice`, `createCreditNote`,
+`recordInvoicePayment`, `createCustomer`, `updateCustomer`) reports
+`outcome: 'unknown'` after a timeout, a network error, HTTP 5xx or an
+unreadable answer (before: `'rejected'`); `previewInvoice` and the reading
+calls stay `'rejected'`. See
+[`outcome: 'unknown'`](#outcome-unknown-never-resend-blindly).
 
 Validation errors arrive as `validation` with field paths
 (`invoiceFieldErrors(error)` → `[{ field: 'items[0].vatRate', message }]`).
@@ -1425,10 +1479,16 @@ the old formula: `fixtures/invoice-totals.json`.
 For online shops and other systems that show or mirror the stock of a
 Kasseneck account: read articles, locations, stock per location and the stock
 ledger, and get every stock change pushed by webhook within seconds, also the
-ones made at the register in the shop. Uses the `api_key` of the account and
-belongs on a **server**. Reading needs the module `lager`; purchase prices and
-stock values appear only when the account has the permission `costs`
-(otherwise the fields are absent, not `null`).
+ones made at the register in the shop. Since 1.5.0 also the write side:
+create and update articles, book goods receipts, transfers, losses and
+condition changes, and reserve stock at checkout (see
+[Shop: reserve and invoice](#shop-reserve-and-invoice)). Uses the `api_key` of
+the account and belongs on a **server**. Reading needs the module `lager`,
+writing additionally the account switch *Lager-API schreiben*, which Kasseneck
+turns on (always on in the test environment, `kr_test_…`; otherwise
+`inventory_api_not_enabled`). Purchase prices and stock values appear only when
+the account has the permission `costs` (otherwise the fields are absent, not
+`null`).
 
 **Integers with a fixed scale:** quantities in thousandths of the base unit
 (`1000` = 1 piece, `250` = 0.250 kg), money in cents, purchase prices in
@@ -1500,16 +1560,22 @@ app.post('/kasseneck-webhook', express.raw({ type: '*/*' }), async (req, res) =>
 - **Events.** `stock.changed` carries the current state of one article at one
   location (`onHand`, `reserved`, `available`, `defective`, `sequence`,
   `updatedAt`) plus `cause` (`sale`, `invoice`, `goods_receipt`, `transfer`,
-  `takeover` …) and `movementId`; changes within 10 seconds are combined into
-  one delivery. `stock.below_minimum` fires once when `onHand` drops below the
-  minimum stock set for the location; `minStock` in the payload is that
-  threshold. The article's own `minStock` never triggers it, and
+  `takeover`, `reservation` …) and `movementId`; changes within 10 seconds are
+  combined into one delivery. `stock.below_minimum` fires once when
+  `available` (`onHand − reserved`, so a reservation alone can trigger it)
+  drops below the minimum stock set for the location (`minStockByLocation` of
+  the article); `minStock` in the payload is that threshold. The article's own
+  `minStock` is a legacy field and never triggers it, and
   `listStock({ belowMinimum: true })` follows the same rule. In movements,
   `goods_receipt` is a goods receipt; `receipt` only ever means a sales receipt
   (`source.type`).
   `article.created`, `article.updated` and `article.deactivated` carry the
-  article as `getArticle` returns it, without purchase prices. Deduplicate on
-  `event.id`; deliveries are retried after 1 min, 5 min, 30 min, 2 h and 12 h.
+  article as `getArticle` returns it, without purchase prices.
+  `reservation.expired`, `reservation.released` and `reservation.redeemed`
+  carry the reservation as `getReservation` returns it, with its status after
+  the change; `released` and `redeemed` also fire for a partial release or
+  redemption (status still `active`). Deduplicate on `event.id`; deliveries
+  are retried after 1 min, 5 min, 30 min, 2 h and 12 h.
 - **Safety net without webhooks.** `listStock({ changedSince })` and
   `listArticles({ updatedSince })` are sorted by `updatedAt` ascending and
   include the boundary, so remembering the last `updatedAt` and asking again
@@ -1528,6 +1594,159 @@ app.post('/kasseneck-webhook', express.raw({ type: '*/*' }), async (req, res) =>
   `invalid_webhook_url`, `event_not_subscribed` and `webhook_inactive` are
   decided on the code with `isInventoryError(error, code)`.
 
+### Writing: articles and bookings
+
+Every write takes an `idempotencyKey` (1 to 120 characters). The same request
+with the same key takes effect exactly once; repeating it returns the stored
+answer of the first call, the same key with different content gives
+`idempotency_conflict`. After a timeout or a network error, repeat with the
+**same** key, never with a new one. Since 1.5.1 every write, reservation and
+webhook call reports `outcome: 'unknown'` in that case (also after HTTP 5xx or
+an unreadable answer; before: `'rejected'`), so `isOutcomeUnknown(error)` is
+the signal to resend with the same key; `previewGoodsReceipt` and the reading
+calls stay `'rejected'`. The client refuses to send a write without
+a valid key, and checks before sending only what is certainly wrong without the
+network (required ids, integer quantities, amounts and prices, the range of
+`expiresInMinutes`); everything else the server decides and reports with its
+code.
+
+```ts
+import { createInventoryClient, isInventoryError, inventoryFieldErrors } from '@kreiseck/kasseneck-api/inventory';
+
+const inventory = createInventoryClient({ apiKey: process.env.KASSENECK_API_KEY! });
+
+// A foreign article with its EAN; without ean the server assigns an own code.
+const roll = await inventory.createArticle({
+  idempotencyKey: 'shop-article-1001',
+  name: 'Kaisersemmel',
+  ean: '9001234567896',
+  unitPriceCents: 65,
+  vatRate: 10,
+  stockTracked: true,
+  minStockByLocation: { haupt: 20000 },   // thousandths: warn below 20 pieces
+  externalIds: { shop: '1001' },          // lookupArticleByCode({ externalSystem: 'shop', externalId: '1001' })
+});
+
+// Goods receipt: 60 pieces at 0.38 EUR each, plus freight spread by value.
+const receipt = await inventory.receiveGoods({
+  idempotencyKey: 'shop-goods-receipt-118',
+  items: [{ articleId: roll.id, quantity: 60000, unitPriceMicros: 380000 }],
+  landedCosts: [{ type: 'freight', amountCents: 450 }],
+  reference: 'LS-2026-118',
+});
+// receipt: { operationId, movementIds, lotIds, warnings: [] }
+
+try {
+  await inventory.recordStockLoss({ idempotencyKey: 'shop-loss-7', reason: 'breakage', items: [{ articleId: roll.id, quantity: 2000 }] });
+} catch (error) {
+  if (isInventoryError(error, 'exceeds_stock')) { /* losses, transfers and condition changes never overdraw */ }
+  else if (isInventoryError(error, 'validation')) console.log(inventoryFieldErrors(error));
+  else throw error;
+}
+```
+
+- **Articles.** `updateArticle({ idempotencyKey, articleId, …fields })` changes
+  only the fields it names; `null` clears an optional one. `externalIds` and
+  `metadata` are replaced as a whole, `minStockByLocation` is merged per
+  location (`{ haupt: null }` removes just that one). `stockKind` is fixed after
+  the first movement (`stock_kind_locked`). `deactivateArticle` frees the code
+  and the external ids. `code_taken` and `external_id_taken` carry `field` and
+  the `articleId` that holds the code in `error.details`. `minStock` is a
+  legacy field without effect; use `minStockByLocation`.
+- **Bookings.** `receiveGoods`, `transferStock`, `recordStockLoss` (`reason`
+  from `STOCK_LOSS_REASONS`; `other` needs `note`, `withdrawal` needs
+  `withdrawalType`), `changeStockCondition` (`sellable` ↔ `defective`) and
+  `reverseStockMovement({ operationId, reason })` answer with a
+  `StockOperation`. `warnings[]` are notices from `INVENTORY_WARNING_CODES`,
+  never errors: the booking took effect. Prices may be sent without the
+  permission `costs`; values come back only in `previewGoodsReceipt`, which is
+  `receiveGoods` with `dryRun: true` (books nothing, needs no key; a `null`
+  key counts as none and is not sent). `receiveGoods` itself refuses
+  `dryRun: true` before sending (`KasseneckValidationError`, `scope:
+  'request'`): a preview is not a booking, call `previewGoodsReceipt`.
+
+### Shop: reserve and invoice
+
+Hold the goods while the customer pays, turn the reservation into a sale with
+the invoice, and let the server release what was never paid:
+
+```ts
+import { createInventoryClient, inventoryShortfalls, isInventoryError, parseInventoryWebhookEvent } from '@kreiseck/kasseneck-api/inventory';
+import { createInvoiceApi } from '@kreiseck/kasseneck-api/invoice';
+
+const inventory = createInventoryClient({ apiKey: process.env.KASSENECK_API_KEY! });
+const invoices = createInvoiceApi({ apiKey: process.env.KASSENECK_API_KEY! });
+
+// 1. Checkout: reserve everything or nothing, measured against `available`.
+async function checkout(order: Order) {
+  try {
+    return await inventory.createReservation({
+      idempotencyKey: `checkout-${order.id}`,   // the same key on every retry of this checkout
+      reference: `Bestellung ${order.number}`,
+      expiresInMinutes: 30,
+      items: [{ articleId: 'kaisersemmel', quantity: 6000 }],   // 6 pieces, at the default location
+    });
+  } catch (error) {
+    if (!isInventoryError(error, 'insufficient_available')) throw error;
+    // Nothing was reserved. Tell the customer what is short:
+    // [{ articleId, locationId, requested: 6000, available: 2000 }]
+    return showShortage(inventoryShortfalls(error));
+  }
+}
+
+// 2. Paid: issue the invoice; the position redeems the reservation.
+async function paid(order: Order, reservationId: string) {
+  const { invoice, notice } = await invoices.issueInvoice({
+    idempotencyKey: `invoice-${order.id}`,
+    priceMode: 'gross',
+    serviceStart: '2026-10-06',
+    orderReference: `Bestellung ${order.number}`,
+    items: [{
+      description: 'Kaisersemmel', quantity: 6, unitPriceCents: 65, vatRate: 10,
+      articleId: 'kaisersemmel', reservationId,
+    }],
+    payment: { method: 'online' },
+  });
+  // Expired before the invoice: no error, the invoice sells without it.
+  if (notice?.some((n) => n.code === 'reservation_expired')) log('sold without reservation', invoice.number);
+}
+
+// 3. Abandoned cart: give the goods back at once instead of waiting for expiry.
+async function abandoned(order: Order, reservationId: string) {
+  await inventory.releaseReservation({ idempotencyKey: `release-${order.id}`, reservationId });
+}
+
+// 4. Webhooks (subscribe to reservation.* with createWebhook, verify as above).
+function onDelivery(rawBody: Buffer) {
+  const event = parseInventoryWebhookEvent(rawBody);
+  if (event && !event.test && event.type === 'reservation.expired') {
+    return shop.cancelUnpaidOrder(event.data.reference);   // the stock is available again
+  }
+}
+```
+
+- **Redeeming.** A position with `reservationId` needs `articleId`. The server
+  checks it when the invoice is issued: `reservation_not_found` (unknown or
+  another account), `reservation_not_active` (already redeemed or released),
+  `reservation_mismatch` (no open quantity of this article at the invoice's
+  stock location, `stockLocationId` or the default location); nothing is issued
+  then. An expired reservation is no error but the notice `reservation_expired`
+  (with `reservationId`). The reservation is redeemed when the invoice is
+  booked into stock: selling less than reserved releases the rest, selling
+  more gives the warning `reservation_exceeded`. Credit notes take no
+  `reservationId`.
+- **Expiry.** Without `expiresInMinutes` the account's default applies (7 days);
+  5 to 43,200 minutes are allowed. `extendReservation` sets a new expiry from
+  now, only for an active reservation that is not yet due
+  (`reservation_not_active`). `releaseReservation` without `items` releases
+  everything, with `items` per position (without `quantity` the whole rest);
+  the status becomes `released` only when nothing is open.
+- **Events.** `reservation.expired`, `reservation.released` and
+  `reservation.redeemed` carry the reservation with its status afterwards.
+  `listReservations({ status: 'active' })` or `({ reference })` is the safety
+  net without webhooks; the stock ledger shows reservations as movements of
+  type `reservation` with `quantityDelta: 0` and the change in `reservedDelta`.
+
 ## Migrating from 0.x
 
 1.0 is one breaking step: the wire, the exported names and the contract files
@@ -1603,7 +1822,7 @@ in machine form what both sides agreed on, among them:
 |---|---|---|
 | `pos-settings-defaults.json` | field names and defaults of the register settings as sent on `/api/v3` (`business`, `device`), derived from the backend contract in `fixtures/v3/` | `npm run fixtures:kasse` |
 | `stored/pos-settings-defaults.json` | the same defaults in the stored (internal, German) form (`betrieb`, `geraet`) | `npm run fixtures:kasse` |
-| `surface.json` | base URLs (`baseUrls.public`, `baseUrls.pos`), the calls per path (`calls`, and the backend's `routes`), settings value lists (`enums`, keyed by field), other register lists (`pos`), register error codes, permission keys, shortcut actions, partner, invoice and inventory lists | `npm run fixtures:oberflaeche` |
+| `surface.json` | base URLs (`baseUrls.public`, `baseUrls.pos`), the calls per path (`calls`, and the backend's `routes`), the calls with an effect whose outcome is `unknown` after a timeout, network error, 5xx or unreadable answer (`unknownOutcomeCalls`, sorted), settings value lists (`enums`, keyed by field), other register lists (`pos`), register error codes, permission keys, shortcut actions, partner, invoice and inventory 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` |
 | `pos-texts.json` | the register's message catalogue | `npm run fixtures:texte` |
 | `invoice-texts.json` | invoice texts in both languages | `npm run fixtures:rechnungstexte` |