Square商品資料與ReceiptRoller商品資料的對應關係

登錄於Square Catalog的商品，在完成與ReceiptRoller的連動後，會自動轉換並匯入至ReceiptRoller的商品主檔（ProductDto）中。本文將整理欄位層級的對應關係，以及Square特有的注意事項。

Square Catalog的結構

在Square Catalog中，商品是以下列3個層級來表示。ReceiptRoller將ITEM對應為一項商品，並從第一個ITEM_VARIATION取得SKU與價格。

• ITEM — 商品本體（商品名稱、說明、分類）
• ITEM_VARIATION — 尺寸、顏色差異等個別商品（SKU、價格）
• CATEGORY — 分類（分類名稱）

欄位對應表

固定值與規則值

• TaxRate = 0.10（日本標準稅率10%）為統一設定值。商品個別稅率在目前版本並不會匯入。
• Status = "Active"。已在Square端刪除的商品（is_deleted = true）不列入同步對象。

不會被匯入的項目

以下Square Catalog欄位，在目前版本中並不會匯入至ReceiptRoller端。

• 第2個以後的ITEM_VARIATION — Square的尺寸差異、顏色差異，尚未對應到ReceiptRoller端的規格變化款功能（HasVariants / Variants）。僅第一項會被用作SKU與價格。
• 商品圖片（image_ids）— 因Square圖片API的取得屬於獨立流程，目前狀況並不列入同步對象。
• 修飾項目（modifier_list_info）— 加料、選項等附加項目目前尚未支援。
• 成本資訊 — 因Square同樣沒有標準欄位，BaseCostPrice 會維持為0。請在ReceiptRoller端另行登錄。
• ReceiptRoller特有欄位（JanCode / Brand / Supplier / ModelNumber 等）— 因Square無對應概念，在再次同步時不會被覆寫。ReceiptRoller端手動登錄的內容會被保留。

同步時機

• Square → ReceiptRoller（商品主檔匯入）：於商品管理畫面點選「從Square同步」按鈕手動執行。系統會從Square Catalog API（ListCatalog）一併取得ITEM與CATEGORY，並以 SquareCatalogObjectId 比對後進行新增或更新。
• 再次同步時的行為：既有商品（相同 SquareCatalogObjectId）的 ProductName / Description / SKU / Category / BasePrice / SquareVariationId 會被覆寫更新。而在ReceiptRoller端新增的 JanCode / Brand / BaseCostPrice 等則會予以保留。
• ReceiptRoller → Square：目前版本尚未支援。在ReceiptRoller端登錄的商品不會自動反映至Square Catalog。

比對與新建規則

從Square Catalog匯入商品資料時，僅會透過 SquareCatalogObjectId 的完全一致來比對既有商品。若不一致，則會以新商品的形式新增至PIM。

系統不會依商品名稱或分類進行自動合併（因為同名也可能是不同商品）。若要整合重複項目，請於商品管理畫面手動操作。

注意事項

• 若在Square端實體刪除商品，該商品透過 SquareCatalogObjectId 的比對將失效，再次新增時會被登錄為不同商品。建議在Square中改用「停用」而非刪除。
• 若使用Square的尺寸差異、顏色差異（多個Variation），僅第一個Variation會被匯入。若要依尺寸個別登錄為不同商品，請在Square端也將其登錄為不同的ITEM。
• 幣別非JPY時會自動換算（最小貨幣單位 ÷ 100）。不建議混用多種幣別的營運方式。
• 在ReceiptRoller端登錄 BaseCostPrice（成本）後，會反映至銷售分析的利潤計算中。由於Square沒有成本欄位，請務必於ReceiptRoller端另行輸入。

相關指南

• ProductDto 參考文件（開發者專用）— 正式模型的完整欄位規格
• Square交易資料的對應關係
• Square顧客資料的對應關係
• Square的POS連動設定