如果您在布鲁克林经营一家 32 座的精品咖啡馆,同时使用 Square Terminal 和 thMenu QR 菜单,保持两个系统的价格同步会成为运营噩梦。咖啡师将拿铁从 5.50 美元改为 5.75 美元,但 QR 菜单仍显示旧价。本文介绍一种混合架构:webhook 优先,轮询作为安全网。
Webhook 作为主通道
Square 的 catalog.version.updated 事件在任意 item、variation 或 modifier 变更时触发。将其路由到 thMenu Worker 端点 /api/integrations/square/webhook:校验 HMAC-SHA256 签名,提取 object_id,然后调用 /v2/catalog/object/{id}。
Worker 把响应映射到 D1_MENU:variations[0].price_money.amount(分,575)变成 products.price = 5.75 USD。square_object_id 列保障 upsert。Square 公布的 SLA 是 99.2% 在 15 分钟内送达。
轮询与速率限制
网络中断或 Square 罕见延迟超过 5 分钟时,30 分钟 cron 会查询 /v2/catalog/search,过滤最近 35 分钟更新的项目。
Square 限速为 每秒 10 请求。500 个 item:每次 batch_retrieve 拉 100 个,再暂停 1 秒,完全避免 429。
税率映射:美国 vs 中国
布鲁克林征收 8.875% 纽约销售税;上海店面征收 13% 增值税。在 products 添加 tax_us_pct 与 tax_cn_pct 列,按 restaurant.country 选择。
常见问题
如果 webhook 全失败?轮询会在 30 分钟内修复偏差。
是否同步库存?不,仅同步目录。
哪个套餐?Pro 与 Platinum。
觉得有用?分享给朋友。