Square POS ile thMenu Çift Yönlü Senkronizasyonu: Webhook + REST Polling Hibrit

New York Brooklyn'de 32 koltuklu bir specialty cafe işletiyorsanız ve hem Square Terminal hem thMenu QR menüsü kullanıyorsanız, ürün fiyatı değiştiğinde iki sistemi senkron tutmak operasyonel kâbusa dönüşebilir. Barista latte fiyatını 5.50 → 5.75 USD güncelledi, ancak müşterinin QR menüsünde hâlâ eski fiyat görünüyor. Bu makale, webhook'a güvenen ama network kesintisinde polling fallback'i devreye sokan hibrit bir mimari anlatıyor.

Webhook tabanlı primary sync

Square Catalog API catalog.version.updated event'i, herhangi bir item, variation veya modifier değiştiğinde tetiklenir. Bu webhook'u thMenu worker'ında /api/integrations/square/webhook endpoint'ine yönlendirin: HMAC-SHA1 signature ile doğrulayın (Square x-square-hmacsha256-signature header'ı kullanır), olay payload'undan object_id'yi çekin, ardından /v2/catalog/object/{id} ile detayları fetch edin.

Worker bu cevabı thMenu D1_MENU şemasına map'ler: Square variations[0].price_money.amount (cent cinsinden, örn. 575) → products.price (5.75 USD). square_object_id kolonu D1'de saklanır; aynı item bir sonraki güncellemede tekrar webhook gelirse upsert yapılır. İlk 15 dakikada %99.2 webhook iletim oranı Square'in resmi SLA'sıdır.

Polling fallback ve rate limit

Ağ kesintisi, Cloudflare'in geçici outage'ı veya Square'in webhook gecikmesi (nadiren 5 dakikayı aşar) gibi senaryolar için 30 dakikalık cron polling ikinci bir savunma katmanıdır. Cron job /v2/catalog/search endpoint'ine son 35 dakikadaki updated_at filtreli sorgu atar; webhook'un kaçırdığı her şey burada yakalanır.

Square API rate limit'i saniyede 10 istek'tir. 500 ürünlü bir cafe için bu yeterlidir, ancak batching gerekir: cron job tek seferde 100 ürünü batch_retrieve ile çeker, ardından 1 saniye bekler. Worker queue + setTimeout(1000) kombinasyonu ile 429 hatalarından kaçınılır.

Tax mapping: US sales tax vs Türkiye KDV

Brooklyn'deki cafe %8.875 NY sales tax uygular; aynı işletmenin İstanbul lokasyonu varsa %10 KDV (yemek-içecek) söz konusudur. thMenu products tablosuna tax_us_pct ve tax_tr_pct şeklinde iki ayrı kolon ekleyin; runtime'da restaurant.country alanına göre hangisinin gösterileceği seçilir.

• Square Locations API her lokasyon için ayrı tax rate döndürür; sync sırasında location_id ile eşleştirin.
• Müşteri menüsünde "fiyatlara KDV dahildir" / "Tax not included" disclaimer'ı locale bazlı gösterin.
• Stripe Tax entegrasyonu varsa, mapping'i Stripe Tax Code'lara (txcd_*) genişletin.

SSS

Webhook'lar gelmezse ne olur? 30 dakika içinde polling fallback farkı yakalar. Müşteri o pencerede eski fiyatı görebilir; bu kabul edilebilir bir trade-off'tur.

Inventory de senkron mu? Bu kılavuz catalog (ürün/fiyat) senkronu için. Inventory için Square Inventory API ayrı bir webhook akışı kullanır, henüz thMenu'ya entegre değil.

Hangi thMenu planı gerekli? Square entegrasyonu Pro ve Platinum planlarda mevcuttur; Starter planda manuel ürün girişi yapılır.

Faydalı buldunuz mu? Paylaşın.