商品マスター（PIM）・カテゴリデータ

商品 PIM カテゴリ SKU データ連携

この記事の対象
商品マスター（PIM）データを連携したい開発者向け。EC・POS・WMSとの同期に使います。

レシートローラーの商品（product）はSKU単位の最小販売単位を表します。バリエーション（サイズ・色など）を持つ場合は親商品と子バリエーションの2階層構造を取ります。

主なフィールド

フィールド	内容
`id`	商品ID（`prd_`）
`sku`	店舗内で一意のSKUコード
`jan_code`	JAN/EAN/UPCバーコード（任意）
`name`	商品名
`price`	標準価格
`tax_rate`	税率
`category_id`	カテゴリ
`parent_id`	親商品（バリエーションの場合）
`attributes`	サイズ・色などの属性（自由JSON）
`images[]`	商品画像URL

主なエンドポイント

GET    /v1/products             ← 一覧（フィルタ可）
GET    /v1/products/{id}         ← 個別
POST   /v1/products              ← 作成
PATCH  /v1/products/{id}         ← 部分更新
DELETE /v1/products/{id}         ← 削除（論理削除）
POST   /v1/products/batch        ← バッチ作成・更新
GET    /v1/categories            ← カテゴリツリー

SKU管理のベストプラクティス

SKUは店舗内で一意。命名規則を事前に定める
外部システムのIDを external_id 属性に保存しておくと再同期が楽
バリエーション展開時は親SKUと子SKUの命名規則を分けておく（例：SHIRT-001 / SHIRT-001-M-RED）
削除より非公開（is_active=false）を推奨。過去のレシートと紐付けが残る

EC・POSとの同期パターン

EC → レシートローラー（マスター起点）

ECの商品マスターを正とし、Webhookまたは定期バッチでレシートローラーへ反映。レシートローラーは「読む側」になる。

レシートローラー → POS

レシートローラー側で商品を一元管理し、POS連携アプリが product.updated Webhookを受けて各POSへ配信。

双方向同期（注意）

双方向は競合解決ロジックが必要。updated_at 比較や、片方を「マスター時間帯」を決める運用が現実的。