分类 API

管理支持嵌套层级的商品分类。

接口列表

GET

/categories

categories:read

获取所有分类的平面列表。

GET

/categories/tree

categories:read

获取包含嵌套子分类的完整分类树。

GET

/categories/:id

categories:read

通过 ID 获取单个分类。

POST

/categories

categories:write

创建新分类。设置 parentId 可创建子分类。

PUT

/categories/:id

categories:write

更新现有分类。支持部分更新。

DELETE

/categories/:id

categories:write

软删除分类。该分类下的商品不受影响。

字段参考

字段	类型	必填	描述
id	string	否	唯一分类标识符（只读）
name	string	是	分类名称
slug	string	否	URL 友好的别名（省略时自动生成）
description	string	否	分类描述
parentId	string	否	用于嵌套的父分类 ID
imageUrl	string	否	分类图片 URL
sortOrder	integer	否	显示排序（数值越小越靠前）
isActive	boolean	否	分类是否启用（默认：true）
children	Category[]	否	嵌套的子分类（仅在树端点中返回）
createdAt	datetime	否	ISO 8601 时间戳（只读）
updatedAt	datetime	否	ISO 8601 时间戳（只读）

示例

获取分类树

bash

curl "https://api.mercozy.com/api/v1/external/categories/tree" \
  -H "X-API-Key: mk_live_xxxxx"

创建分类

bash

curl -X POST "https://api.mercozy.com/api/v1/external/categories" \
  -H "X-API-Key: mk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Electronics",
    "description": "Electronic devices and accessories",
    "sortOrder": 1,
    "isActive": true
  }'

响应示例（树结构）

json

{
  "data": [
    {
      "id": "cat_abc123",
      "name": "Electronics",
      "slug": "electronics",
      "description": "Electronic devices and accessories",
      "parentId": null,
      "imageUrl": null,
      "sortOrder": 1,
      "isActive": true,
      "children": [
        {
          "id": "cat_def456",
          "name": "Smartphones",
          "slug": "smartphones",
          "description": "Mobile phones",
          "parentId": "cat_abc123",
          "imageUrl": null,
          "sortOrder": 1,
          "isActive": true,
          "children": []
        }
      ],
      "createdAt": "2025-12-15T10:30:00Z",
      "updatedAt": "2025-12-15T10:30:00Z"
    }
  ]
}