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 KR

브루클린은 8.875% 뉴욕 판매세, 서울 매장은 10% 부가세. products에 tax_us_pct와 tax_kr_pct를 추가합니다.

FAQ

Webhook이 실패하면?폴링이 30분 안에 차이를 메웁니다.

재고도 동기화?아니요, 카탈로그만.

어느 플랜?Pro와 Platinum.

도움이 되셨나요? 공유해 주세요.