批次寫入規格
一次寫入多筆規格,逐筆各自新增、更新或去重,互不影響。
送出空陣列或沒有 body 會在受理前被拒絕,回傳 400 empty_batch;已受理的請求一律回傳 HTTP 200,逐筆的處理結果放在回應 body 的 items 裡,單筆失敗不會讓其他筆一起失敗。
每一筆依下列順序決定要寫入哪一顆(或哪幾顆)規格,第一條符合的就套用:
- 帶
id:更新該筆規格,id永遠優先於outerSysCode。此時帶"productId": 0該筆失敗,見更新端點的說明 - 帶非 0 的
productId與outerSysCode:比對這個商品底下同料號的規格,找到就更新,找不到就在這個商品底下新增 - 只帶
outerSysCode(productId省略或帶 0):在整個租戶內比對料號,同一料號的每一顆規格都會更新,所屬商品不變;找不到就新增一顆未加入商品的規格
逐筆結果的 id 是寫入的第一顆規格,ids 列出全部(由小到大)。例如料號 ERP-S-0004 同時放在兩個商品底下時,該筆會回報 "status": "updated", "id": 11, "ids": [11, 12]。失敗的那一筆 id 為 null、ids 為空陣列。
命中組合 SKU 時該筆回報 failed,錯誤字串與單筆端點相同,不會改為新增,其餘各筆不受影響。逐筆依送出順序處理,所以同一批裡出現兩次的新料號,第一筆會新增、第二筆會更新。更新一律是部分合併,只會覆蓋你送出的欄位;outerSysCode 的必填規則與單筆端點相同。
Authentication
每個 /v1 請求都必須帶 X-Client-Id、X-Timestamp、X-Nonce 與 X-Signature 四個標頭。X-Signature 是以 client secret 對 canonical string 做 HMAC-SHA256 後的 Base64。
canonical string 的組成、可複製的簽章範例與 401 排查步驟,請參閱「驗證與簽章」。
Request
規格序號。帶 id 時一律視為更新該筆規格,不會再比對 outerSysCode;省略時改依料號(與 productId)判斷新增或更新。PUT /v1/skus/{id} 會忽略這裡的值,一律以路徑上的 id 為準。
所屬商品序號,選填。規格可以不屬於任何商品,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 與省略完全相同,只用料號比對,也不會把命中的規格移出商品。
ERP 端的料號,用來比對、去重:帶了非 0 的 productId 時只比對該商品底下的規格,否則比對整個租戶(去除前後空白、不分大小寫)。新增時為必填,省略回傳 400 outerSysCode is required to create a SKU;更新時省略保留現有值。長度上限 50 字元,超過回傳 400 outer_sys_code_too_long。
名稱。新增時省略視為空字串;更新時省略保留現有值。長度上限 100 字元,超過回傳 400 name_too_long。
條碼。查詢時是精確比對,與 outerSysCode、name 的子字串比對不同,詳見 listSkus 端點說明。新增時省略視為空字串;更新時省略保留現有值。長度上限 50 字元,超過回傳 400 barcode_too_long。
倉別。新增時省略視為空字串;更新時省略保留現有值。長度上限 50 字元,超過回傳 400 warehouse_too_long。
商品單位。新增時省略視為空字串;更新時省略保留現有值。長度上限 50 字元,超過回傳 400 unit_too_long。
規格內容(例如「12入」「500g」)。新增時省略視為空字串;更新時省略保留現有值。長度上限 100 字元,超過回傳 400 spec_too_long。
價格。新增時省略視為 0;更新時省略保留現有值。
賣價。新增時省略視為 0;更新時省略保留現有值。
數量精度(0 為整數,1 至 4 為小數位數)。新增時省略視為 0;更新時省略保留現有值。
規格狀態:Active(上架)、Inactive(下架)或 GiftOnly(僅供贈品),不分大小寫。新增時省略為 Active;更新時省略保留現有值。其他值(包含空字串,以及商品才有的 InactiveVisible)回傳 400 invalid_status,批次則只有該筆失敗。只帶料號的更新會套用到同料號的每一顆規格,與其他欄位一樣。
Response
逐筆的處理結果,順序與送出的陣列相同,一筆對一筆。