**版本：202601**

# 创建商品专辑

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

在店铺中创建一个新的商品专辑，可设置专辑名称、描述、关联商品、SEO 信息及商品排序规则。

## 请求

**application/json**

**请求体 | 示例**

**请求体 (required)**

- `collection` object (required)

  待创建的专辑数据

  - `title` string (required)

    专辑名称
  - `handle` string

    专辑 handle（URL 友好的唯一别名）
  - `description` string

    专辑描述
  - `image` object

    专辑封面

    - `src` string (required)

      专辑封面的源 URL
    - `width` int32

      专辑封面宽度（单位：像素）
    - `height` int32

      专辑封面高度（单位：像素）
    - `alt` string

      专辑封面的替代文本（alt）
  - `seo_title` string

    专辑的 SEO 标题
  - `seo_keywords` string[]

    SEO 关键词列表
  - `seo_description` string

    专辑的 SEO 描述
  - `sort_order` string

    专辑内商品的排序规则，可选值：

    *   `manual`：手动排序（默认）
    *   `sales-desc`：按总销量从高到低
    *   `price-asc`：按售价从低到高
    *   `price-desc`：按售价从高到低
    *   `views-desc`：按浏览人气从高到低
    *   `vendor-asc`：按供应商 A-Z 展示
    *   `vendor-desc`：按供应商 Z-A 展示
    *   `created-desc`：按创建时间从近到远：
    *   `intelligent`：智能推荐排序

    **默认值：** `manual`
  - `product_ids` string[]

    要加入专辑的商品 ID 列表，必须为有效的 UUID
  - `smart` boolean

    是否为智能集合
  - `match_rules` object

    智能集合匹配规则

    - `disjunctive` boolean

      规则模块之间的逻辑关系：

      *   `true`：满足任一规则模块即可（OR）
      *   `false`：所有规则模块都必须满足（AND，默认）
    - `rule_modules` object[]

      规则模块列表

      *   Array \[

      - `disjunctive` boolean

        模块内规则之间的逻辑关系：

        *   `true`：满足任一规则即可（OR）
        *   `false`：所有规则都必须满足（AND，默认）
      - `rules` object[]

        模块内的规则列表

        *   Array \[

        - `column` string

          规则匹配的目标字段。可选值：

          *   `title`：商品标题
          *   `product_status`：商品状态
          *   `tags`：商品标签
          *   `vendor`：供应商 / 品牌
          *   `variant_price`：SKU 价格
          *   `variant_weight`：SKU 重量
          *   `inventory_quantity`：库存数量
          *   `product_note`：商品备注
          *   `sales`：销售量
          *   `real_sales`：实际销售量
          *   `views`：浏览量
          *   `add_to_cart_count`：加购次数
          *   `created_at`：商品创建时间
          *   `spu`：SPU 标识符
          *   `spus_match`：SPU 匹配状态
          *   `published_at`：发布时间
          *   `category_id`：类目 ID
          *   `brand`：品牌
        - `relation` string

          用于匹配的比较运算符。可选值：

          *   `equals`：等于
          *   `not_equals`：不等于
          *   `starts_with`：以...开头
          *   `ends_with`：以...结尾
          *   `contains`：包含
          *   `not_contains`：不包含
          *   `greater_than`：大于
          *   `less_than`：小于
          *   `top`：前 N 个结果（通常用于可排序字段）
        - `condition` string

          规则的条件值

          *   文本字段：普通字符串
          *   数值字段：可转换为数字的字符串
          *   时间字段：时间戳或约定的时间格式
          *   `top` 运算符：代表 N 的值
        *   \]
      *   \]
  - `tags` string[]

    集合标签列表

```json
{
  "collection": {
    "title": "string",
    "handle": "string",
    "description": "string",
    "image": {
      "src": "string",
      "width": 0,
      "height": 0,
      "alt": "string"
    },
    "seo_title": "string",
    "seo_keywords": [
      "string"
    ],
    "seo_description": "string",
    "sort_order": "manual",
    "product_ids": [
      "string"
    ],
    "smart": true,
    "match_rules": {
      "disjunctive": true,
      "rule_modules": [
        {
          "disjunctive": true,
          "rules": [
            {
              "column": "string",
              "relation": "string",
              "condition": "string"
            }
          ]
        }
      ]
    },
    "tags": [
      "string"
    ]
  }
}
```

## 响应

**200**

OK

**application/json**

**数据结构 | 示例**

**数据结构**

- `code` string

  错误码
- `message` string

  错误信息
- `data` object

  - `collection` object

    已创建的专辑

    - `id` string

      专辑 ID
    - `title` string

      专辑名称
    - `description` string

      专辑描述
    - `handle` string

      专辑 handle（URL 友好的唯一别名）
    - `smart` boolean

      是否为智能专辑（满足条件的商品自动加入）
    - `image` object

      专辑封面

      - `src` string

        图片来源 URL
      - `width` int32

        图片宽度（像素）
      - `height` int32

        图片高度（像素）
      - `alt` string

        图片替代文本
    - `seo_title` string

      专辑的 SEO 标题
    - `seo_keywords` string[]

      SEO 关键词列表
    - `seo_description` string

      专辑的 SEO 描述
    - `sort_order` string

      专辑内商品的排序规则（取值见创建专辑接口）
    - `created_at` string

      专辑创建时间（ISO-8601 格式）
    - `updated_at` string

      专辑最后更新时间（ISO-8601 格式）
    - `match_rules` object

      智能集合匹配规则

      - `disjunctive` boolean

        条件是否为析取关系（OR）
      - `rule_modules` object[]

        规则模块列表

        *   Array \[

        - `disjunctive` boolean

          条件是否为析取关系（OR）
        - `rules` object[]

          此模块中的规则列表

          *   Array \[

          - `column` string

            列
          - `relation` string

            关联关系
          - `condition` string

            条件
          *   \]
        *   \]
    - `tags` string[]

      集合标签列表
    - `product_count` int64

      集合中的商品数量

```json
{
  "code": "string",
  "message": "string",
  "data": {
    "collection": {
      "id": "string",
      "title": "string",
      "description": "string",
      "handle": "string",
      "smart": true,
      "image": {
        "src": "string",
        "width": 0,
        "height": 0,
        "alt": "string"
      },
      "seo_title": "string",
      "seo_keywords": [
        "string"
      ],
      "seo_description": "string",
      "sort_order": "string",
      "created_at": "string",
      "updated_at": "string",
      "match_rules": {
        "disjunctive": true,
        "rule_modules": [
          {
            "disjunctive": true,
            "rules": [
              {
                "column": "string",
                "relation": "string",
                "condition": "string"
              }
            ]
          }
        ]
      },
      "tags": [
        "string"
      ],
      "product_count": 0
    }
  }
}
```