Skip to navigation

追蹤文件站台與 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 規格」的「組合品庫存」「庫存」「組合品」,錯誤字串見「錯誤碼」。