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.

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.

{
  "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ěď:

{ "ok": true, "cart_id": 42, "status": "open", "changed": true }

Logika controlleru EshopCartController:

Najde nebo vytvoří Contact podle emailu
Hledá poslední otevřený košík pro daný kontakt
Porovná obsah (hash z items + currency + total) – pokud se nezměnil, jen obnoví last_seen_at
Uloží/aktualizuje FunnelCart, upsertuje TrackingProduct záznamy
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í.

{
  "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ěď:

{ "ok": true, "cart_id": 42, "order_id": "ORD-2026-0042", "status": "converted" }

Logika controlleru EshopOrderController:

Najde kontakt podle emailu
Hledá košík – podle cart_id, nebo poslední open/empty pro daný kontakt
Pokud košík nenajde → 404 cart_not_found
Uloží data objednávky, status → converted
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

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

3.5 KiB Raw Blame History Unescape Escape