Quick Order Form 的 API

使用公共 API 创建、更新、列出和删除 Quick Order Form、Quick Buy Collection 和 Quick Buy Variant 表格。

本页介绍 Quick Order Form 功能系列的公共 API。一个端点可处理三种相关的记录类型，通过 type 字段加以区分：

quick_order_page：独立的 Quick Order Form 页面。
quick_buy_collection：产品系列页面或产品卡片页面上的 Quick Buy 功能。
quick_buy_variant：产品页面上的 Variant Table。

这 4 种操作使用相同的基础 URL、请求头和身份验证，详见公共 API。

创建记录

端点

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（必填）	布尔值：`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 个端点与公共 API 的其他部分使用相同的错误响应。有关 401 Unauthorized、403 Forbidden 和 429 Too Many Requests，请参阅公共 API。

这对您有帮助吗？