Skip to navigation

建立規格

View as Markdown

建立單一規格,或依料號更新既有規格。新增時 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

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 an object.
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
idlongOptional

新增或更新的規格序號;ids 有多個時是其中第一個。

idslist of longs or nullOptional

這次新增或更新的所有規格序號,由小到大。只有料號命中多顆規格時才會超過一個。

Errors

401
Unauthorized Error
403
Forbidden Error
500
Internal Server Error