商品主檔（PIM）、類別資料

商品 PIM 類別 SKU 資料串接

本文的對象
適用於想串接商品主檔（PIM）資料的開發者。用於與 EC、POS、WMS 的同步。

ReceiptRoller 的商品（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 → ReceiptRoller（主檔起點）

將 EC 的商品主檔為正，以 Webhook 或定期批次反映至 ReceiptRoller。ReceiptRoller 成為「讀取端」。

ReceiptRoller → POS

在 ReceiptRoller 端一元管理商品，POS 串接應用程式接收 product.updated Webhook 播送至各 POS。

雙向同步（注意）

雙向需要衝突解決邏輯。以 updated_at 比較，或決定某一方為「主檔時段」的運用較現實。

類別

持有樹狀結構（父子關係）
各商品屬於 1 個類別
也可在類別本身設定稅率，讓商品繼承的模式