Quick Order Form 的 API

使用 Public API 建立、更新、列出及刪除 Quick Order Form、Quick Buy Collection 和 Quick Buy Variant 表格。

本頁介紹 Quick Order Form 功能系列的 Public API。單一端點可處理三種相關的記錄類型，並以 type 欄位區分：

quick_order_page：獨立的 Quick Order Form 頁面。
quick_buy_collection：商品系列／商品卡片頁面上的 Quick Buy 功能。
quick_buy_variant：商品頁面上的 Variant Table。

這 4 種操作使用相同的基礎 URL、標頭和驗證方式，詳見 Public APIs。

建立記錄

端點

POST https://wholesale.samita.io/api/v1/quick-order-forms

請求標頭

標頭	說明	是否必填
`X-SAMITA-API-KEY`	Wholesale 應用程式中提供的 API 金鑰	是
`X-SAMITA-SHOP-URL`	Shopify 商店網域，格式為 xxx.myshopify.com	是
`CONTENT-TYPE`	必須為 `application/json`	是

此 API 需要 API 金鑰具備針對您所建立之特定 type 的 Create 權限。

共用欄位（所有類型）

欄位	類型	是否必填	說明
`title`	string，最多 255 個字元	是	記錄在應用程式中的名稱。
`status`	boolean	是	是否啟用。
`type`	string	是	`quick_order_page`、`quick_buy_collection` 或 `quick_buy_variant`。

其餘必填欄位取決於 type：

欄位	類型	備註
`apply_product`	object（必填）	`type`：`products` 或 `collections`。
`apply_product.product_ids`	array	當 `type` 為 `products` 時必填。
`apply_product.collection_ids`	array	當 `type` 為 `collections` 時必填。
`display_on_page`	string（必填）	顯示此表單的 Shopify 頁面的 handle。
`pagination`	object（必填）	`type`：`pagination` 或 `load_more_button`；`per_page`：1–50 的數字。
`columns`	object（必填）	`product_stock`：boolean，顯示／隱藏庫存欄位。

範例：

{
  "title": "Wholesale Order Form",
  "status": true,
  "type": "quick_order_page",
  "apply_product": {
    "type": "collections",
    "collection_ids": [123456789]
  },
  "display_on_page": "wholesale-order-form",
  "pagination": {
    "type": "pagination",
    "per_page": 20
  },
  "columns": {
    "product_stock": true
  }
}

欄位	類型	備註
`apply_product`	object（必填）	`type`：`all`、`products`、`collections` 或 `product-tags`，並搭配對應的 `product_ids` / `collection_ids` / `product_tags`。
`exclude_product`	object（必填）	`type`：`none`、`products` 或 `collections`，並搭配對應的 ID。
`apply_customer`	object（必填）	`type`：`all`、`logged`、`non-logged` 或 `customer-tags`，適用時搭配 `tags`。
`exclude_customer`	object（必填）	`type`：`none` 或 `customer-tags`，適用時搭配 `tags`。
`display_on_pages`	array（必填）	可為 `index`、`collection`、`search`、`another_page` 的任意組合。
`columns`	object（必填）	Boolean 值：`stock_status`、`quantity`、`variant`、`volume_discount`、`add_to_cart`。

範例：

{
  "title": "Quick Buy on Collections",
  "status": true,
  "type": "quick_buy_collection",
  "apply_product": { "type": "all", "product_ids": [], "product_tags": [], "collection_ids": [] },
  "exclude_product": { "type": "none", "product_ids": [], "collection_ids": [] },
  "apply_customer": { "type": "customer-tags", "tags": ["wholesale"] },
  "exclude_customer": { "type": "none", "tags": [] },
  "display_on_pages": ["collection", "index"],
  "columns": {
    "stock_status": true,
    "quantity": true,
    "variant": true,
    "volume_discount": true,
    "add_to_cart": true
  }
}

欄位	類型	備註
`apply_product`	object（必填）	結構與 `quick_buy_collection` 相同。
`exclude_product`	object（必填）	結構與 `quick_buy_collection` 相同。
`apply_customer`	object（必填）	結構與 `quick_buy_collection` 相同。
`exclude_customer`	object（必填）	結構與 `quick_buy_collection` 相同。
`template`	string（必填）	`default` 或 `matrix-column`。
`columns`	object（必填）	`stock`：boolean，顯示／隱藏庫存欄位。

範例：

{
  "title": "Variant Table",
  "status": true,
  "type": "quick_buy_variant",
  "apply_product": { "type": "all", "product_ids": [], "product_tags": [], "collection_ids": [] },
  "exclude_product": { "type": "none", "product_ids": [], "collection_ids": [] },
  "apply_customer": { "type": "logged", "tags": [] },
  "exclude_customer": { "type": "none", "tags": [] },
  "template": "default",
  "columns": {
    "stock": true
  }
}

回應

200 – Success 會傳回已建立的記錄。請參閱下方 取得記錄 中的範例。

更新記錄

PUT https://wholesale.samita.io/api/v1/quick-order-forms/{id}

標頭與建立時相同。只需傳送您要變更的欄位，title、status、configs 和 product_configs 全都是選填；未指定的欄位會保留目前的值。此 API 需要 Update 權限。

取得記錄

GET https://wholesale.samita.io/api/v1/quick-order-forms/{id}

標頭與建立時相同，不需要請求本文。此 API 需要 View 權限。

200 – Success 範例（type: quick_order_page）：

{
  "id": 1,
  "title": "Wholesale Order Form",
  "status": true,
  "type": "quick_order_page",
  "apply_product": {
    "type": "collections",
    "product_ids": [],
    "collection_ids": [123456789]
  },
  "display_on_page": "wholesale-order-form",
  "pagination": {
    "type": "pagination",
    "per_page": 20
  },
  "columns": {
    "product": true,
    "product_stock": true,
    "quantity": true,
    "action": true
  },
  "created_at": "2026-01-15T10:00:00",
  "updated_at": "2026-01-15T10:00:00"
}

刪除記錄

DELETE https://wholesale.samita.io/api/v1/quick-order-forms/{id}

標頭與建立時相同。傳入 ids 參數，內容為以逗號分隔的待刪除記錄 ID 清單（可作為查詢字串參數或 JSON 本文欄位），例如 ids=1,2,3。此 API 需要 Delete 權限。

200 – Success：

{
  "success": true
}

錯誤回應

這 4 個端點與 Public API 的其他部分使用相同的錯誤回應，401 Unauthorized、403 Forbidden 和 429 Too Many Requests 請參閱 Public APIs。

這對您有幫助嗎？