Двусторонняя синхронизация Square POS с thMenu: Webhook + REST Polling

Если вы держите специализированное кафе на 32 места в Бруклине с Square Terminal и QR-меню thMenu, синхронизация цен превращается в операционный кошмар. Бариста изменил латте с 5,50 до 5,75 USD, а QR-меню всё ещё показывает старую цену. Эта статья описывает гибридную архитектуру: webhook — основной канал, polling — страховка.

Webhook как основной канал

Событие Square catalog.version.updated срабатывает при любом изменении item, variation или modifier. Направьте его на Worker thMenu по адресу /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. SLA Square — 99,2% доставка за 15 минут.

Polling и rate limit

При сбоях сети или редких задержках Square (5+ минут) cron каждые 30 минут опрашивает /v2/catalog/search с фильтром по последним 35 минутам.

Лимит Square — 10 запросов/сек. Для 500 позиций: 100 в одном batch_retrieve и пауза 1 секунда — 429 ошибок не будет.

Маппинг налогов: US vs RU

Бруклин — 8,875% NY sales tax; локация в Москве — 10% НДС на общепит. Добавьте tax_us_pct и tax_ru_pct в products; restaurant.country выбирает.

FAQ

Если webhook не сработает? Polling закрывает разрыв за 30 минут.

Синхронизируется ли остаток? Нет, только каталог.

Какой план? Pro и Platinum.

Было полезно? Поделитесь.