分類

分類物件是部落格文章的一個分類節點，最多九層。

分類端點需要 features.blog_categories 為 true，關閉時回 404 feature_unavailable。共通錯誤（validation_failed、insufficient_scope、not_found）見錯誤。改名、搬移與刪除在商店後台操作。

端點

方法與路徑	中文名	所需權限
`POST /v1/blog/categories`	建立分類	`write_blog`
`GET /v1/blog/categories`	列出分類	`read_blog`

分類物件

欄位	型別	必填或可為 null	用途
`id`	整數	必填	識別碼（唯讀）
`name`	字串	必填	分類名稱
`parent_id`	整數	可為 null	父分類識別碼，最上層為 `null`
`path`	字串	必填	從最上層到自己的名稱路徑，以斜線分隔（唯讀）
`hidden`	布林	必填	是否在前台隱藏
`children`	物件[]	必填	子分類，只有 `format=tree` 才有內容（唯讀）

識別碼是 id，path 供人閱讀。

POST`/v1/blog/categories`

標頭 Idempotency-Key（字串，必填）重送沿用同一把鍵，見慣例。內文：

name（字串，必填）分類名稱，前後空白會去除，同一父分類下不可同名
parent_id（整數，可為 null）父分類識別碼，null 代表建在最上層
hidden（布林，可省略）是否在前台隱藏，預設 false

建立前先列出既有分類。回 201 與分類物件，children 為空陣列。

錯誤碼	狀態碼	處理動作	可重試
`category_name_conflict`	409	沿用 `details` 的 `existing_category_id`	否
`idempotency_key_reused`	409	換一把新鍵	否
`validation_failed`	422	父分類不存在或超過九層時修正 `parent_id`	否

請求

curl -s -X POST https://api.sfec.cloud/v1/blog/categories \
  -H "Authorization: Bearer $SFAPP_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"針織","parent_id":12,"hidden":false}'

import os
import uuid

import requests

response = requests.post(
    "https://api.sfec.cloud/v1/blog/categories",
    headers={
        "Authorization": f"Bearer {os.environ['SFAPP_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"name": "針織", "parent_id": 12, "hidden": False},
)
print(response.status_code, response.json())

const response = await fetch("https://api.sfec.cloud/v1/blog/categories", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SFAPP_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({ name: "針織", parent_id: 12, hidden: false }),
});
console.log(response.status, await response.json());

回應

{
  "id": 56,
  "name": "針織",
  "parent_id": 12,
  "path": "服飾/上衣/針織",
  "hidden": false,
  "children": []
}

GET`/v1/blog/categories`

查詢參數 format（字串，可省略）flat 回扁平列表，預設值；tree 回樹狀結構，畫選單用它。

分類一次全部回傳，meta.next_cursor 固定為 null、meta.limit 固定為 50。

錯誤碼	狀態碼	處理動作	可重試
`validation_failed`	422	`format` 改成 `flat` 或 `tree`	否
`rate_limited`	429	依 `Retry-After` 等待後重送	是

請求

curl -s "https://api.sfec.cloud/v1/blog/categories?format=tree" \
  -H "Authorization: Bearer $SFAPP_KEY"

import os

import requests

response = requests.get(
    "https://api.sfec.cloud/v1/blog/categories",
    headers={"Authorization": f"Bearer {os.environ['SFAPP_KEY']}"},
    params={"format": "tree"},
)
print(response.status_code, response.json())

const url = new URL("https://api.sfec.cloud/v1/blog/categories");
url.searchParams.set("format", "tree");
const response = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.SFAPP_KEY}` },
});
console.log(response.status, await response.json());

回應

{
  "data": [
    {
      "id": 10,
      "name": "服飾",
      "parent_id": null,
      "path": "服飾",
      "hidden": false,
      "children": [
        {
          "id": 12,
          "name": "上衣",
          "parent_id": 10,
          "path": "服飾/上衣",
          "hidden": false,
          "children": []
        }
      ]
    }
  ],
  "meta": { "next_cursor": null, "limit": 50 }
}

分類

端點

分類物件

POST/v1/blog/categories

GET/v1/blog/categories

POST`/v1/blog/categories`

GET`/v1/blog/categories`