Skip to navigation

更新組合品

View as Markdown

依組合 SKU 序號更新組合品,路徑上的 id 永遠優先於 body 帶的 id。更新是部分合併,只送有異動的欄位;省略的欄位維持原值,不會被清空。成功時回傳 { "id": 9001, "ids": [9001] }。

components 省略即配方維持不變;帶值(包含空陣列)即配方整份替換,並依建立時相同的規則重新驗證,任何一條規則沒過,這次更新整筆失敗、不會套用部分修改,原有配方保持不動。此外配方替換多一條建立時不適用的規則:元件不可以是這個組合品自己,回傳 400 component_self_reference。

省略 productId 會保留目前所在的商品頁;帶非 0 的新值會把組合品移到那個商品頁,規則與規格相同:排到目標商品的最後一個,客戶價格設定跟著移過去,原商品底下若已經沒有任何規格且狀態是 Active 或 InactiveVisible,會自動改為下架(Inactive)。⚠️ 帶 "productId": 0 會被拒絕,回傳 400 productId 0 cannot detach a SKU; omit productId to keep its product——依 id 指定的更新不能把組合品移出商品頁,要移出請到後台操作。

id 不存在、屬於其他租戶,或指向一般規格時回傳 404 not_found。組合 SKU(含配方整份替換)的寫入在單一交易內完成。

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 排查步驟,請參閱「驗證與簽章」。

Path parameters

idlongRequired

要更新的組合 SKU 序號。這個值永遠優先於 body 裡的 id。不存在、屬於其他租戶,或指向一般規格時,回傳 404。

Request

This endpoint expects an object.
idlong or nullOptional

組合 SKU 序號。帶 id 時一律視為更新該筆,不會再比對 outerSysCode;省略時改依料號判斷新增或更新。PUT /v1/bundles/{id} 會忽略這裡的值,一律以路徑上的 id 為準。

productIdlong or nullOptional

組合 SKU 所在的商品頁序號,選填。組合品可以不放在任何商品頁。

新增時省略或帶 0,建成沒有放在商品頁的組合品;帶非 0 值則必須是租戶內既有的商品(任何商品皆可),否則該筆失敗(404 not_found)。

更新時省略會保留目前所在的商品頁;帶非 0 的新值會把組合品移到那個商品頁,規則見更新端點的說明。依 id 指定的更新(批次項目帶 id,或 PUT /v1/bundles/{id})帶 0 會回傳 400 productId 0 cannot detach a SKU; omit productId to keep its product。沒有 id 的項目帶 0 與省略完全相同。

outerSysCodestring or nullOptional

ERP 端的組合品料號,用來比對、去重:帶了非 0 的 productId 時只比對該商品底下的規格,否則在整個租戶內比對組合 SKU(去除前後空白、不分大小寫)。新增時省略視為空字串;更新時省略保留現有值。長度上限 50 字元,超過回傳 400 outer_sys_code_too_long。

namestring or nullOptional

組合品名稱。新增時省略視為空字串;更新時省略保留現有值。長度上限 100 字元,超過回傳 400 name_too_long。

unitstring or nullOptional

商品單位。新增時省略視為空字串;更新時省略保留現有值。長度上限 50 字元,超過回傳 400 unit_too_long。

specstring or nullOptional

規格內容。新增時省略視為空字串;更新時省略保留現有值。長度上限 100 字元,超過回傳 400 spec_too_long。

barcodestring or nullOptional

條碼。新增時省略視為空字串;更新時省略保留現有值。長度上限 50 字元,超過回傳 400 barcode_too_long。

warehousestring or nullOptional

倉別。新增時省略視為空字串;更新時省略保留現有值。長度上限 50 字元,超過回傳 400 warehouse_too_long。

pricedouble or nullOptional

牌價。新增時省略視為 0;更新時省略保留現有值。必須介於 0 到 9999999.99,超出範圍回傳 400 invalid_price。

sellPricedouble or nullOptional

對外售價。範圍與省略規則同 price,超出範圍同樣回傳 400 invalid_price。

quantityPrecisioninteger or nullOptional

數量精度(0 為整數,1 至 4 為小數位數)。新增時省略視為 0;更新時省略保留現有值。必須介於 0 到 4,超出範圍回傳 400 invalid_quantity_precision。

statusstring or nullOptional

組合品狀態:Active(上架)、Inactive(下架)或 GiftOnly(僅供贈品),不分大小寫。新增時省略為 Active;更新時省略保留現有值。其他值(包含空字串,以及商品才有的 InactiveVisible)回傳 400 invalid_status,批次則只有該筆失敗。

isNegativeStockAllowedboolean or nullOptional

組合品自身是否允許負庫存:true 時自身不限量、只看組成規格;false 時組合品自身的可售數用完就不能再下單。新增時省略為 true;更新時省略保留現有值。在庫數請用 POST /v1/bundles/stock/batch 設定。

componentslist of objects or nullOptional

配方,至少 1 筆;建立時必填,省略或空陣列一律回傳 400 bundle_components_required(建立永遠會送出自己的配方陣列,省略在效果上等同空陣列)。更新時省略(null)即配方維持不變;帶值(包含空陣列)即配方整份替換,替換規則見更新端點的說明,替換整個失敗時完全不套用、原配方保留。

Response

OK
idlongOptional

新增或更新的規格序號;ids 有多個時是其中第一個。

idslist of longs or nullOptional

這次新增或更新的所有規格序號,由小到大。只有料號命中多顆規格時才會超過一個。

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
500
Internal Server Error