庫存資料串接

庫存以商品 × 倉庫的組合管理。1 個商品可在多個倉庫持有庫存，各自持有獨立的庫存量。庫存異動會以入出庫紀錄（stock_movement）全數記錄。

主要欄位（inventory）

相關權限範圍

• inventory.read — 庫存量讀取
• inventory.write — 庫存量的更新（入出庫紀錄）
• warehouse.read / warehouse.write — 倉庫主檔操作

主要端點

GET   /v1/inventory                  ← 庫存一覽
GET   /v1/inventory/{product_id}     ← 商品的各倉庫庫存
PATCH /v1/inventory/{product_id}     ← 庫存量更新（差分或絕對值）
POST  /v1/stock_movements            ← 記錄入出庫
GET   /v1/stock_movements            ← 入出庫紀錄
GET   /v1/warehouses                 ← 倉庫一覽

更新方法（差分 vs 絕對值）

// 以絕對值覆寫（盤點時）
PATCH /v1/inventory/prd_a01
{ "warehouse_id": "wh_main", "quantity": 42 }

// 以差分增減（入出庫時、建議）
POST /v1/stock_movements
{
  "product_id": "prd_a01",
  "warehouse_id": "wh_main",
  "delta": -3,
  "reason": "sale",
  "reference_id": "rcp_xyz789"
}

差分指定時同時更新的衝突較不易發生，且會留下紀錄，故建議使用。

Webhook 事件

• inventory.changed — 庫存量異動
• inventory.low_stock — 低於閾值
• inventory.out_of_stock — 缺貨
• stock_movement.created — 入出庫紀錄

WMS 串接模式

WMS 主導（建議）

• WMS 為庫存的正
• 向 ReceiptRoller POST stock_movement 進行同步
• 設定為在 ReceiptRoller 端收據發行時不自動減算庫存

ReceiptRoller 主導

• ReceiptRoller 為庫存的正（適用於小規模店鋪）
• 透過 POS 連動在收據發行時自動減算
• WMS 以 inventory.changed Webhook 追隨

引當（reserved）的使用方式

在 EC 接單「加入購物車」「結帳前」等需要暫扣時，先增加 reserved。結帳完成時從 quantity 減算，取消則將 reserved 退回。

相關指南

• 商品主檔（PIM）
• Webhook 的概要
• 返回開發者幫助中心