Tvåvägs Square POS-synkronisering med thMenu: Webhook + REST Polling

Driver du ett 32-platsers specialty-café i Brooklyn med både Square Terminal och en thMenu QR-meny, kan prissynkronisering bli en operativ mardröm. Baristan ändrar latten från 5,50 till 5,75 USD, men QR-menyn visar fortfarande gammalt pris. Den här artikeln beskriver en hybridarkitektur: webhook först, polling som skyddsnät.

Webhook som primär kanal

Squares catalog.version.updated-event utlöses vid varje ändring av item, variation eller modifier. Rikta det till thMenu Worker-endpointen /api/integrations/square/webhook: verifiera HMAC-SHA256-signaturen, läs object_id och hämta detaljer via /v2/catalog/object/{id}.

Workern mappar svaret till D1_MENU: variations[0].price_money.amount i öre (575) blir products.price = 5,75 USD. Kolumnen square_object_id möjliggör upsert. Squares SLA levererar 99,2 % av webhooks inom 15 minuter.

Polling och rate limit

Vid nätverksavbrott eller sällsynta Square-fördröjningar på 5+ minuter täcker en 30-minuters cron luckor genom att fråga /v2/catalog/search filtrerat på de senaste 35 minuterna.

Squares gräns är 10 anrop/sek. För 500 artiklar: 100 per batch_retrieve och 1 sekunds paus.

Skattemappning: US vs SE

Brooklyn tar 8,875 % NY sales tax; ett café i Stockholm tar 12 % moms på restaurangtjänster. Lägg till tax_us_pct och tax_se_pct i products.

FAQ

Vad händer om webhooks misslyckas?Polling utjämnar inom 30 minuter.

Synkroniseras lagret?Nej, endast katalog.

Vilken plan?Pro och Platinum.

Var detta hjälpsamt? Dela det.