批次寫入規格

View as Markdown
一次寫入多筆規格,逐筆各自新增、更新或去重,互不影響。 送出空陣列或沒有 body 會在受理前被拒絕,回傳 400 empty_batch;已受理的請求一律回傳 HTTP 200,逐筆的處理結果放在回應 body 的 `items` 裡,單筆失敗不會讓其他筆一起失敗。 每一筆的新增/更新/去重規則與單筆端點相同:帶 `id` 就更新該筆;不帶 `id` 但 `outerSysCode` 命中同一商品底下的既有規格就改為更新(去重比對限定在同一個 `productId` 之內,不同商品下的相同代碼不會互相匹配);兩者都沒有則新增。 若去重命中的是組合商品的規格,該筆回報 failed 並帶 bundle SKU cannot be updated through this API,絕不會改為新增,其餘各筆不受影響。若 `productId` 指向的是一筆組合商品,該筆同樣回報 failed 並帶 bundle product cannot receive SKUs through this API,新增與更新皆適用,其餘各筆不受影響。 更新一律是部分合併,只會覆蓋你送出的欄位;`outerSysCode`、`productId` 的必填規則與單筆端點相同。

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 排查步驟,請參閱[「驗證與簽章」](/authentication)。

Request

This endpoint expects a list of objects.
idlong or nullOptional

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

productIdlong or nullOptional

對應的商品序號,必須指向既有商品,且不可以是組合商品——一個組合品商品固定只有一個 SKU,由組合商品專屬端點建立與維護;帶入組合商品的商品序號一律回傳 400 bundle product cannot receive SKUs through this API,新增與更新(改指到另一個商品)皆適用。

新增時為必填,省略或帶入非正整數回傳 400 productId is required to create a SKU;更新時省略會保留規格目前所屬的商品,帶新值則會把規格改到另一個商品底下。outerSysCode 的去重比對也是以這個欄位限定範圍,同一組 outerSysCode 換一個 productId 視為完全不同的比對對象。

outerSysCodestring or nullOptional

ERP 端的規格代碼,用來在同一個 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;更新時省略保留現有值。

Response

OK
itemslist of objects or nullOptional

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

Errors

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