Square POS と thMenu の双方向同期:Webhook + REST ポーリングのハイブリッド

ブルックリンで Square Terminal と thMenu QR メニューを併用する 32 席のスペシャルティカフェを運営している場合、価格同期は運用上の悪夢になりがちです。バリスタがラテを 5.50 から 5.75 USD に変更しても、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 は 15 分以内に 99.2% 配信です。

ポーリングとレート制限

ネットワーク障害や 5 分以上の Square 遅延に備え、30 分の cron が /v2/catalog/search を直近 35 分のフィルタで実行します。

Square のレート制限は 毎秒 10 リクエスト。500 アイテムでは、batch_retrieve ごとに 100 件を取得し、1 秒のスリープで 429 を回避します。

税率マッピング:US vs JP

ブルックリンは 8.875% NY セールスタックス、東京店舗は 10% 消費税。products に tax_us_pct と tax_jp_pct を追加し、restaurant.country で選択します。

FAQ

Webhook が失敗したら?ポーリングが 30 分以内に差分を埋めます。

在庫も同期?いいえ、カタログのみです。

どのプラン?Pro と Platinum。

お役に立ちましたか?シェアしてください。