更新規格
依 id 更新規格,路徑上的 id 永遠優先於 body 帶的 id,即使 body 另外指定了別的 id 也一律以路徑為準。更新是部分合併,只送有異動的欄位;省略的欄位維持原值,不會被清空。成功時回傳 { "id": 1, "ids": [1] }。
省略 productId 會保留規格目前所屬的商品。帶非 0 的新值會把規格移到那個商品底下,規則與後台相同:規格排到目標商品的最後一個,客戶價格設定跟著移過去;原商品底下若已經沒有任何規格,且狀態是 Active 或 InactiveVisible,會自動改為下架(Inactive)。⚠️ 帶 "productId": 0 會被拒絕,回傳 400 productId 0 cannot detach a SKU; omit productId to keep its product——依 id 指定的更新不能把規格移出商品,要移出請到後台操作;只想保留所屬商品就不要送這個欄位。
id 不存在或屬於其他租戶時回傳 404;組合 SKU 無法透過本端點更新,回傳 400 bundle SKU cannot be updated through this API,請改用 PUT /v1/bundles/{id}。
Authentication
每個 /v1 請求都必須帶 X-Client-Id、X-Timestamp、X-Nonce 與 X-Signature 四個標頭。X-Signature 是以 client secret 對 canonical string 做 HMAC-SHA256 後的 Base64。
canonical string 的組成、可複製的簽章範例與 401 排查步驟,請參閱「驗證與簽章」。
Path parameters
要更新的規格序號。這個值永遠優先於 body 裡的 id,兩者不一致時一律以路徑為準。不存在或屬於其他租戶時,回傳 404;error 是該資源的簡短說明,而非 not_found。
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
新增或更新的規格序號;ids 有多個時是其中第一個。
這次新增或更新的所有規格序號,由小到大。只有料號命中多顆規格時才會超過一個。