跳到主要内容

组织商品集合

将商品分组到集合中，方便买家浏览。

适用场景​

搭建分类页面、促销分组，或按标签自动归类商品。

前置条件​

  • 一个已完成 OAuth 授权与 token 存储的公开应用——先完成 开发应用。下面的每个请求都带 Access-Token: {token} 头，使用你为每个店铺保存的 token。
  • OAuth 授权时已获得 collection 访问权限范围。

工作原理​

集合（collection）是用于分组浏览的容器；成员关系（collect）是把一个商品关联到一个集合的记录。

  • 手动集合（smart: false）只包含你显式以 collect 形式添加的商品——你逐个（或批量）挑选。
  • 智能集合（smart: true）会自动纳入所有匹配其规则（标签、价格、供应商等）的商品——你不需要自己添加 collect。智能集合是异步创建的：创建请求返回一个任务，你需要轮询该任务直到集合就绪。

创建手动集合​

为手动集合显式设置 smart: false——由你精确控制哪些商品属于该集合。

POST /openapi/2026-01/collections

请求体：

{
  "collection": {
    "title": "Summer picks",
    "smart": false // false = 手动集合，由你选择商品
  }
}

响应（节选，集合在 data.data.collection 下）：

{
  "code": "Success",
  "data": {
    "collection": {
      "id": "9574a4b4-1b85-42fc-9b8c-b47e26640cc0",
      "title": "Summer picks",
      "handle": "summer-picks",
      "sort_order": "manual",
      "created_at": "2026-07-02T02:58:32Z",
      "updated_at": "2026-07-02T02:58:32Z"
    }
  }
}
注意

创建手动集合时必须显式设置 smart: false。省略该字段可能导致请求走上智能集合（异步）的处理分支而失败。详见 创建集合。

将商品添加到集合​

一条 collect 把一个商品关联到一个集合。

POST /openapi/2026-01/collects

请求体：

{
  "collect": {
    "collection_id": "9574a4b4-1b85-42fc-9b8c-b47e26640cc0", // 集合的 id
    "product_id": "4d3e7859-455c-4899-a296-7befe731c585"
  }
}

响应（节选，collect 在 data.data.collect 下）：

{
  "code": "Success",
  "data": {
    "collect": {
      "id": "cc6ae5d9-fdc8-4c6a-a413-a9218ed9db0e",
      "collection_id": "9574a4b4-1b85-42fc-9b8c-b47e26640cc0",
      "product_id": "4d3e7859-455c-4899-a296-7befe731c585",
      "position": 1,
      "created_at": "2026-07-02T02:58:34Z",
      "updated_at": "2026-07-02T02:58:34Z"
    }
  }
}

完整字段见 创建成员关系（collect）。

如需一次添加多个商品，使用 POST /collects/batch——见 批量创建 collect。如需移除某个商品，删除其 collect 即可，使用 DELETE /collects/{id}（见 删除 collect）。

创建智能集合​

智能集合会自动包含匹配规则（标签、价格、供应商等）的商品。它是异步创建的：先发起创建，再轮询任务。

POST /openapi/2026-01/collections/async

请求体：

{
  "collection": {
    "title": "New arrivals",
    "smart": true, // true = 智能集合，商品由系统自动匹配
    "match_rules": [
      { "column": "tag", "relation": "equals", "condition": "new" } // 匹配规则：标签等于 "new"
    ]
  }
}

响应：一个含任务 id 的异步任务——见 异步创建集合。轮询 GET /collections/async-task/{id} 直到任务完成——见 获取集合异步任务——之后可用 PATCH /collections/{id}/smart-rule 调整规则。详见 更新智能集合规则。如需异步更新智能规则，使用 异步更新智能集合规则。

更新或删除集合​

按 id 更新或删除集合。

PUT /openapi/2026-01/collections/{id}

请求体：

{
  "collection": {
    "title": "Summer picks (updated)" // 任何你想修改的字段
  }
}

返回更新后的集合——见 更新集合。

DELETE /openapi/2026-01/collections/{id}

见 删除集合。

列出集合与成员​

用 GET /collections 列出集合，或用 GET /collections/{id} 获取单个。用 GET /collects 列出成员关系（collect）。两者都各有一个计数端点。

见 列出集合、获取集合、统计集合数量 和 列出成员关系。

下一步​