pfand for cpp

API.md

@@ -2,6 +2,15 @@
 
 HTTPS API that mirrors the JTL-POS ↔ Wawi sync protocol. Use this to build a custom POS client that syncs catalog data and submits orders.
 
+Two servers implement this protocol:
+
+| Implementation | Entry | Handlers |
+|---|---|---|
+| **Node.js** | `server.js` | [`src/endpoints/`](src/endpoints/) |
+| **C++** | `jtlsrv-cpp/` | [`jtlsrv-cpp/src/endpoints/`](jtlsrv-cpp/src/endpoints/) |
+
+Clients talk to either over the same paths and shapes. See [Node vs C++](#node-vs-c) for the few behavioral differences.
+
 Base URL: `https://<host>:<port>` (default port `4443`)
 
 Paths may be called as `/v1/...` or `/api/v1/...` — both resolve to the same handlers.
@@ -193,9 +202,12 @@ Notable fields:
 | `isCompositeProduct` | `"1"` if the article is a Stückliste parent |
 | `imghash` | Pass to `/v1/pimage?path=...` |
 | Deposit fields | Present when JTL-POS Pfand attributes are set |
+| `attributes` | Article attributes from `tArtikelAttribut` (incl. Pfand) |
 
 Many other product fields are filled with static defaults (`sort`, `use_stock`, `unit`, etc.) for JTL-POS compatibility.
 
+**Node only:** `prices[]` applies per–customer-group net overrides from `tPreis` / `tPreisDetail`. C++ currently fills every group with the base gross price.
+
 ### `GET /v1/productcomposite`
 
 BOM rows for composite (Stückliste) parents.
@@ -263,9 +275,10 @@ No `limit` — returns all groups newer than the cursor.
 
 ### `GET /v1/cimage` — Category image
 
-| Param | Required |
-|---|---|
-| `path` | yes — image hash from `imghash` / `imgsrc` |
+| Param | Required | Notes |
+|---|---|---|
+| `path` | yes | Image hash from `imghash` / `imgsrc` |
+| `size` | no | **C++ only.** Target max dimension in px (default `200`). Use `0` for the full unresized image. Node always serves a ≤200px resize and ignores `size`. |
 
 **Success (200):** binary image body (`image/jpeg`, `image/png`, …), resized by the server.
 
@@ -435,4 +448,39 @@ Invalid JSON body → `500` with `[]`.
 | `GET` | `/v1/cimage` | Category image by hash |
 | `POST` | `/v1/order` | Create order(s) |
 
-Handlers live in [`src/endpoints/`](src/endpoints/).
+Handlers: Node [`src/endpoints/`](src/endpoints/), C++ [`jtlsrv-cpp/src/endpoints/`](jtlsrv-cpp/src/endpoints/).
+
+---
+
+## Node vs C++
+
+Both expose the same route table, pairing flow, cursor sync protocol, and order request/response contract. A client written against this document works with either binary.
+
+### Same (client-visible)
+
+| Area | Behavior |
+|---|---|
+| Routes | Identical methods and paths (`/v1/...` and `/api/v1/...`) |
+| Pairing | Short `authCode` → discovery; 6-digit → pair / revoke / register |
+| Init / list params | Same cursor names and default `limit` values |
+| Category / composite / deleted | Same JSON field names and cursor semantics |
+| Order | Same `{ "orders": [...] }` body, result array, `OK` / `ERROR`, HTTP 200 vs 500 |
+| Auth | Neither validates `authToken` on sync/order after pairing |
+
+### Differences that affect clients
+
+| Area | Node | C++ |
+|---|---|---|
+| **Group prices** | Per–customer-group overrides from `tPreis` | Every group gets the base gross price |
+| **Image `size`** | Ignored; always resize ≤200px | Honored (`size`, default `200`; `0` = full) |
+| **`discountPercent`** | Fixed 2 decimals (`"0.00"`) | `std::to_string` of the double (e.g. `"0.000000"`) |
+| **Init when DB is down** | Handler throws → HTTP 500 | Returns all counts as `"0"` (HTTP 200) |
+| **Product `created_at`** | Formatted `YYYY-MM-DD HH:mm:ss` | Whatever ODBC returns for `dErstelldatum` |
+
+### Safe client strategy
+
+- Treat optional product fields (per-group price overrides) as best-effort when talking to C++.
+- Prefer `price` for the default gross; do not assume `prices[]` differ by group unless you know you are on Node.
+- Call images with `?path=<hash>` only; omit `size` unless you need C++-specific sizing.
+- Parse `discountPercent` as a number, not a fixed-format string.
+- On init, treat HTTP 500 and all-zero counts similarly as “nothing to sync / unavailable”.