分類 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"
    }
  ]
}