追蹤文件站台與 API 的異動
2026 年 11 月 11 日
這一版讓組合品有自己的庫存額度,並新增組合品庫存 API。既有組合品的庫存行為會改變,已經串接組合品的整合請先看最後一節。
組合品有自己的庫存額度
組合品要能下單,現在兩關都要過:組合品自身的額度,以及各組成規格的庫存。
isNegativeStockAllowed為true時,組合品自身不限量,只看組成規格,與過去相同。- 為
false時,組合品自身的可售數(在庫數扣掉未出貨訂單佔用)用完就不能再下單,即使組成規格還有庫存。適合限量禮盒這類情境。 - 出貨時組合品自身的在庫數會跟著扣減,出貨後取消會回補,與一般規格相同。
- 組合品自身的額度不會產生預購數量,預購只由允許負庫存的組成規格計算。
新增組合品庫存 API
GET /v1/bundles/{id}/stock查詢組合品自身的inventoryQty、availableQty與isNegativeStockAllowed。id 指向一般規格時回傳404 not_found。POST /v1/bundles/stock/batch以絕對值設定組合品自身的在庫數,每一筆用bundleId(組合 SKU 序號)指定;quantity與isNegativeStockAllowed都是選填,省略的欄位維持現值。bundleId不存在或指向一般規格時,該筆回報bundle not found,不影響其他筆。
兩支端點與規格庫存使用同樣的庫存讀取/寫入權限。
規格庫存可以設定是否允許負庫存
GET /v1/skus/{id}/stock的回應新增isNegativeStockAllowed。POST /v1/skus/stock/batch的每一筆可以選填isNegativeStockAllowed,省略時維持現值;用料號命中多顆規格時,每一顆都套用同一個值。
⚠️ 庫存批次的 quantity 改為選填,沒帶不再壓成 0
POST /v1/skus/stock/batch 與 POST /v1/bundles/stock/batch 的 quantity 改為選填。過去 POST /v1/skus/stock/batch 沒帶 quantity 會被當成 0、把在庫數蓋成 0;現在沒帶就維持現有在庫數,也不留異動紀錄,所以只想改 isNegativeStockAllowed 時可以只帶它。quantity 與 isNegativeStockAllowed 都沒帶時,該筆回報 quantity or isNegativeStockAllowed is required,不影響其他筆。
組合品主檔新增 isNegativeStockAllowed
POST /v1/bundles、PUT /v1/bundles/{id}、POST /v1/bundles/batch 可以帶 isNegativeStockAllowed,查詢結果也會帶出。新增時省略為 true(不限量);更新時省略保留現有值。組合品自身不限量以外時,GET /v1/bundles/{id} 的 availableQty 也不會超過組合品自身的可售數。
⚠️ 既有組合品與錯誤字串的異動
- 過去透過本 API 建立的組合品,
isNegativeStockAllowed都是false、在庫數為 0。 這一版上線後,這些組合品會因為自身額度為 0 而無法下單。要維持過去「只看組成規格」的行為,請用PUT /v1/bundles/{id}或POST /v1/bundles/stock/batch把isNegativeStockAllowed設為true;要限量就用POST /v1/bundles/stock/batch設定在庫數。 POST /v1/skus/stock/batch的skuId指向組合 SKU 時,錯誤字串由bundle SKU stock cannot be set through this API改為bundle SKU stock must be set through /v1/bundles/stock/batch。有比對這個字串的整合需要調整。
各端點的完整規則見「API 規格」的「組合品庫存」「庫存」「組合品」,錯誤字串見「錯誤碼」。