批次寫入組合品
一次寫入多筆組合品,逐筆各自新增、更新或去重,互不影響。
送出空陣列或沒有 body 會在受理前被拒絕,回傳 400 empty_batch;已受理的請求一律回傳 HTTP 200,逐筆的處理結果放在回應 body 的 items 裡,單筆失敗不會讓其他筆一起失敗。
每一筆依下列順序決定要寫入哪一個(或哪幾個)組合品,規則與規格批次相同,只是一般規格與組合 SKU 對調,第一條符合的就套用:
- 帶
id:更新該組合品,id永遠優先於outerSysCode。此時帶"productId": 0該筆失敗,見更新端點的說明 - 帶非 0 的
productId與outerSysCode:比對這個商品底下同料號的規格。是組合 SKU 就更新;是一般規格則該筆失敗並帶 product_type_conflict。找不到就在這個商品底下新增組合品 - 只帶
outerSysCode(productId省略或帶 0):在整個租戶內比對料號(去除前後空白、不分大小寫,只比對組合 SKU),同一料號的每一個組合品都會更新,所屬商品頁不變;找不到就新增一個沒有放在商品頁的組合品。料號只屬於一般規格時該筆失敗並帶 product_type_conflict,不會新增(一般規格請用/v1/skus)
逐筆結果的形狀與其他批次寫入相同:index、status(created、updated、failed)、id、ids、errors。id 是寫入的第一個組合 SKU 序號,ids 列出全部(由小到大);失敗的那一筆 id 為 null、ids 為空陣列。逐筆依送出順序處理,所以同一批裡出現兩次的新料號,第一筆會新增、第二筆會更新。
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
逐筆的處理結果,順序與送出的陣列相同,一筆對一筆。