ProductDto 參考

PIM 商品資料模型參考 POS串接

本文的對象
本文適用於透過 API、MCP、Webhook 處理 ReceiptRoller 商品主檔（PIM）的開發者。說明從 POS 匯入的商品資訊、各店鋪價格、變體、原價等結構。

ProductDto 是 ReceiptRoller 的商品主檔（PIM）的正規模型。在店鋪儀表板的商品管理畫面登錄的商品、從 Square Catalog 同步的商品、以 CSV 匯入的商品 — 全部都彙集到這一個型別。

商品主檔以商業帳戶為單位管理，可在底下的店鋪共用。若想讓各店鋪擁有不同的價格，請使用後述的 StorePricesJson。

主要欄位

識別碼、基本資訊

欄位	型別	內容
`OrganizationId`	string	商業帳戶 ID。PartitionKey。
`ProductId`	string	RR 內部的商品 ID（GUID）。RowKey。
`ProductName`	string	商品名稱。
`SKU`	string	庫存管理單位（SKU 代碼）。Square 串接時為 Variation 的 SKU。
`JanCode`	string	JAN 條碼（Barcode）。
`Category`	string	類別名稱（字串）。非階層結構，而是扁平的分類。
`Brand` / `Supplier` / `Description` / `Unit`	string	品牌、供應商、說明、單位（個、本、kg 等）。

商品規格

ModelNumber / Series / Color / Size / Weight / ContentVolume / Material / Specification / CountryOfOrigin。皆為 string 且為選填。預期用於零售類的商品主檔。

B2B、物流、報關

CasePackSize（箱入數）、MinimumOrderQuantity、LeadTimeDays、HsCode（HS 碼）、StorageRequirements（保管條件）、Certifications。這些是為進行批發、進出口的商家提供的擴充欄位。

價格、原價

欄位	型別	內容
`BasePrice`	decimal	未稅銷售價格（基準價格）。
`BaseCostPrice`	decimal	原價（基準）。利益分析的基礎資料。
`TaxRate`	decimal	稅率。預設 `0.10`（日本標準）。
`StorePricesJson`	string (JSON)	各店鋪的價格、原價覆寫。可以 `StorePrices` 屬性作為陣列存取。有 `GetPriceForStore(storeId)` / `GetCostPriceForStore(storeId)` 輔助方法。

計算輔助屬性：TaxIncludedPrice（含稅價格）、ProfitMargin（毛利率 %）、MinVariantPrice / MaxVariantPrice（有變體時的價格區間）。

圖片

ImageUrl（封面圖片 URL）與 ImageUrlsJson（整個圖庫的 JSON 陣列）。可以 ImageUrls 屬性作為陣列讀取。為與收據 1 圖片商品的向後相容，當 ImageUrlsJson 為空時，會後備為包含 ImageUrl 的單元素陣列。

變體

HasVariants（是否有變體）、VariantOptionsJson（顏色、尺寸等的選項定義）、Variants（ProductVariantDto 的陣列）。將顏色差異、尺寸差異作為 1 商品處理時使用。

POS 串接用欄位

欄位	內容
`SquareCatalogObjectId`	Square Catalog 的 Item 物件 ID（`#XXXX` 格式）。同步時設定。
`SquareVariationId`	Square Catalog 的 Variation 物件 ID。保存第一個變體。

預購、狀態、稽核

IsPreOrder、PreOrderReleaseDate、PreOrderNote（預購商品的發售日 / 註釋）。Status（Active / Discontinued / Draft）、SortOrder、InternalMemo、CreatedAt、UpdatedAt。

從 POS 的對應

各 POS 的商品資料對應到 ProductDto 的哪個欄位，彙整在店鋪幫助的個別文章中。請注意不同 POS 能處理的項目差異很大。

Square 商品資料與 ReceiptRoller 商品資料的對應 — 透過 Catalog API 的完整雙向同步
Smaregi 商品資料與 ReceiptRoller 商品資料的對應 — 目前版本僅透過交易明細

注意事項

OrganizationId 與 ProductId 的組合為唯一的鍵。即使商品名稱相同，商業帳戶不同即為不同商品。
BaseCostPrice 直接用於營業額分析的利益計算。由於值的更新不伴隨歷史記錄，若需要原價變更時的快照，需要另外設計（正在 t-e9a2f447 系列的成本資料擴充中檢討）。
StorePricesJson 為各店鋪覆寫，未設定的店鋪會直接套用 BasePrice / BaseCostPrice。
從 Square Catalog 匯入的商品會設定 SquareCatalogObjectId，再同步時會以此 ID 比對。請勿手動覆寫。