Square 商品データとレシートローラー商品データのマッピング

Square 商品カタログ Catalog API POS連携データマッピング

Square Catalog に登録された商品は、レシートローラー連携後、レシートローラーの商品マスタ（ProductDto） に自動的に変換されて取り込まれます。本記事では、フィールド単位の対応関係と、Square 固有のクセをまとめます。

Square Catalog では商品が以下の 3 階層で表現されます。レシートローラーは ITEM を 1 つの商品としてマッピングし、最初の ITEM_VARIATION から SKU と価格を取得します。

Square Catalog	レシートローラー（`ProductDto`）	備考
ITEM `id`	`SquareCatalogObjectId`	Square 側の商品 ID。再同期時の照合キー。
ITEM `item_data.name`	`ProductName`	商品名。
ITEM `item_data.description`	`Description`	商品説明。
CATEGORY `category_data.name`	`Category`	ITEM の `category_id` から名前を解決して保存。
最初の ITEM_VARIATION `id`	`SquareVariationId`	Variation の ID。1 商品 = 1 Variation 前提で保存。
最初の ITEM_VARIATION `item_variation_data.sku`	`SKU`	在庫管理単位。
最初の ITEM_VARIATION `price_money.amount`	`BasePrice`	通貨が JPY ならそのまま、それ以外は 100 で割って小数に変換（Square は最小通貨単位で保存）。

Square Catalog の以下のフィールドは、現バージョンでは RR 側に取り込まれません。

2 つ目以降の ITEM_VARIATION — Square のサイズ違い・色違いは、RR 側のバリエーション機能（HasVariants / Variants）にはまだマッピングされていません。最初の 1 件のみが SKU・価格として使われます。
商品画像（image_ids） — Square 画像 API の取得は別フローのため、現状は同期対象外。
変調項目（modifier_list_info） — トッピング・オプションなどの追加項目は未対応。
原価情報 — Square にも標準フィールドが無いため、BaseCostPrice は 0 のまま。RR 側で別途登録してください。
RR 固有フィールド（JanCode / Brand / Supplier / ModelNumber など）— Square には対応概念がないため、再同期で上書きされません。RR 側で手動登録した内容は保持されます。

Square → RR（商品マスタ取り込み）：商品管理画面の「Square から同期」ボタンで手動実行。Square Catalog API（ListCatalog）から ITEM と CATEGORY を一括取得し、SquareCatalogObjectId で照合して新規追加・更新します。
再同期時の挙動：既存商品（同じ SquareCatalogObjectId）は ProductName / Description / SKU / Category / BasePrice / SquareVariationId が上書きされます。RR 側で追加した JanCode / Brand / BaseCostPrice などは保持されます。
RR → Square：現バージョンでは未対応。RR 側で登録した商品は Square Catalog には自動反映されません。

Square Catalog から商品が取り込まれる際、既存商品との照合は SquareCatalogObjectId の完全一致のみで行われます。一致しなければ新規商品として PIM に追加されます。

商品名やカテゴリでの自動マージは行いません（同名でも別商品の可能性があるため）。重複を統合したい場合は商品管理画面から手動で行ってください。

Square 側で商品を物理削除すると、その商品の SquareCatalogObjectId による照合が効かなくなります。再追加時は別商品として登録されます。Square では削除より「非アクティブ化」を推奨します。
Square のサイズ違い・色違い（複数 Variation）を使っている場合は、最初の Variation だけが取り込まれます。サイズごとに別商品として登録したい場合は、Square 側でも別 ITEM として登録してください。
通貨が JPY 以外の場合は自動で換算されます（最小通貨単位 ÷ 100）。複数通貨を混在させる運用は推奨されません。
RR 側で BaseCostPrice（原価）を登録すると、売上分析の利益計算に反映されます。Square には原価フィールドが無いため、RR 側で必ず別途入力してください。