查詢單一組合商品

View as Markdown

依商品序號查詢單一組合商品,含完整配方與即時算出的可組數量。若該 id 不存在、屬於其他租戶,或指向的是一般商品,一律回傳 404 not_found,這幾種情況無法從回應內容區分。

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

Path parameters

idlongRequired

要查詢的組合商品序號,是商品序號、不是規格序號。不存在、屬於其他租戶,或指向一般商品時,一律回傳 404 not_found。

Response

OK
idlongOptional

組合商品序號,即這個組合商品的商品序號。

skuIdlongOptional

唯讀。這個組合商品配對的規格(Bundle 型別)序號,僅供核對,任何情況下都不接受輸入。

outerSysCodestring or nullOptional

ERP 端的組合商品代碼。

namestring or nullOptional

組合商品名稱。

statusstring or nullOptional

狀態,語意與「商品」家族相同,共三種:Active(上架)、Inactive(下架)、InactiveVisible(下架-顯示)。透過本 API 建立的組合商品一律為 Active,狀態值只能在後台維護。

productCategoryIdlongOptional

目前所屬的分類序號。

unitstring or nullOptional

商品單位。

specstring or nullOptional

規格內容。

barcodestring or nullOptional

條碼。

warehousestring or nullOptional

倉別。

pricedoubleOptional

牌價,與組合商品價格家族讀寫的是同一個 sku 欄位,也可以用 GET /v1/bundles/{id}/prices 單獨查詢。⚠️ 規格價格家族(PUT /v1/prices/batch)對組合品規格一律回傳 not_found,不要對組合商品打那支端點。

sellPricedoubleOptional

對外售價,與 price 同樣可由 GET /v1/bundles/{id}/prices 單獨查詢。

quantityPrecisionintegerOptional

數量精度(0 為整數,1 至 4 為小數位數)。

availableQtydoubleOptional

可組數量,即以目前庫存最多能組出幾份這個組合商品:把每個元件的可售量除以它的每組用量、取其中最小值後無條件捨去,並夾在 0(不會是負數)。⚠️ 這不是前台可購買數量:允許負庫存銷售的元件在這裡仍然會被計入上限,前台則會把這種元件視為供應無限、整顆排除在外,兩個公式因此可能合法地給出不同的數字。這個落差不會出現在完全透過本 API 建立的元件身上——透過本 API 建立的規格一律不允許負庫存銷售,即使這個欄位在資料庫層的預設值其實是「允許」;落差只可能出現在透過本 API 以外的管道建立、且沿用了那個資料庫預設值的規格上,而這種規格你端無法從本 API 的回應裡分辨出來。這個欄位也不受 updatedSince 增量拉取涵蓋,細節見清單端點的說明。

componentslist of objects or nullOptional

配方,每一筆為一個 BundleComponentResponse;一個組合商品至少有 1 個元件。

Errors

401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
500
Internal Server Error