# POST /api/item_categories

カテゴリ作成

ショップにカテゴリを作成します。

表示名は `name` で指定できます。
`parent_id` を指定すると、そのカテゴリの下に作成します。
省略または `null` を指定すると、最上位に作成します。
作成したカテゴリは、同じ階層の末尾に並びます。

作成後のカテゴリは `GET /api/item_categories/{id}` で確認することができます。

## 要求スコープ

- `item_categories.write`
- `items.read`

## リクエストボディ

`application/json`

- `name` string（必須 / 1 文字以上 / 30 文字以下）: カテゴリの表示名（1〜30 文字）。絵文字などの 4 バイト文字は使用できません。
- `parent_id` integer | null（任意 / ≥ 0）: 親カテゴリの ID。省略または null の場合は最上位のカテゴリとして作成します。

## レスポンスボディ（200）

`application/json`

- `id` integer（必須 / ≥ 0）: 作成されたカテゴリの ID

## リクエスト例

```sh
curl -X POST "https://apiv2.thebase.com/api/item_categories" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "parent_id": 0
}'
```

## レスポンス

| Status | Description |
| --- | --- |
| `200` | 作成成功。作成されたカテゴリの ID を返します。カテゴリの内容は `GET /api/item_categories/{id}` で取得できます。 |

## エラー

エラーは `application/problem+json` の Problem 形式で返します。認証・スコープ・予期しない内部エラーなど、すべてのエンドポイントに共通のエラーと構造・判別方法は [エラーレスポンス](/docs/errors.md) を参照してください。

このエンドポイントが返すその他のエラーは次のとおりです。

| Status | Type | Description |
| --- | --- | --- |
| `400` | `/errors/request/malformed-body` | リクエストボディをこのエンドポイントが要求する形式として解釈できない場合に返します。 |
| `400` | `/errors/item_categories/invalid-body` | リクエストボディがエンドポイントのスキーマを満たさない場合に返します。 |
| `413` | `/errors/request/body-too-large` | JSON リクエストボディが 1 MiB の上限を超える場合に返します。 |
| `415` | `/errors/request/unsupported-media-type` | JSON 形式のリクエストボディを要求するエンドポイントに、対応していない Content-Type が指定された、または Content-Type が指定されていない場合に返します。 |
| `422` | `/errors/item_categories/write-rejected` | カテゴリの作成・編集、またはカテゴリと商品の結びつけを業務ルールにより実行できない場合に返します (親カテゴリが存在しない、階層の上限を超える、同じ階層に同名のカテゴリが既にある、など)。 |
| `502` | `/errors/internal/bad-gateway` | BASE API が処理を完了するために必要な内部処理で不整合が発生した場合に返します。 |
| `504` | `/errors/internal/gateway-timeout` | BASE API が処理を完了するために必要な内部処理が制限時間内に完了しなかった場合に返します。 |