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

Smaregi 商品 POS連動資料對應

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

同步的操作方式是在商品管理畫面點選「從Smaregi同步」按鈕手動執行。詳細內容請參閱Smaregi的POS連動設定。

欄位對應表

Smaregi `/pos/products`	ReceiptRoller（`ProductDto`）	備註
`productId`	`SmaregiProductId`	Smaregi內部ID。作為再次同步時的比對鍵。
`productCode`	`SKU`	Smaregi的商品代碼（門市經營者一般使用的編號）。
`productName`	`ProductName`	商品名稱（最多85個字）。
`description`	`Description`	商品說明（若為空值則不更新）。
`categoryId`	`Category`	從 `/pos/categories` 解析出 `categoryName` 後儲存。
`price`	`BasePrice`	轉換為decimal型別。再次同步時僅在數值大於0時才會覆寫。
`cost`	`BaseCostPrice`	轉換為decimal型別。若為空值或0，則保留ReceiptRoller端既有的數值。
`displayFlag`	— （篩選條件）	`"0"`（終端不顯示）的商品不列入同步對象。

不會被匯入的項目

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

稅率（taxRate）— Smaregi的 /pos/products 並不會回傳稅率。回傳的僅有 taxDivision（0=含稅、1=未稅、2=非課稅）這種稅務分類的類別值。實際稅率是由Smaregi的租戶設定所決定，因此ReceiptRoller端在新建時會設定預設的10%，更新時則維持既有稅率。
JAN碼 — Smaregi的 /pos/products 端點並無JAN碼欄位。需在ReceiptRoller端另行登錄。
品牌、供應商、型號、系列等 — 因Smaregi標準欄位中無對應概念。需在ReceiptRoller端另行登錄。
商品圖片 — Smaregi端的圖片同步在目前版本尚未支援。
規格變化款（顏色差異、尺寸差異等個別商品）— Smaregi端的父子商品結構，在目前版本並不會展開為個別商品。
門市別價格 — 若Smaregi依門市設定不同價格，目前版本僅會匯入合約整體的基本價格。可於ReceiptRoller端使用 StorePricesJson 進行覆寫。
ReceiptRoller特有欄位（Brand / Supplier / JanCode / ModelNumber / TaxRate 等）— Smaregi端無對應概念、或不進行同步的欄位，在再次同步時不會被覆寫。ReceiptRoller端手動登錄的內容會被保留。

比對與新建規則

從Smaregi匯入商品資料時，僅會透過 SmaregiProductId 的完全一致來比對既有商品。若不一致，則會以新商品的形式新增至PIM。系統不會依商品名稱或SKU進行自動合併（因為同名也可能是不同商品）。

同步時機

Smaregi → ReceiptRoller（商品主檔匯入）：於商品管理畫面點選「從Smaregi同步」按鈕手動執行。系統會從Smaregi Platform API（/pos/products + /pos/categories）取得所有商品與分類清單，並以 SmaregiProductId 比對後進行新增或更新。
再次同步時的行為：既有商品（相同 SmaregiProductId）的 ProductName / Description / SKU / Category / BasePrice / BaseCostPrice（僅在有值時）會被覆寫更新。而在ReceiptRoller端新增的 Brand / Supplier / JanCode / TaxRate 等則會予以保留。
ReceiptRoller → Smaregi：目前版本尚未支援。在ReceiptRoller端登錄的商品不會自動反映至Smaregi。

注意事項

若在Smaregi端實體刪除商品，該商品透過 SmaregiProductId 的比對將失效。建議在Smaregi中改用 displayFlag 進行不顯示設定（不顯示的商品雖不列入同步對象，但與過去交易明細的關聯仍會保留）。
成本（cost）在Smaregi端也屬於選填項目。若Smaregi端未輸入成本，則需在ReceiptRoller端手動輸入 BaseCostPrice。若要運用利潤分析功能，建議一併檢視成本資料的完整性。
若混有稅率非10%（如輕減稅率8%等）的商品，請於同步後在ReceiptRoller端個別將 TaxRate 變更為0.08。由於Smaregi端不會傳來稅率資訊，系統不會自動設定。
大量商品的首次同步，可能因API的速率限制而需要一些時間。超過方案商品數量上限的商品將會被略過。

透過交易明細取得的商品資訊

即使未執行商品主檔同步，每次交易時，SmaregiTransactionDetail 中的 productCode / productName / categoryName 仍會作為交易明細匯入。這些資料會以交易當下的快照形式保存，並作為收據顯示與商品別銷售統計的基礎資料發揮作用。詳細內容請參閱Smaregi交易資料的對應關係。