Wiki

2026-04-22 13:01:47 +02:00
commit 803acf3da3
14 changed files with 1101 additions and 0 deletions
--- a/API-reference.md
+++ b/API-reference.md
@@ -0,0 +1,121 @@
+# API Reference
+
+Všechny API endpointy vyžadují `X-Site-Key` header nebo `?site_key=` parametr (ověření přes `ResolveTrackingSite` middleware).
+
+---
+
+## Browser Tracking API
+
+Endpointy používané `collect.js` z prohlížeče.
+
+### `POST /api/collect`
+Obecný tracking event (page_view, newsletter_subscribe, gallery_config_submit...).
+
+```json
+{
+  "visitor_id": "string (required)",
+  "event": "string (required)",
+  "payload": {},
+  "occurred_at": "ISO 8601"
+}
+```
+
+### `POST /api/identify`
+Identifikace návštěvníka (propojení visitor_id s emailem nebo ftclid tokenem).
+
+```json
+{
+  "visitor_id": "string",
+  "email": "string (nebo ftclid)",
+  "ftclid": "string",
+  "name": "string",
+  "user_id": "string"
+}
+```
+
+### `GET /api/me`
+Vrátí informace o aktuálním návštěvníkovi (kontakt propojený s visitor_id).
+
+### `POST /api/cart`
+Upsert košíku z prohlížeče.
+
+```json
+{
+  "visitor_id": "string",
+  "event": "cart_upsert",
+  "payload": {
+    "cart_id": null,
+    "cart": {
+      "items": [{ "code": "...", "qty": 1, "unit_no_tax": 99 }],
+      "totals": { "currency": "CZK", "total_no_tax": 99 }
+    }
+  }
+}
+```
+
+### `POST /api/cart/complete`
+Dokončení košíku z prohlížeče.
+
+```json
+{
+  "visitor_id": "string",
+  "event": "cart_completed",
+  "payload": {
+    "cart_id": 42,
+    "order_id": "ORD-001",
+    "total": 198.00,
+    "currency": "CZK",
+    "checkout": {
+      "shipping_no_tax": 89,
+      "shipping_label": "PPL",
+      "cod_fee_no_tax": 29
+    }
+  }
+}
+```
+
+---
+
+## Eshop API (server-to-server)
+
+Viz [Integrace Eshop API](Integrace-Eshop-API).
+
+### `POST /api/eshop/cart`
+Košík z eshopu – párování podle emailu. Logováno do `eshop-YYYY-MM-DD.log`.
+
+### `POST /api/eshop/order`
+Objednávka z eshopu – párování podle emailu.
+
+---
+
+## Integrace Webhooky
+
+### `POST /api/integrations/smartemailing/webhook`
+Příjem webhooků ze SmartEmailing (odhlášení, události).
+
+---
+
+## Veřejné endpointy
+
+### `GET /feeds/products.xml`
+XML produktový feed (`ProductFeedController`).
+
+### `GET /e/o/{token}`
+Email open tracking pixel.
+
+### `GET /email/u/{token}`
+Unsubscribe stránka z emailu.
+
+### `GET /unsubscribe/{contact}` *(signed URL)*
+Globální odhlášení kontaktu.
+
+---
+
+## Chybové kódy
+
+| HTTP | Situace |
+|------|---------|
+| 401 | Chybějící nebo neplatný Site Key |
+| 404 | Záznam nenalezen (cart_not_found...) |
+| 422 | Validační chyba – chybí povinné pole |
+| 500 | Serverová chyba |