# 组织商品集合

> 用 Open API 把 Shoplazza 商品归入手动集合和智能集合、往集合里加商品，并查询集合与关联记录。

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

## 适用场景

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

## 前置条件

- 一个已完成 OAuth 授权与 token 存储的公开应用——先完成 [开发独立应用](/docs/app/getting-started/create-public-app/develop-app)。下面的每个请求都带 `Access-Token: {token}` 头，使用你为每个店铺保存的 token。
- OAuth 授权时已获得 `collection` 访问权限范围。

## 工作原理

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

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

### 创建手动集合

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

`POST /openapi/2026-01/collections`

请求体：

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

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

```json
{
  "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"
    }
  }
}
```

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

### 将商品添加到集合

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

`POST /openapi/2026-01/collects`

请求体：

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

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

```json
{
  "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）](/api/collect-create)。

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

### 创建智能集合

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

`POST /openapi/2026-01/collections/async`

请求体：

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

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

### 更新或删除集合

按 id 更新或删除集合。

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

请求体：

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

返回更新后的集合——见 [更新集合](/api/collection-update)。

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

见 [删除集合](/api/collection-delete)。

## 列出集合与成员

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

见 [列出集合](/api/collections)、[获取集合](/api/collection-detail)、[统计集合数量](/api/collection-count) 和 [列出成员关系](/api/collects)。

## 下一步

- [管理库存](/docs/app/use-cases/product-merchandising/manage-inventory)
- [创建与更新商品](/docs/app/use-cases/product-merchandising/create-and-update-products)