services

docs/api/routes/misc/getCategories.md

@@ -0,0 +1,78 @@
+# `GET /misc/getCategories`
+
+Protected. Requires a valid session cookie (`credentials: 'include'`).
+
+Returns the full JTL category list and a nested tree. Same data source as the legacy `getKat` socket handler in dashApp.
+
+## Response `200`
+
+```json
+{
+  "categories": [
+    {
+      "kKategorie": 16,
+      "kOberKategorie": 0,
+      "nSort": 10,
+      "cName": "Dünger",
+      "count": 142
+    }
+  ],
+  "tree": [
+    {
+      "kKategorie": 16,
+      "kOberKategorie": 0,
+      "nSort": 10,
+      "cName": "Dünger",
+      "count": 142,
+      "children": [
+        {
+          "kKategorie": 39,
+          "kOberKategorie": 16,
+          "nSort": 0,
+          "cName": "Bio",
+          "count": 47,
+          "children": []
+        }
+      ]
+    }
+  ]
+}
+```
+
+### `categories[]`
+
+Flat list — useful for lookups by ID (`katNames`-style maps).
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `kKategorie` | number | Category ID |
+| `kOberKategorie` | number | Parent category ID (`0` = root) |
+| `nSort` | number | Sort order among siblings |
+| `cName` | string \| null | German display name (Sprache 1, Plattform 1, Shop 0) |
+| `count` | number | Active articles directly in this category |
+
+### `tree[]`
+
+Nested hierarchy rooted at `kOberKategorie === 0` (or orphaned nodes). Each node has the same fields plus `children[]`, sorted by `nSort` then `cName`.
+
+Use `tree` for sidebar navigation; use `categories` for ID → name maps or [`GET /article/search`](../article/search.md) `filter` param.
+
+## Errors
+
+| Status | Body |
+|--------|------|
+| 401 | `{ "error": "Unauthorized" }` |
+| 500 | `{ "error": "..." }` |
+
+## Example
+
+```js
+const res = await fetch('http://localhost:4208/api/misc/getCategories', {
+  credentials: 'include',
+});
+const { categories, tree } = await res.json();
+
+const katNames = Object.fromEntries(
+  categories.map((kat) => [kat.kKategorie, kat.cName])
+);
+```

docs/api/routes/misc/getSteuer.md

@@ -0,0 +1,63 @@
+# `GET /misc/getSteuer`
+
+Protected. Requires a valid session cookie (`credentials: 'include'`).
+
+Returns tax classes and their rates from JTL-Wawi (`tSteuerklasse` + `tSteuersatz`, domestic zone `kSteuerzone = 1`).
+
+## Response `200`
+
+```json
+{
+  "steuerklassen": [
+    {
+      "kSteuerklasse": 1,
+      "cName": "Normaler Steuersatz",
+      "nStandard": 1,
+      "fSteuersatz": 19
+    },
+    {
+      "kSteuerklasse": 2,
+      "cName": "Ermäßigter Steuersatz",
+      "nStandard": 0,
+      "fSteuersatz": 7
+    }
+  ]
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `kSteuerklasse` | Tax class ID (used on articles as `kSteuerklasse`) |
+| `cName` | Display name |
+| `nStandard` | `1` if this is the default tax class |
+| `fSteuersatz` | VAT rate in percent |
+
+### Brutto calculation
+
+Look up the article's `kSteuerklasse` in `steuerklassen`, then:
+
+```js
+function getBrutto(netto, kSteuerklasse, steuerklassen) {
+  const row = steuerklassen.find((s) => s.kSteuerklasse === kSteuerklasse);
+  if (!row) return null;
+  return netto * (1 + row.fSteuersatz / 100);
+}
+```
+
+Load once on app init and reuse for search results and article detail.
+
+## Errors
+
+| Status | Body |
+|--------|------|
+| 401 | `{ "error": "Unauthorized" }` |
+| 500 | `{ "error": "..." }` |
+
+## Example
+
+```js
+const res = await fetch('http://localhost:4208/api/misc/getSteuer', {
+  credentials: 'include',
+});
+const { steuerklassen } = await res.json();
+```