139 lines
3.5 KiB
Markdown
139 lines
3.5 KiB
Markdown
# 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',
|
||
]);
|
||
```
|