Skip to navigation

批次寫入組合品

View as Markdown

一次寫入多筆組合品,逐筆各自新增、更新或去重,互不影響。

送出空陣列或沒有 body 會在受理前被拒絕,回傳 400 empty_batch;已受理的請求一律回傳 HTTP 200,逐筆的處理結果放在回應 body 的 items 裡,單筆失敗不會讓其他筆一起失敗。

每一筆依下列順序決定要寫入哪一個(或哪幾個)組合品,規則與規格批次相同,只是一般規格與組合 SKU 對調,第一條符合的就套用:

  1. 帶 id:更新該組合品,id 永遠優先於 outerSysCode。此時帶 "productId": 0 該筆失敗,見更新端點的說明
  2. 帶非 0 的 productId 與 outerSysCode:比對這個商品底下同料號的規格。是組合 SKU 就更新;是一般規格則該筆失敗並帶 product_type_conflict。找不到就在這個商品底下新增組合品
  3. 只帶 outerSysCode(productId 省略或帶 0):在整個租戶內比對料號(去除前後空白、不分大小寫,只比對組合 SKU),同一料號的每一個組合品都會更新,所屬商品頁不變;找不到就新增一個沒有放在商品頁的組合品。料號只屬於一般規格時該筆失敗並帶 product_type_conflict,不會新增(一般規格請用 /v1/skus)

逐筆結果的形狀與其他批次寫入相同:index、status(created、updated、failed)、id、ids、errors。id 是寫入的第一個組合 SKU 序號,ids 列出全部(由小到大);失敗的那一筆 id 為 null、ids 為空陣列。逐筆依送出順序處理,所以同一批裡出現兩次的新料號,第一筆會新增、第二筆會更新。

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

Request

This endpoint expects a list of objects.
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
itemslist of objects or nullOptional

逐筆的處理結果,順序與送出的陣列相同,一筆對一筆。

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
500
Internal Server Error