Si gestionas un café de especialidad de 32 plazas en Brooklyn con Square Terminal y un menú QR de thMenu, mantener los precios sincronizados puede convertirse en una pesadilla operativa. El barista cambia el latte de 5,50 a 5,75 USD, pero el QR sigue mostrando el precio anterior. Este artículo explica una arquitectura híbrida: webhook primero, polling como red de seguridad.
Webhook como canal principal
El evento catalog.version.updated de Square se dispara con cualquier cambio de item, variation o modifier. Redirígelo al Worker de thMenu en /api/integrations/square/webhook: verifica la firma HMAC-SHA256, extrae object_id y consulta /v2/catalog/object/{id}.
El Worker mapea la respuesta a D1_MENU: variations[0].price_money.amount en centavos (575) se convierte en products.price = 5,75 USD. La columna square_object_id permite upsert. Square entrega 99,2 % de webhooks en 15 minutos.
Polling y límite de tasa
Para caídas de red o retrasos de Square (5+ minutos), un cron de 30 minutos consulta /v2/catalog/search filtrado por los últimos 35 minutos.
El límite Square es 10 solicitudes/segundo. Para 500 items basta: 100 por batch_retrieve, luego 1 segundo de pausa. Los 429 desaparecen.
Mapeo de impuestos: US vs ES
Brooklyn carga 8,875 % de NY sales tax; un local en Madrid aplica 10 % de IVA hostelería. Añade tax_us_pct y tax_es_pct a products; restaurant.country elige cuál mostrar.
FAQ
¿Si fallan los webhooks? El polling lo resuelve en 30 minutos.
¿Sincroniza inventario? No, solo catálogo.
¿Qué plan? Pro y Platinum.
¿Te resultó útil? Compártelo.
Artículos relacionados
¿Qué es un menú QR? La guía completa para restaurantes
Un menú QR permite a tus clientes acceder a tu carta al instante desde el móvil,…
Pasar del menú en papel al menú QR digital: guía paso a paso
¿Quieres adoptar los menús QR pero no sabes por dónde empezar? Esta guía cubre f…
Menús QR geolocalizados: servir distintos idiomas según la IP del visitante
Cómo un resort de 180 plazas en Antalya enruta el mismo QR a menús turcos, alema…