Wiki

2026-04-22 13:01:47 +02:00
commit 803acf3da3
14 changed files with 1101 additions and 0 deletions
--- a/Integrace-Eshop-API.md
+++ b/Integrace-Eshop-API.md
@@ -0,0 +1,138 @@
+# Integrace Eshop API
+
+Server-to-server integrace pro eshopy. Eshop posílá data přímo ze svého backendu – párování probíhá podle e-mailu zákazníka, **žádný browser tracking není potřeba**.
+
+Podrobná dokumentace pro programátora eshopu je v [`docs/integrace-eshop.md`](../docs/integrace-eshop.md).
+
+---
+
+## Autentizace
+
+Každý request musí obsahovat Site Key:
+
+```
+X-Site-Key: <site-key>
+# nebo
+?site_key=<site-key>
+```
+
+---
+
+## Endpointy
+
+### `POST /api/eshop/cart` – Stav košíku
+
+Volejte při každé změně košíku. Párování probíhá podle `email`.
+
+```json
+{
+  "email": "zakaznik@example.cz",
+  "currency": "CZK",
+  "total_no_tax": 198.00,
+  "cart_id": null,
+  "items": [
+    {
+      "code": "PROD-001",
+      "name": "Název produktu",
+      "qty": 2,
+      "unit_no_tax": 99.00,
+      "total_no_tax": 198.00,
+      "url": "https://eshop.cz/produkt"
+    }
+  ]
+}
+```
+
+**Odpověď:**
+```json
+{ "ok": true, "cart_id": 42, "status": "open", "changed": true }
+```
+
+Logika controlleru `EshopCartController`:
+1. Najde nebo vytvoří `Contact` podle emailu
+2. Hledá poslední otevřený košík pro daný kontakt
+3. Porovná obsah (hash z items + currency + total) – pokud se nezměnil, jen obnoví `last_seen_at`
+4. Uloží/aktualizuje `FunnelCart`, upsertuje `TrackingProduct` záznamy
+5. Zapiše `FunnelEvent` (event `cart_upsert`, source `eshop`)
+
+---
+
+### `POST /api/eshop/order` – Dokončení objednávky
+
+Volejte jednorázově při úspěšném dokončení.
+
+```json
+{
+  "email": "zakaznik@example.cz",
+  "cart_id": 42,
+  "order_id": "ORD-2026-0042",
+  "total_no_tax": 198.00,
+  "currency": "CZK",
+  "checkout": {
+    "shipping_no_tax": 89.00,
+    "shipping_label": "PPL",
+    "cod_fee_no_tax": 29.00
+  }
+}
+```
+
+**Odpověď:**
+```json
+{ "ok": true, "cart_id": 42, "order_id": "ORD-2026-0042", "status": "converted" }
+```
+
+Logika controlleru `EshopOrderController`:
+1. Najde kontakt podle emailu
+2. Hledá košík – podle `cart_id`, nebo poslední `open`/`empty` pro daný kontakt
+3. Pokud košík nenajde → `404 cart_not_found`
+4. Uloží data objednávky, status → `converted`
+5. Zapiše `FunnelEvent` (event `cart_completed`, source `eshop`)
+
+---
+
+## Logování
+
+Všechny requesty na `/api/eshop/*` jsou logovány do `storage/logs/eshop-YYYY-MM-DD.log` přes middleware `LogEshopRequest`. E-mail je maskován (`za***@example.cz`).
+
+---
+
+## Chybové stavy
+
+| HTTP | Kód | Řešení |
+|------|-----|--------|
+| 401 | – | Chybný nebo chybějící Site Key |
+| 422 | – | Chybí povinné pole |
+| 404 | `cart_not_found` | Žádný otevřený košík pro daný email |
+
+---
+
+## PHP příklad
+
+```php
+// Při změně košíku
+$res = Http::withHeaders(['X-Site-Key' => config('tracking.site_key')])
+    ->post('https://app.domena.cz/api/eshop/cart', [
+        'email'       => $customer->email,
+        'currency'    => 'CZK',
+        'total_no_tax' => $cart->totalNoTax(),
+        'cart_id'     => session('ft_cart_id'),
+        'items'       => $cart->items->map(fn($i) => [
+            'code'        => $i->sku,
+            'name'        => $i->name,
+            'qty'         => $i->qty,
+            'unit_no_tax' => $i->unitPriceNoTax,
+        ])->toArray(),
+    ]);
+
+session(['ft_cart_id' => $res->json('cart_id')]);
+
+// Při dokončení
+Http::withHeaders(['X-Site-Key' => config('tracking.site_key')])
+    ->post('https://app.domena.cz/api/eshop/order', [
+        'email'    => $customer->email,
+        'cart_id'  => session('ft_cart_id'),
+        'order_id' => $order->id,
+        'total_no_tax' => $order->totalNoTax(),
+        'currency' => 'CZK',
+    ]);
+```