# 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 |