更新組合商品

View as Markdown
依商品序號更新組合商品,路徑上的 id 永遠優先於 body 帶的 id。更新是部分合併,只送有異動的欄位;省略的欄位維持原值,不會被清空。components 省略即配方維持不變;帶值(包含空陣列)即配方整份替換,並依建立時相同的規則重新驗證,任何一條規則沒過,這次更新整筆失敗、不會套用部分修改,原有配方保持不動。此外配方替換多一條建立時不適用的規則:元件不可以是這個組合商品自己的規格,回傳 400 component_self_reference。省略 productCategoryId 會保留目前的分類;若有帶值,會依建立時相同的規則重新驗證。id 不存在、屬於其他租戶,或指向一般商品時回傳 404 not_found。status 不是可寫欄位,本端點無法變更組合商品的上下架狀態。三張表(含配方整份替換)的寫入在單一交易內完成。

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

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

Request

This endpoint expects an object.
idlong or nullOptional

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

outerSysCodestring or nullOptional

ERP 端的組合商品代碼,用來與既有組合商品比對、去重。新增時省略視為空字串;更新時省略保留現有值。長度上限 50 字元,超過回傳 400 outer_sys_code_too_long。

namestring or nullOptional

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

productCategoryIdlong or nullOptional

商品分類序號,必須是可指派的(子)分類 id。新增時必填,省略回傳 400 product_category_id_required;帶了但分類不存在、不可指派或屬於其他租戶,回傳 400 invalid_product_category_id。更新時省略會保留目前的分類;若有帶值,會依相同規則重新驗證。

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。

componentslist of objects or nullOptional

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

Response

OK
idlongOptional

新增或更新成功後,該筆資料的 id。

Errors

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