Synchronisation Bidirectionnelle Square POS avec thMenu : Webhooks + Polling REST

Si vous exploitez un café de 32 places à Brooklyn utilisant à la fois Square Terminal et un menu QR thMenu, garder les prix synchronisés peut vite devenir un cauchemar opérationnel. Le barista passe le latte de 5,50 à 5,75 USD, mais le menu QR affiche encore l'ancien prix. Cet article décrit une architecture hybride : webhook d'abord, polling en filet de sécurité.

Webhook : canal principal

L'événement Square catalog.version.updated se déclenche à chaque modification d'item, de variation ou de modifier. Routez-le vers le Worker thMenu sur /api/integrations/square/webhook : vérifiez la signature HMAC-SHA256, lisez object_id puis appelez /v2/catalog/object/{id}.

Le Worker mappe la réponse dans D1_MENU : variations[0].price_money.amount en centimes (575) devient products.price = 5,75 USD. La colonne square_object_id permet l'upsert. Square garantit 99,2 % de livraison sous 15 minutes.

Polling et rate limit

En cas de panne réseau ou de retard rare de Square (5+ minutes), un cron de 30 minutes interroge /v2/catalog/search filtré sur les 35 dernières minutes et rattrape les manquements du webhook.

Le rate limit Square est de 10 requêtes/seconde. Pour 500 items, c'est largement suffisant à condition de batcher : 100 items par batch_retrieve, puis 1 seconde de pause — les 429 disparaissent.

Mapping taxes : US vs FR

Brooklyn applique 8,875 % de NY sales tax ; une boutique parisienne du même opérateur applique 10 % de TVA restauration. Ajoutez tax_us_pct et tax_fr_pct dans products, et choisissez selon restaurant.country.

FAQ

Si les webhooks tombent ? Le polling rattrape sous 30 minutes.

Synchronise-t-on aussi le stock ? Non, seulement le catalogue.

Quel plan ? Pro et Platinum.

Cet article vous a été utile ? Partagez-le.