Se gestisci un café di specialità da 32 posti a Brooklyn con Square Terminal e un menu QR thMenu, tenere i prezzi sincronizzati può diventare un incubo. Il barista cambia il latte da 5,50 a 5,75 USD, ma il menu QR mostra ancora il prezzo vecchio. Questo articolo descrive un'architettura ibrida: prima il webhook, poi il polling come rete di sicurezza.
Webhook come canale primario
L'evento Square catalog.version.updated si attiva ad ogni modifica di item, variation o modifier. Indirizzalo al Worker thMenu su /api/integrations/square/webhook: verifica la firma HMAC-SHA256, estrai object_id e chiama /v2/catalog/object/{id}.
Il Worker mappa la risposta in D1_MENU: variations[0].price_money.amount in centesimi (575) diventa products.price = 5,75 USD. La colonna square_object_id permette l'upsert. Square consegna il 99,2% dei webhook entro 15 minuti.
Polling e rate limit
Per downtime di rete o ritardi rari di Square (5+ minuti), un cron di 30 minuti interroga /v2/catalog/search filtrato sugli ultimi 35 minuti.
Il rate limit Square è 10 richieste/secondo. Per 500 item è ampiamente sufficiente: 100 per batch_retrieve, poi 1 secondo di pausa.
Mapping fiscale: US vs IT
Brooklyn applica 8,875% di NY sales tax; un locale a Milano applica 10% di IVA ristorazione. Aggiungi tax_us_pct e tax_it_pct in products; restaurant.country sceglie il valore.
FAQ
Se cadono i webhook? Il polling colma il gap entro 30 minuti.
Sincronizza anche l'inventario? No, solo il catalogo.
Quale piano? Pro e Platinum.
Ti è stato utile? Condividilo.
Articoli correlati
Cos'è un menù QR? La guida completa per i ristoranti
Un menù QR permette ai clienti di accedere alla tua carta istantaneamente dallo …
Dal menù cartaceo al menù QR digitale: guida passo passo
Vuoi adottare i menù QR ma non sai da dove iniziare? Questa guida copre fotograf…
Menu QR geolocalizzati: servire lingue diverse in base all'IP del visitatore
Come un resort da 180 coperti ad Antalya instrada lo stesso QR a menu turchi, te…