Skip to navigation

批次寫入規格

View as Markdown

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

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

每一筆依下列順序決定要寫入哪一顆(或哪幾顆)規格,第一條符合的就套用:

  1. 帶 id:更新該筆規格,id 永遠優先於 outerSysCode。此時帶 "productId": 0 該筆失敗,見更新端點的說明
  2. 帶非 0 的 productId 與 outerSysCode:比對這個商品底下同料號的規格,找到就更新,找不到就在這個商品底下新增
  3. 只帶 outerSysCode(productId 省略或帶 0):在整個租戶內比對料號,同一料號的每一顆規格都會更新,所屬商品不變;找不到就新增一顆未加入商品的規格

逐筆結果的 id 是寫入的第一顆規格,ids 列出全部(由小到大)。例如料號 ERP-S-0004 同時放在兩個商品底下時,該筆會回報 "status": "updated", "id": 11, "ids": [11, 12]。失敗的那一筆 id 為 null、ids 為空陣列。

命中組合 SKU 時該筆回報 failed,錯誤字串與單筆端點相同,不會改為新增,其餘各筆不受影響。逐筆依送出順序處理,所以同一批裡出現兩次的新料號,第一筆會新增、第二筆會更新。更新一律是部分合併,只會覆蓋你送出的欄位;outerSysCode 的必填規則與單筆端點相同。

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

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

productIdlong or nullOptional

所屬商品序號,選填。規格可以不屬於任何商品,ERP 只管料號時不必知道商品。

新增時省略或帶 0,建成未加入商品的規格;帶非 0 值則必須是租戶內既有的商品,否則該筆失敗(404)。

更新時省略會保留目前所屬的商品;帶非 0 的新值會把規格移到那個商品底下,規則見更新端點的說明。依 id 指定的更新(批次項目帶 id,或 PUT /v1/skus/{id})帶 0 會回傳 400 productId 0 cannot detach a SKU; omit productId to keep its product。沒有 id 的項目帶 0 與省略完全相同,只用料號比對,也不會把命中的規格移出商品。

outerSysCodestring or nullOptional

ERP 端的料號,用來比對、去重:帶了非 0 的 productId 時只比對該商品底下的規格,否則比對整個租戶(去除前後空白、不分大小寫)。新增時為必填,省略回傳 400 outerSysCode is required to create a SKU;更新時省略保留現有值。長度上限 50 字元,超過回傳 400 outer_sys_code_too_long。

namestring or nullOptional

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

barcodestring or nullOptional

條碼。查詢時是精確比對,與 outerSysCode、name 的子字串比對不同,詳見 listSkus 端點說明。新增時省略視為空字串;更新時省略保留現有值。長度上限 50 字元,超過回傳 400 barcode_too_long。

warehousestring or nullOptional

倉別。新增時省略視為空字串;更新時省略保留現有值。長度上限 50 字元,超過回傳 400 warehouse_too_long。

unitstring or nullOptional

商品單位。新增時省略視為空字串;更新時省略保留現有值。長度上限 50 字元,超過回傳 400 unit_too_long。

specstring or nullOptional

規格內容(例如「12入」「500g」)。新增時省略視為空字串;更新時省略保留現有值。長度上限 100 字元,超過回傳 400 spec_too_long。

pricedouble or nullOptional

價格。新增時省略視為 0;更新時省略保留現有值。

sellPricedouble or nullOptional

賣價。新增時省略視為 0;更新時省略保留現有值。

quantityPrecisioninteger or nullOptional

數量精度(0 為整數,1 至 4 為小數位數)。新增時省略視為 0;更新時省略保留現有值。

statusstring or nullOptional

規格狀態:Active(上架)、Inactive(下架)或 GiftOnly(僅供贈品),不分大小寫。新增時省略為 Active;更新時省略保留現有值。其他值(包含空字串,以及商品才有的 InactiveVisible)回傳 400 invalid_status,批次則只有該筆失敗。只帶料號的更新會套用到同料號的每一顆規格,與其他欄位一樣。

Response

OK
itemslist of objects or nullOptional

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

Errors

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