建立規格
建立單一規格,或依料號更新既有規格。新增時 outerSysCode 為必填,省略回傳 400 outerSysCode is required to create a SKU。
productId 選填:省略(或帶 0)就建成未加入商品的規格,查詢時 productId 為 0;帶非 0 值則必須是租戶內既有的商品,否則回傳 404。
未帶 id 時會先用料號找既有規格,規則依序如下,第一條符合的就套用:
- 帶了非 0 的
productId:只比對這個商品底下同料號的規格,找到就更新那一顆,找不到就在這個商品底下新增。不同商品下的相同料號是不同的規格。命中的若是組合 SKU,回傳 400 bundle SKU cannot be updated through this API,且不會改為新增 - 只帶料號(
productId省略或帶 0):在整個租戶內比對料號(去除前後空白、不分大小寫,只比對一般規格),同一料號的每一顆規格都會被更新,所屬商品不變;找不到就新增一顆未加入商品的規格。料號只屬於組合 SKU 時回傳 400 outerSysCode belongs to a bundle SKU; use /v1/bundles,不會新增
所以每次都送 0 或不送 productId 的 ERP 可以放心重送同一份資料:第一次新增,之後都是更新。
status 選填,見請求欄位說明。庫存不能在這裡設定——新建規格的在庫數固定為 0,之後要用庫存的專屬端點寫入(見「庫存」)。
成功時回傳 { "id": 5001, "ids": [5001] }:ids 列出這次新增或更新的每一顆規格,id 是其中第一顆。新增回 201,更新回 200。
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
新增或更新的規格序號;ids 有多個時是其中第一個。
這次新增或更新的所有規格序號,由小到大。只有料號命中多顆規格時才會超過一個。