V1 Categories API

类目与商品分类模块提供平台类目查询，以及当前店铺的露天商品分类创建、列表和删除能力。

概述

• 所有接口需要 Access Token，通过 Authorization: Bearer <access_token> 传递。
• 平台类目是 Sugumart 维护的商品类目树，用于商品 class_id。
• 商品分类是当前店铺在露天维护的自定义分组，用于商品 store_class_id。
• V1 不开放平台类目的创建、更新或删除。
• 商品分类按 Access Token 绑定的店铺隔离。

---

获取类目列表

GET /openapi/v1/categories

Authentication: Required (Access Token)

逐级获取可用于创建商品的启用类目。未传 parent 时返回一级类目；传入任意层级类目的 g_class 时，只返回该类目的下一层直接子节点。调用方应在用户选择父类目后继续请求下一层，直到选择 selectable=true 的类目。

Query Parameters

字段	类型	必填	说明
parent	string	否	父类目的 g_class；省略时返回一级类目，传入时只返回其下一层直接子节点

Response

字段	类型	说明
categories	Category[]	可用的同层类目列表，按 g_class 升序排列；有效父类目没有子节点时返回空数组

Response Example

{
  "success": true,
  "data": {
    "categories": [
      {
        "id": "cat_bags",
        "g_class": "00110001",
        "name": "背包",
        "level": 2,
        "parent": "0011",
        "color": true,
        "has_children": true,
        "selectable": false
      }
    ]
  }
}

逐级查询示例：

GET /openapi/v1/categories
GET /openapi/v1/categories?parent=0011
GET /openapi/v1/categories?parent=00110001

创建或更新商品时，class_id 必须使用 selectable=true 的类目 g_class。中间节点即使存在也不能直接用于商品发布。

Error Responses

Status	message	code	说明
401	Invalid or expired token	unauthorized	Access Token 无效或已过期
404	Category not found	category_not_found	parent 对应类目不存在、已停用或不可用于当前店铺

---

创建商品分类

POST /openapi/v1/product-categories

Authentication: Required (Access Token)

在当前店铺创建一个露天商品分类。创建成功后服务端刷新当前店铺的完整商品分类缓存。

Request Body

字段	类型	必填	说明
store_class_name	string	是	分类名称，1-30 个 Unicode 字符且不超过 45 UTF-8 bytes
item_sort_mode	string	是	商品排序：new（最新）、price（价格）、sold（销量）
display_sort	number	是	分类显示顺序，1-100 的整数

Request Example

{
  "store_class_name": "通勤精选",
  "item_sort_mode": "new",
  "display_sort": 10
}

Response

字段	类型	说明
product_categories	ProductCategory[]	创建后当前店铺的完整商品分类列表

Response Example

{
  "success": true,
  "data": {
    "product_categories": [
      {
        "store_class_id": "sc_1024",
        "store_class_name": "通勤精选",
        "item_sort_mode": "new",
        "display_sort": 10,
        "synced_at": "2026-08-04T08:15:00.000Z"
      }
    ]
  }
}

Error Responses

Status	message	code	说明
400	Invalid product category	validation_error	名称、排序模式或显示顺序校验失败
401	Invalid or expired token	unauthorized	Access Token 无效或已过期
502	Ruten product category request failed	ruten_store_class_mutation_failed	露天拒绝创建或响应不可用

---

获取商品分类列表

GET /openapi/v1/product-categories

Authentication: Required (Access Token)

返回当前店铺的全部商品分类。存在本地缓存时直接返回缓存；首次查询且无缓存时，服务端从露天同步后返回。列表固定按 display_sort ASC, store_class_id ASC 排列；store_class_id 是显示顺序相同时的稳定第二排序键。

Response

字段	类型	说明
product_categories	ProductCategory[]	当前店铺商品分类列表

Response Example

{
  "success": true,
  "data": {
    "product_categories": [
      {
        "store_class_id": "sc_1024",
        "store_class_name": "通勤精选",
        "item_sort_mode": "new",
        "display_sort": 10,
        "synced_at": "2026-08-04T08:15:00.000Z"
      }
    ]
  }
}

Error Responses

Status	message	code	说明
401	Invalid or expired token	unauthorized	Access Token 无效或已过期
502	Invalid product category response	invalid_ruten_store_class_response	露天商品分类响应无法验证

---

删除商品分类

POST /openapi/v1/product-categories/{id}/delete

Authentication: Required (Access Token)

删除当前店铺的露天商品分类。成功后服务端刷新并返回完整商品分类列表。

Path Parameters

字段	类型	必填	说明
id	string	是	商品分类 ID，1-64 字符

Request Body

无。

Response

字段	类型	说明
product_categories	ProductCategory[]	删除后当前店铺的完整商品分类列表

Response Example

{
  "success": true,
  "data": {
    "product_categories": []
  }
}

Error Responses

Status	message	code	说明
400	Invalid product category ID	validation_error	分类 ID 格式错误
401	Invalid or expired token	unauthorized	Access Token 无效或已过期
404	Product category not found	product_category_not_found	商品分类不存在或不属于当前店铺
409	Product category is in use	product_category_in_use	仍有商品使用该分类；应先移出或改设这些商品的 store_class_id
502	Ruten product category request failed	ruten_store_class_mutation_failed	露天拒绝删除或响应不可用

公共响应字段

Category

字段	类型	说明
id	string	类目记录 ID
g_class	string	平台类目代码；创建商品时作为 class_id
name	string	类目显示名称，优先使用简体名称
level	number	类目层级，正整数
parent	string | null	父类目的 g_class；一级类目为 null
color	boolean	该类目是否具有颜色分类语义
has_children	boolean	是否存在至少一个启用的直接子节点；为 true 时可继续使用 parent=g_class 查询下一层
selectable	boolean	是否可作为商品 class_id；V1 仅允许选择没有启用子节点的末级类目

hscode 属于平台内部类目映射，不在 V1 类目响应中返回。

ProductCategory

字段	类型	说明
store_class_id	string	露天商品分类 ID，对应商品的 store_class_id
store_class_name	string	商品分类名称
item_sort_mode	string	商品排序：new、price、sold
display_sort	number	分类显示顺序，1-100
synced_at	string	最近从露天同步时间，ISO 8601 UTC