批次更新(SKU)庫存

View as Markdown
批次覆蓋多筆(SKU)的在庫數,一次寫入多筆,逐筆結果互不影響。 ⚠️ **`quantity` 是絕對的在庫數,不是增減量**——每一筆送出的都是「更新後庫存應該是多少」,不是要加減的差量;把差量當成這個欄位送出,會直接把在庫數蓋成錯誤的值,這是使用這支端點最容易出錯、也最需要注意的地方。 送出空陣列或沒有 body 會在受理前被拒絕,回傳 400 empty_batch;已受理的請求一律回傳 HTTP 200,逐筆的處理結果放在回應 body 的 `items` 裡,單筆失敗不會讓其他筆一起失敗。 逐筆狀態是小寫的 ok 或 failed,與規格主檔批次 API(POST /v1/skus/batch)的 created/updated/failed 不同,兩者不可混用;failed 時 `error` 帶失敗原因。 若某一筆的 `skuId` 指向組合商品的規格,該筆回報 failed 並帶 bundle SKU stock cannot be set through this API——組合商品的可組數量由其組成規格推導而來,不是能直接覆寫的數字。請把這類 `skuId` 從推送內容中排除;若貴端是以「任一筆 failed 即視為整批失敗」處理回應,務必先確認推送清單裡沒有組合商品的規格序號。

Authentication

X-Signaturestring
每個 /v1 請求都必須帶 `X-Client-Id`、`X-Timestamp`、`X-Nonce` 與 `X-Signature` 四個標頭。`X-Signature` 是以 client secret 對 canonical string 做 HMAC-SHA256 後的 Base64。 canonical string 的組成、可複製的簽章範例與 401 排查步驟,請參閱[「驗證與簽章」](/authentication)。

Request

This endpoint expects a list of objects.
skuIdlongOptional

要設定庫存的規格序號,必須是既有的一般規格;不存在或屬於其他租戶時,這一筆會在逐筆結果中回報 failed,不影響其他筆。指向組合商品的規格時同樣回報 failed,error 為 bundle SKU stock cannot be set through this API。

quantitydoubleOptional

更新後的絕對在庫數,不是增減量。這是這支端點最容易出錯的地方:送出的必須是「應該是多少」,不能是「要加或減多少」,把差量當成這個欄位送出會直接把在庫數蓋成錯誤的值。

Response

OK
itemslist of objects or nullOptional

逐筆的處理結果,順序與送出的陣列相同,一筆對一筆。

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
500
Internal Server Error