> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.orderupb2b.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.orderupb2b.com/_mcp/server. # 查詢組合商品清單 GET https://api.example.com/v1/bundles 分頁查詢組合商品清單，形狀與「商品」家族的清單端點一致：可用 outerSysCode、name 篩選，兩者皆為大小寫不敏感的子字串比對；用 status 篩狀態，接受 Active、Inactive 或 InactiveVisible 三種值中的任一種（完全比對，大小寫必須完全相符）；用 updatedSince 篩「異動時間等於或晚於此刻」的資料。⚠️ updatedSince 的判斷來源有三個：商品本身的異動時間、規格本身的異動時間、配方列（元件、用量、排序）的異動時間，三者用 OR 合併——改價只會動到規格的異動時間、改配方只會動到配方列的異動時間，兩者都不會動到商品的異動時間，只比對商品這一個來源會讓改價或改配方的組合商品在增量拉取時安靜地缺席。但這三個來源都不涵蓋 availableQty 本身：元件庫存變動、或元件被未出貨訂單保留，都不會觸碰上述任何一個時間戳，所以用 updatedSince 判斷要不要重新拉的整合方，可能會在元件庫存變動後持續讀到一個已經過期的 availableQty，直到這個組合商品本身因為改名、改配方等其他原因被觸碰為止——這是可以接受的（庫存的即時性本來就是你端自己該掌握的事，這支 API 給的是查詢當下那一刻的快照），但務必了解：沒有出現在 updatedSince 增量結果裡不等於這個組合商品的 availableQty 沒有變。另可用 componentSkuId 反查「改動某個元件規格會影響哪些組合商品」。page 從 1 起算，pageSize 為 1–100（預設 100），超出範圍一律回 400，不會自動夾限。 Reference: https://docs.orderupb2b.com/api-reference/bundles/list-bundles ## Authentication - `X-Signature` header (required) — 每個 /v1 請求都必須帶 X-Client-Id、X-Timestamp、X-Nonce 與 X-Signature 四個標頭。X-Signature 是以 client secret 對 canonical string 做 HMAC-SHA256 後的 Base64。canonical string 的組成、可複製的簽章範例與 401 排查步驟，請參閱「驗證與簽章」。 ## Request ### Query parameters - `outerSysCode` (string, optional) — 依 ERP 端的組合商品代碼篩選。大小寫不敏感的子字串比對，查 A100 也會一併比對到 A1000；要精確命中某一筆，請在你端再比對一次完整字串。 - `name` (string, optional) — 依組合商品名稱篩選。大小寫不敏感的子字串比對，規則與 outerSysCode 相同。 - `status` (string, optional) — 依組合商品狀態篩選，接受 Active、Inactive 或 InactiveVisible。這是完全比對，而且大小寫必須與這裡列出的完全相符——帶 active 不會命中任何資料，會回傳 HTTP 200 但 data 是空陣列，不是錯誤。三種狀態的語意見「商品」家族 ProductResponse.status 的說明；透過本端點建立的組合商品一律為 Active，其餘狀態只能由後台維護產生。 - `componentSkuId` (long, optional) — 反查：只回傳**目前配方裡仍然含有**這個元件規格的組合商品，用於「這顆規格庫存異動了，會影響哪些組合商品」這類場景。⚠️ 命中範圍不含歷史關聯——元件曾經在配方裡出現過，後來被替換配方（`PUT /v1/bundles/{id}` 帶新的 `components`）移除，就不會再被這個參數命中；查不到不代表沒有影響過，只代表「現在」沒有關聯，這支反查沒有辦法回答「這顆規格曾經被哪些組合商品用過」。 - `UpdatedSince` (string, optional) — 只回傳異動時間等於或晚於此刻的組合商品，用於增量同步；判斷來源與涵蓋範圍見本端點說明。必須是 ISO-8601 格式，並帶明確的時區位移或 Z（例如 2026-07-01T00:00:00Z）；沒有時區資訊會回傳 400 invalid_updated_since。放進網址時記得把 + 編碼成 %2B。 - `Page` (integer, optional) — 頁碼，從 1 起算，省略時預設 1。小於 1 回傳 400 invalid_page；頁碼大到讓內部位移量溢位時同樣回傳 400 invalid_page。 - `PageSize` (integer, optional) — 每頁筆數，範圍 1 至 100，省略時預設 100。超出範圍一律回傳 400 invalid_page_size，不會自動夾限成合法值，避免分批掃描時誤判為已經抓完全部資料。 ## Response ### 200 OK - `data` (list of object, optional, nullable) — 本頁的組合商品資料，每一筆為一個 BundleResponse。 - `id` (long, optional) — 組合商品序號，即這個組合商品的商品序號。 - `skuId` (long, optional) — 唯讀。這個組合商品配對的規格（Bundle 型別）序號，僅供核對，任何情況下都不接受輸入。 - `outerSysCode` (string, optional, nullable) — ERP 端的組合商品代碼。 - `name` (string, optional, nullable) — 組合商品名稱。 - `status` (string, optional, nullable) — 狀態，語意與「商品」家族相同，共三種：Active（上架）、Inactive（下架）、InactiveVisible（下架-顯示）。透過本 API 建立的組合商品一律為 Active，狀態值只能在後台維護。 - `productCategoryId` (long, optional) — 目前所屬的分類序號。 - `unit` (string, optional, nullable) — 商品單位。 - `spec` (string, optional, nullable) — 規格內容。 - `barcode` (string, optional, nullable) — 條碼。 - `warehouse` (string, optional, nullable) — 倉別。 - `price` (double, optional) — 牌價，與組合商品價格家族讀寫的是同一個 sku 欄位，也可以用 GET /v1/bundles/\{id}/prices 單獨查詢。⚠️ 規格價格家族（PUT /v1/prices/batch）對組合品規格一律回傳 not\_found，不要對組合商品打那支端點。 - `sellPrice` (double, optional) — 對外售價，與 price 同樣可由 GET /v1/bundles/\{id}/prices 單獨查詢。 - `quantityPrecision` (integer, optional) — 數量精度（0 為整數，1 至 4 為小數位數）。 - `availableQty` (double, optional) — 可組數量，即以目前庫存最多能組出幾份這個組合商品：把每個元件的可售量除以它的每組用量、取其中最小值後無條件捨去，並夾在 0（不會是負數）。⚠️ 這不是前台可購買數量：允許負庫存銷售的元件在這裡仍然會被計入上限，前台則會把這種元件視為供應無限、整顆排除在外，兩個公式因此可能合法地給出不同的數字。這個落差不會出現在完全透過本 API 建立的元件身上——透過本 API 建立的規格一律不允許負庫存銷售，即使這個欄位在資料庫層的預設值其實是「允許」；落差只可能出現在透過本 API 以外的管道建立、且沿用了那個資料庫預設值的規格上，而這種規格你端無法從本 API 的回應裡分辨出來。這個欄位也不受 updatedSince 增量拉取涵蓋，細節見清單端點的說明。 - `components` (list of object, optional, nullable) — 配方，每一筆為一個 BundleComponentResponse；一個組合商品至少有 1 個元件。 - `componentSkuId` (long, optional) — 元件規格序號。 - `componentSkuOuterSysCode` (string, optional, nullable) — 元件規格的 ERP 代碼。 - `componentSkuName` (string, optional, nullable) — 元件規格名稱。 - `quantity` (double, optional) — 每組用量。 - `sort` (integer, optional) — 排序，數字越小越前面。 - `totalCount` (integer, optional) — 符合篩選條件的組合商品總數，涵蓋所有頁，不受目前頁碼影響。 - `currentPage` (integer, optional) — 目前頁碼，即請求帶入的 page，從 1 起算。 - `pageSize` (integer, optional) — 目前頁面的筆數上限，即請求帶入的 pageSize。 - `totalPages` (integer, optional) — 總頁數，等於 totalCount 除以 pageSize 後無條件進位；沒有符合的資料時為 0。 ## Errors ### 400 Bad Request Error Bad Request - `error` (string, optional, nullable) — 錯誤代碼，固定為 snake_case 字串，依代碼判斷失敗原因。 ### 401 Unauthorized Error Unauthorized - `error` (string, optional, nullable) — 錯誤代碼，固定為 snake_case 字串，依代碼判斷失敗原因。 ### 403 Forbidden Error Forbidden - `error` (string, optional, nullable) — 錯誤代碼，固定為 snake_case 字串，依代碼判斷失敗原因。 ### 500 Internal Server Error Internal Server Error - `code` (string, optional, nullable) — 錯誤代碼字串。 - `message` (string, optional, nullable) — 對應的錯誤說明文字。 ## Examples **Response** ```json { "data": [ { "id": 1, "skuId": 1, "outerSysCode": "string", "name": "string", "status": "string", "productCategoryId": 1, "unit": "string", "spec": "string", "barcode": "string", "warehouse": "string", "price": 1.1, "sellPrice": 1.1, "quantityPrecision": 1, "availableQty": 1.1, "components": [ { "componentSkuId": 1, "componentSkuOuterSysCode": "string", "componentSkuName": "string", "quantity": 1.1, "sort": 1 } ] } ], "totalCount": 1, "currentPage": 1, "pageSize": 1, "totalPages": 1 } ``` **SDK Code** ```python import requests url = "https://api.example.com/v1/bundles" headers = {"X-Signature": ""} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.example.com/v1/bundles'; const options = {method: 'GET', headers: {'X-Signature': ''}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.example.com/v1/bundles" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("X-Signature", "") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.example.com/v1/bundles") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["X-Signature"] = '' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.example.com/v1/bundles") .header("X-Signature", "") .asString(); ``` ```php request('GET', 'https://api.example.com/v1/bundles', [ 'headers' => [ 'X-Signature' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.example.com/v1/bundles"); var request = new RestRequest(Method.GET); request.AddHeader("X-Signature", ""); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["X-Signature": ""] let request = NSMutableURLRequest(url: NSURL(string: "https://api.example.com/v1/bundles")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```