# 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',
    ]);
```