カテゴリー 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"
    }
  ]
}