Obousměrná synchronizace Square POS s thMenu: Webhook + REST Polling

Pokud provozujete 32místnou specialty kavárnu v Brooklynu se Square Terminalem a QR menu thMenu, synchronizace cen mezi oběma systémy se může stát provozní noční můrou. Barista změní latte z 5,50 na 5,75 USD, ale QR menu stále zobrazuje starou cenu. Tento článek popisuje hybridní architekturu: webhook nejdříve, polling jako záchranná síť.

Webhook jako hlavní kanál

Událost Square catalog.version.updated se spustí při změně item, variation nebo modifier. Nasměrujte ji na endpoint Workeru thMenu /api/integrations/square/webhook: ověřte HMAC-SHA256 podpis, načtěte object_id a stáhněte detaily přes /v2/catalog/object/{id}.

Worker mapuje odpověď do D1_MENU: variations[0].price_money.amount v centech (575) → products.price = 5,75 USD. Sloupec square_object_id umožňuje upsert. SLA dodává 99,2 % webhooků do 15 minut.

Polling a rate limit

Při výpadku sítě nebo vzácném zpoždění Square nad 5 minut 30minutový cron volá /v2/catalog/search s filtrem posledních 35 minut.

Limit Square je 10 dotazů/sekundu. Pro 500 položek: 100 v batch_retrieve a 1 sekunda pauzy.

Mapování daní: US vs CZ

Brooklyn účtuje 8,875 % NY sales tax; pražská pobočka 12 % DPH na stravování. Přidejte tax_us_pct a tax_cz_pct do products.

FAQ

Co když webhook selže?Polling rozdíl vyrovná do 30 minut.

Synchronizuje i zásoby?Ne, pouze katalog.

Který plán?Pro a Platinum.

Bylo to užitečné? Sdílejte to.