建立組合品
建立單一組合品,一次寫入組合 SKU 與配方。未帶 id 時會先用料號找既有組合品,規則與批次寫入相同,所以這支端點也可能改為更新。成功時回傳 { "id": 9001, "ids": [9001] }(組合 SKU 序號,ids 列出這次寫入的每一顆),新增回 201,更新回 200。
productId 選填:省略(或帶 0)就建成沒有放在任何商品頁的組合品;帶非 0 值則必須是租戶內既有的商品(任何商品皆可),否則回傳 404 not_found。
components(配方)的驗證規則:
- 必填、至少 1 筆,省略或空陣列回傳 400 bundle_components_required
- 每個元件用
componentSkuId或componentSkuOuterSysCode擇一指名,兩者都有值時以componentSkuId為準,兩者都沒給回傳 400 component_identifier_required;用料號指名且對到超過 1 筆規格回傳 400 component_sku_code_ambiguous,絕不會替你挑一筆 - 元件必須存在、屬於同一租戶,且必須是一般規格(不允許巢狀組合品)——找不到或跨租戶一律回傳 400 component_not_found,不區分兩者以避免洩漏元件序號屬於別的租戶;是組合 SKU 回傳 400 component_cannot_be_a_bundle。沒有放在任何商品底下的一般規格也可以當元件
- 元件不可重複,回傳 400 component_duplicated;每組用量(
quantity)必須為正數,超出可表示範圍或四捨五入到小數 4 位後不大於 0 都視為不合法,回傳 400 invalid_component_quantity
price、sellPrice 若有帶值必須介於 0 到 9999999.99,超出回傳 400 invalid_price;quantityPrecision 若有帶值必須介於 0 到 4,超出回傳 400 invalid_quantity_precision。status 選填,規則與規格相同,見請求欄位說明。
組合 SKU 與配方的寫入在單一交易內完成,中途任何一步失敗都會整筆回滾,不會留下配方對不上的半成品組合品。
Authentication
每個 /v1 請求都必須帶 X-Client-Id、X-Timestamp、X-Nonce 與 X-Signature 四個標頭。X-Signature 是以 client secret 對 canonical string 做 HMAC-SHA256 後的 Base64。
canonical string 的組成、可複製的簽章範例與 401 排查步驟,請參閱「驗證與簽章」。
Request
組合 SKU 序號。帶 id 時一律視為更新該筆,不會再比對 outerSysCode;省略時改依料號判斷新增或更新。PUT /v1/bundles/{id} 會忽略這裡的值,一律以路徑上的 id 為準。
組合 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 與省略完全相同。
ERP 端的組合品料號,用來比對、去重:帶了非 0 的 productId 時只比對該商品底下的規格,否則在整個租戶內比對組合 SKU(去除前後空白、不分大小寫)。新增時省略視為空字串;更新時省略保留現有值。長度上限 50 字元,超過回傳 400 outer_sys_code_too_long。
組合品名稱。新增時省略視為空字串;更新時省略保留現有值。長度上限 100 字元,超過回傳 400 name_too_long。
商品單位。新增時省略視為空字串;更新時省略保留現有值。長度上限 50 字元,超過回傳 400 unit_too_long。
規格內容。新增時省略視為空字串;更新時省略保留現有值。長度上限 100 字元,超過回傳 400 spec_too_long。
條碼。新增時省略視為空字串;更新時省略保留現有值。長度上限 50 字元,超過回傳 400 barcode_too_long。
倉別。新增時省略視為空字串;更新時省略保留現有值。長度上限 50 字元,超過回傳 400 warehouse_too_long。
牌價。新增時省略視為 0;更新時省略保留現有值。必須介於 0 到 9999999.99,超出範圍回傳 400 invalid_price。
對外售價。範圍與省略規則同 price,超出範圍同樣回傳 400 invalid_price。
數量精度(0 為整數,1 至 4 為小數位數)。新增時省略視為 0;更新時省略保留現有值。必須介於 0 到 4,超出範圍回傳 400 invalid_quantity_precision。
組合品狀態:Active(上架)、Inactive(下架)或 GiftOnly(僅供贈品),不分大小寫。新增時省略為 Active;更新時省略保留現有值。其他值(包含空字串,以及商品才有的 InactiveVisible)回傳 400 invalid_status,批次則只有該筆失敗。
組合品自身是否允許負庫存:true 時自身不限量、只看組成規格;false 時組合品自身的可售數用完就不能再下單。新增時省略為 true;更新時省略保留現有值。在庫數請用 POST /v1/bundles/stock/batch 設定。
配方,至少 1 筆;建立時必填,省略或空陣列一律回傳 400 bundle_components_required(建立永遠會送出自己的配方陣列,省略在效果上等同空陣列)。更新時省略(null)即配方維持不變;帶值(包含空陣列)即配方整份替換,替換規則見更新端點的說明,替換整個失敗時完全不套用、原配方保留。
Response
新增或更新的規格序號;ids 有多個時是其中第一個。
這次新增或更新的所有規格序號,由小到大。只有料號命中多顆規格時才會超過一個。