Wolt integrace — Nastavení a zprovoznění

Tento návod popisuje, jak propojit prodejní automat s platformou Wolt, aby zákazníci mohli objednávat produkty z automatu přes aplikaci Wolt.

---

Předpoklady

Než začnete, ujistěte se, že máte:

• Wolt Merchant Portal účet s přístupem k POS integraci (client credentials + webhook secret)

• Cloudflare účet s Workers plánem (Free tier stačí)

• Běžící Contember instance s nasazeným datovým modelem (GraphQL API)

• Nainstalované CLI: wrangler (Cloudflare Workers CLI), yarn

---

Krok 1: Cloudflare KV Namespace

Worker ukládá OAuth tokeny do Cloudflare KV (key-value storage). Vytvořte namespace:

cd worker
npx wrangler kv:namespace create KV_STORE

Výstup bude obsahovat ID namespace. Vložte ho do worker/wrangler.toml:

[[kv_namespaces]]
binding = "KV_STORE"
id = "<vaše-kv-namespace-id>"

---

Krok 2: Secrets a environment variables

Secrets (citlivé údaje)

Nastavte přes Cloudflare Dashboard (Workers → Settings → Variables) nebo přes CLI:

npx wrangler secret put WOLT_CLIENT_ID
npx wrangler secret put WOLT_CLIENT_SECRET
npx wrangler secret put WOLT_WEBHOOK_SECRET
npx wrangler secret put CONTEMBER_API_TOKEN
npx wrangler secret put CONTEMBER_BASE_API_URL

Secret	Zdroj	Popis
WOLT_CLIENT_ID	Wolt Merchant Portal → POS Integration	OAuth client ID
WOLT_CLIENT_SECRET	Wolt Merchant Portal → POS Integration	OAuth client secret
WOLT_WEBHOOK_SECRET	Wolt Merchant Portal → Webhooks	HMAC-SHA256 klíč pro ověření webhooků
CONTEMBER_API_TOKEN	Contember instance	API token s oprávněním pro čtení/zápis
CONTEMBER_BASE_API_URL	Contember instance	Např. https://engine.contember.example.com

Proměnné (veřejné)

Tyto jsou nastaveny v worker/wrangler.toml:

[vars]
CONTEMBER_PROJECT_SLUG = "vending-admin-hub"

---

Krok 3: Registrace webhooku na Wolt

V Wolt Merchant Portal zaregistrujte webhook:

• URL: https://<váš-worker-domain>/wolt/webhook/orders

• Události: order.notification

• Autentizace: HMAC-SHA256 (Wolt podepisuje každý request hlavičkou wolt-signature)

Poznámka: Worker domain najdete v Cloudflare Dashboard → Workers → váš worker → Triggers → Routes. Typicky vending-admin-hub-worker.<vaše-subdomena>.workers.dev.

---

Krok 4: OAuth onboarding (propojení tokenu)

Wolt používá OAuth 2.0 Authorization Code flow. Při prvním propojení:

1. V Wolt Merchant Portal spusťte POS integraci pro dané venue

2. Wolt přesměruje na váš redirect endpoint s parametrem code:

   https://<váš-worker-domain>/wolt/redirect?code=<authorization-code>

3. Worker automaticky:

   • Vymění code za access_token + refresh_token

   • Extrahuje venue_id z JWT access tokenu

   • Uloží tokeny do KV pod klíčem wolt:tokens:<venue_id>

4. Odpověď potvrdí úspěch:

   { "success": true, "venue_id": "698b0a73e34c89727b175fbc" }

Důležité: OAuth flow je potřeba provést jen jednou pro každé venue. Worker si poté automaticky obnovuje tokeny pomocí refresh tokenu.

---

Krok 5: Propojení automatu s Wolt venue

V administraci (Contember admin) nastavte na entitě Machine pole woltVenueId:

1. Otevřete detail automatu v admin UI

2. Do pole Wolt Venue ID vložte venue_id, které jste obdrželi v kroku 4

3. Uložte

Tím se vytvoří vazba: když přijde Wolt objednávka pro dané venue, systém ví, na kterém automatu ji zpracovat.

---

Krok 6: Sladění produktů (SKU mapping)

Aby systém správně přiřadil objednané položky ke skutečným produktům v automatu:

1. Každý produkt v Contember musí mít vyplněné pole SKU

2. Stejné SKU musí být nastavené na odpovídajícím produktu ve Wolt katalogu

3. Produkt musí mít dostupný inventory (status = available) v daném automatu

Pokud se SKU neshoduje nebo produkt nemá skladové zásoby, objednávka bude automaticky zamítnuta.

---

Krok 7: Deploy workeru

cd worker
npx wrangler deploy

Worker se nasadí na Cloudflare a bude:

• Přijímat webhooky od Wolt

• Zpracovávat objednávky

• Spouštět cron job (každých 5 minut) pro uvolnění prošlých rezervací

---

Ověření funkčnosti

1. Testovací objednávka

Vytvořte objednávku přes Wolt aplikaci na propojené venue.

2. Kontrola logů

V Cloudflare Dashboard → Workers → váš worker → Logs (Real-time) uvidíte:

[WOLT WEBHOOK RAW REQUEST] { ... }
[WOLT WEBHOOK] Notification: { type: "order.notification", ... }
[WOLT WEBHOOK] Full order: { id: "...", items: [...], ... }
[WOLT] Order #12345 accepted + ready: { cartId: "...", pickupCode: "847291", ... }
[WOLT] Reserved 2 inventory items until 2026-02-20T15:30:00.000Z

3. Kontrola v admin UI

• V sekci Objednávky by se měla objevit nová objednávka se statusem in_process

• Pickup code je vygenerovaný 6místný číselný kód

• V sekci Inventory budou odpovídající položky ve stavu reserved

4. MQTT příkaz do automatu

V MQTT logu automatu by se měl objevit příkaz ORDER_RESERVE odeslaný do 5 sekund po vytvoření objednávky.

---

Řešení problémů

Problém	Příčina	Řešení
Webhook vrací 401	Špatný WOLT_WEBHOOK_SECRET	Ověřte, že secret v Cloudflare odpovídá nastavení ve Wolt
No tokens in KV for venue	OAuth flow nebyl proveden	Spusťte onboarding (krok 4)
No machine for venue	woltVenueId nenastaveno na Machine	Nastavte venue ID v admin UI (krok 5)
Objednávka zamítnuta — out of stock	SKU neexistuje nebo nedostatek zásob	Zkontrolujte SKU shodu a stav inventory
Token refresh failed	Prošlý refresh token	Proveďte OAuth onboarding znovu (krok 4)