批次更新(SKU)庫存
批次覆蓋多筆(SKU)的在庫數,一次寫入多筆,逐筆結果互不影響。
⚠️ inventoryQuantity 是絕對的在庫數,不是增減量——每一筆送出的都是「更新後庫存應該是多少」,不是要加減的差量;把差量當成這個欄位送出,會直接把在庫數蓋成錯誤的值,這是使用這支端點最容易出錯、也最需要注意的地方。
送出空陣列或沒有 body 會在受理前被拒絕,回傳 400 empty_batch;已受理的請求一律回傳 HTTP 200,逐筆的處理結果放在回應 body 的 items 裡,單筆失敗不會讓其他筆一起失敗。
每一筆用下列其中一種方式指定規格:
skuId(正整數):就是那一顆規格。同時帶了outerSysCode時以skuId為準- 只帶
outerSysCode(料號):租戶內帶有這個料號的每一顆一般規格(去除前後空白、不分大小寫)都會設成同一個inventoryQuantity。skuId帶 0 視同沒帶,所以固定序列化這個欄位的 ERP 也可以送 0
兩者都沒給(包括 skuId 為 0 又沒有料號)時,該筆失敗並帶 skuId or outerSysCode is required。
⚠️ 回應是一顆規格一列,不是一筆請求一列:用料號命中多顆規格時,每一顆各回一列,依規格序號由小到大排在一起,並原樣帶回該筆的 outerSysCode;料號找不到任何規格時只回一列 failed(skuId 為 null,error 為 SKU not found)。各列依請求順序排列。請用 skuId 或 outerSysCode 對回原始請求,不要假設回應筆數等於請求筆數。
逐筆狀態是小寫的 ok 或 failed,與規格主檔批次 API(POST /v1/skus/batch)的 created/updated/failed 不同,兩者不可混用;failed 時 error 帶失敗原因。
每一筆的 inventoryQuantity 與 isNegativeStockAllowed 都是選填,省略的欄位維持現值——沒帶 inventoryQuantity 不會被當成 0,在庫數不變、也不留異動紀錄,所以只想改是否允許負庫存時可以只帶 isNegativeStockAllowed。兩個欄位都沒帶時,該筆 failed,error 為 inventoryQuantity or isNegativeStockAllowed is required。用料號命中多顆規格時,每一顆都套用同樣的值。
若某一筆的 skuId 指向組合 SKU,該筆回報 failed 並帶 bundle SKU stock must be set through /v1/bundles/stock/batch;只屬於組合 SKU 的料號則比對不到任何規格(SKU not found)。組合品的庫存請改用 POST /v1/bundles/stock/batch 推送;若貴端是以「任一筆 failed 即視為整批失敗」處理回應,務必先確認本端點的推送清單裡沒有組合品。
Authentication
每個 /v1 請求都必須帶 X-Client-Id、X-Timestamp、X-Nonce 與 X-Signature 四個標頭。X-Signature 是以 client secret 對 canonical string 做 HMAC-SHA256 後的 Base64。
canonical string 的組成、可複製的簽章範例與 401 排查步驟,請參閱「驗證與簽章」。
Request
要設定庫存的規格序號,必須是既有的一般規格;不存在或屬於其他租戶時,這一筆會在逐筆結果中回報 failed,不影響其他筆。指向組合 SKU 時同樣回報 failed,error 為 bundle SKU stock must be set through /v1/bundles/stock/batch。與 outerSysCode 擇一提供;同時提供時以這個欄位為準,帶 0 視同沒帶。
料號。沒有帶正整數的 skuId 時才會用到:租戶內帶有這個料號的每一顆一般規格(去除前後空白、不分大小寫)都會設成同一個 inventoryQuantity。找不到任何規格時該筆失敗,error 為 SKU not found。
選填。更新後的絕對在庫數,不是增減量。這是這支端點最容易出錯的地方:送出的必須是「應該是多少」,不能是「要加或減多少」,把差量當成這個欄位送出會直接把在庫數蓋成錯誤的值。省略時在庫數維持現值(不會被當成 0);與 isNegativeStockAllowed 都省略時該筆 failed。
選填。是否允許負庫存:true 時超出現貨的部分仍可下單(記為預購),false 時可售數用完就不能再下單。省略時維持現值;以料號命中多顆規格時每一顆都套用。
Response
逐列的處理結果,依請求順序排列。用料號命中多顆規格的請求會有多列(依規格序號由小到大排在一起),所以列數可能多於送出的筆數。