> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.orderupb2b.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.orderupb2b.com/_mcp/server. # 更新組合商品 PUT https://api.example.com/v1/bundles/{id} Content-Type: application/json 依商品序號更新組合商品，路徑上的 id 永遠優先於 body 帶的 id。更新是部分合併，只送有異動的欄位；省略的欄位維持原值，不會被清空。components 省略即配方維持不變；帶值（包含空陣列）即配方整份替換，並依建立時相同的規則重新驗證，任何一條規則沒過，這次更新整筆失敗、不會套用部分修改，原有配方保持不動。此外配方替換多一條建立時不適用的規則：元件不可以是這個組合商品自己的規格，回傳 400 component_self_reference。省略 productCategoryId 會保留目前的分類；若有帶值，會依建立時相同的規則重新驗證。id 不存在、屬於其他租戶，或指向一般商品時回傳 404 not_found。status 不是可寫欄位，本端點無法變更組合商品的上下架狀態。三張表（含配方整份替換）的寫入在單一交易內完成。 Reference: https://docs.orderupb2b.com/api-reference/bundles/update-bundle ## Authentication - `X-Signature` header (required) — 每個 /v1 請求都必須帶 X-Client-Id、X-Timestamp、X-Nonce 與 X-Signature 四個標頭。X-Signature 是以 client secret 對 canonical string 做 HMAC-SHA256 後的 Base64。canonical string 的組成、可複製的簽章範例與 401 排查步驟，請參閱「驗證與簽章」。 ## Request ### Path parameters - `id` (long, required) — 要更新的組合商品序號，是商品序號、不是規格序號。這個值永遠優先於 body 裡的 id。不存在、屬於其他租戶，或指向一般商品時，回傳 404。 ### Body (application/json) This endpoint expects an object. - `id` (long, optional, nullable) — 組合商品序號（商品序號）。帶 id 時一律視為更新該筆，不會再比對 outerSysCode；省略時改依 outerSysCode 判斷新增或更新。PUT /v1/bundles/\{id} 會忽略這裡的值，一律以路徑上的 id 為準。 - `outerSysCode` (string, optional, nullable) — ERP 端的組合商品代碼，用來與既有組合商品比對、去重。新增時省略視為空字串；更新時省略保留現有值。長度上限 50 字元，超過回傳 400 outer_sys_code_too_long。 - `name` (string, optional, nullable) — 組合商品名稱。新增時省略視為空字串；更新時省略保留現有值。長度上限 100 字元，超過回傳 400 name_too_long。 - `productCategoryId` (long, optional, nullable) — 商品分類序號，必須是可指派的（子）分類 id。新增時必填，省略回傳 400 product_category_id_required；帶了但分類不存在、不可指派或屬於其他租戶，回傳 400 invalid_product_category_id。更新時省略會保留目前的分類；若有帶值，會依相同規則重新驗證。 - `unit` (string, optional, nullable) — 商品單位。新增時省略視為空字串；更新時省略保留現有值。長度上限 50 字元，超過回傳 400 unit_too_long。 - `spec` (string, optional, nullable) — 規格內容。新增時省略視為空字串；更新時省略保留現有值。長度上限 100 字元，超過回傳 400 spec_too_long。 - `barcode` (string, optional, nullable) — 條碼。新增時省略視為空字串；更新時省略保留現有值。長度上限 50 字元，超過回傳 400 barcode_too_long。 - `warehouse` (string, optional, nullable) — 倉別。新增時省略視為空字串；更新時省略保留現有值。長度上限 50 字元，超過回傳 400 warehouse_too_long。 - `price` (double, optional, nullable) — 牌價。新增時省略視為 0；更新時省略保留現有值。必須介於 0 到 9999999.99，超出範圍回傳 400 invalid_price。 - `sellPrice` (double, optional, nullable) — 對外售價。範圍與省略規則同 price，超出範圍同樣回傳 400 invalid_price。 - `quantityPrecision` (integer, optional, nullable) — 數量精度（0 為整數，1 至 4 為小數位數）。新增時省略視為 0；更新時省略保留現有值。必須介於 0 到 4，超出範圍回傳 400 invalid_quantity_precision。 - `components` (list of object, optional, nullable) — 配方，至少 1 筆；建立時必填，省略或空陣列一律回傳 400 bundle_components_required（建立永遠會送出自己的配方陣列，省略在效果上等同空陣列）。更新時省略（null）即配方維持不變；帶值（包含空陣列）即配方整份替換，替換規則見更新端點的說明，替換整個失敗時完全不套用、原配方保留。 - `componentSkuId` (long, optional, nullable) — 元件規格序號。與 componentSkuOuterSysCode 擇一必填，兩者都有值時以這個欄位為準，因為它精確、不需要反查。 - `componentSkuOuterSysCode` (string, optional, nullable) — 元件規格的 ERP 代碼，componentSkuId 省略時才會用到，精確比對，不分大小寫、去除前後空白。對到超過 1 筆規格時整筆失敗並帶 component_sku_code_ambiguous，絕不會替你挑一筆；兩個識別欄位都沒給時失敗並帶 component_identifier_required。 - `quantity` (double, optional) — 每組用量，必須為正數。超出可表示的範圍，或四捨五入到小數 4 位後不大於 0，都視為不合法，回傳 400 invalid_component_quantity。 - `sort` (integer, optional) — 排序，數字越小越前面。 ## Response ### 200 OK - `id` (long, optional) — 新增或更新成功後，該筆資料的 id。 ## Errors ### 400 Bad Request Error Bad Request - `error` (string, optional, nullable) — 錯誤代碼，固定為 snake_case 字串，依代碼判斷失敗原因。 ### 401 Unauthorized Error Unauthorized - `error` (string, optional, nullable) — 錯誤代碼，固定為 snake_case 字串，依代碼判斷失敗原因。 ### 403 Forbidden Error Forbidden - `error` (string, optional, nullable) — 錯誤代碼，固定為 snake_case 字串，依代碼判斷失敗原因。 ### 404 Not Found Error Not Found - `error` (string, optional, nullable) — 錯誤代碼，固定為 snake_case 字串，依代碼判斷失敗原因。 ### 500 Internal Server Error Internal Server Error - `code` (string, optional, nullable) — 錯誤代碼字串。 - `message` (string, optional, nullable) — 對應的錯誤說明文字。 ## Examples **Request** ```json {} ``` **Response** ```json { "id": 1 } ``` **SDK Code** ```python import requests url = "https://api.example.com/v1/bundles/1" payload = {} headers = { "X-Signature": "", "Content-Type": "application/json" } response = requests.put(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.example.com/v1/bundles/1'; const options = { method: 'PUT', headers: {'X-Signature': '', 'Content-Type': 'application/json'}, body: '{}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.example.com/v1/bundles/1" payload := strings.NewReader("{}") req, _ := http.NewRequest("PUT", url, payload) req.Header.Add("X-Signature", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.example.com/v1/bundles/1") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Put.new(url) request["X-Signature"] = '' request["Content-Type"] = 'application/json' request.body = "{}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.put("https://api.example.com/v1/bundles/1") .header("X-Signature", "") .header("Content-Type", "application/json") .body("{}") .asString(); ``` ```php request('PUT', 'https://api.example.com/v1/bundles/1', [ 'body' => '{}', 'headers' => [ 'Content-Type' => 'application/json', 'X-Signature' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.example.com/v1/bundles/1"); var request = new RestRequest(Method.PUT); request.AddHeader("X-Signature", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "X-Signature": "", "Content-Type": "application/json" ] let parameters = [] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.example.com/v1/bundles/1")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PUT" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```