文章

文章物件是部落格的一篇文章。

共通錯誤（validation_failed、insufficient_scope、feature_unavailable、not_found）見錯誤。

端點

方法與路徑	中文名	所需權限
`POST /v1/blog/posts`	建立文章	`write_blog`
`PATCH /v1/blog/posts/{id}`	更新文章	`write_blog`
`GET /v1/blog/posts/{id}`	取得文章	`read_blog`
`GET /v1/blog/posts`	列出文章	`read_blog`
`POST /v1/blog/posts/{id}/publish`	發布或排程	`publish_blog`
`POST /v1/blog/posts/{id}/unpublish`	下架文章	`publish_blog`
`DELETE /v1/blog/posts/{id}`	刪除文章	`write_blog`

文章物件

欄位	型別	必填或可為 null	用途
`id`	整數	必填	識別碼（唯讀）
`title`	字串	必填	標題
`summary`	字串	可為 null	摘要
`body_html`	字串	必填	內文（已過濾 HTML）
`cover_image`	物件	必填	封面圖 `path` 與 `url`（唯讀）
`status`	字串	必填	`draft`、`scheduled`、`published`（唯讀）
`published_at`	字串	可為 null	發布時間（唯讀）
`category_ids`	整數[]	必填	分類識別碼
`default_category_id`	整數	可為 null	預設分類識別碼
`view_count`	整數	必填	前台瀏覽次數（唯讀）
`public_url`	字串	可為 null	前台網址（唯讀）
`created_at`	字串	必填	建立時間（唯讀）
`updated_at`	字串	必填	更新時間（唯讀）
`warnings`	字串[]	可省略	寫入時移除的項目（唯讀）

列表回應不含 body_html 與 warnings。

POST`/v1/blog/posts`

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

title（字串，必填）標題，前後空白會去除
body_html（字串，必填）內文，依白名單過濾，移除項目列在 warnings
summary、category_ids、default_category_id（可為 null）見文章物件表
cover_image_url（字串，可為 null）封面圖網址，見圖片

上限見限制。回 201，status 為 draft。下表錯誤也適用更新。

錯誤碼	狀態碼	處理動作	可重試
`title_charset_unsupported`	422	見 `limits.title_allows_emoji`	否
`cover_image_not_owned`	422	改填上傳回應的 `url`	否
`content_too_large`	413	縮短內文	否
`duplicate_content`	409	沿用 `details` 的文章	否
`idempotency_key_reused`	409	換一把新鍵	否
`quota_exceeded`	429	見 `quotas.posts_per_day`	否

請求

curl -s -X POST https://api.sfec.cloud/v1/blog/posts \
  -H "Authorization: Bearer $SFAPP_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"title":"秋季針織穿搭指南","body_html":"<h2>選色</h2><p>今年主打燕麥色。</p>","summary":"燕麥色與灰階的搭法。"}'

import os
import uuid

import requests

response = requests.post(
    "https://api.sfec.cloud/v1/blog/posts",
    headers={
        "Authorization": f"Bearer {os.environ['SFAPP_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "title": "秋季針織穿搭指南",
        "body_html": "<h2>選色</h2><p>今年主打燕麥色。</p>",
        "summary": "燕麥色與灰階的搭法。",
    },
)
print(response.status_code, response.json())

const response = await fetch("https://api.sfec.cloud/v1/blog/posts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SFAPP_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    title: "秋季針織穿搭指南",
    body_html: "<h2>選色</h2><p>今年主打燕麥色。</p>",
    summary: "燕麥色與灰階的搭法。",
  }),
});
console.log(response.status, await response.json());

回應

{
  "id": 1001,
  "title": "秋季針織穿搭指南",
  "summary": "燕麥色與灰階的搭法。",
  "body_html": "<h2>選色</h2><p>今年主打燕麥色。</p>",
  "cover_image": { "path": null, "url": null },
  "status": "draft",
  "published_at": null,
  "category_ids": [],
  "default_category_id": null,
  "view_count": 0,
  "public_url": null,
  "created_at": "2026-09-14T11:20:44+08:00",
  "updated_at": "2026-09-14T11:20:44+08:00",
  "warnings": []
}

PATCH`/v1/blog/posts/{id}`

路徑 id（整數，必填）識別碼。內文欄位與建立文章相同，差異如下：

每個欄位都可省略，至少送一個
title、body_html、cover_image_url 不接受 null
summary 與 default_category_id 清空傳 null
category_ids 整批覆蓋，清空傳 null 或空陣列

狀態與發布時間改用發布與下架端點。回 200 與文章物件，錯誤同建立文章。

請求

curl -s -X PATCH https://api.sfec.cloud/v1/blog/posts/1001 \
  -H "Authorization: Bearer $SFAPP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"summary":"燕麥色與灰階的搭法，附實穿照。"}'

import os

import requests

response = requests.patch(
    "https://api.sfec.cloud/v1/blog/posts/1001",
    headers={"Authorization": f"Bearer {os.environ['SFAPP_KEY']}"},
    json={"summary": "燕麥色與灰階的搭法，附實穿照。"},
)
print(response.status_code, response.json())

const response = await fetch("https://api.sfec.cloud/v1/blog/posts/1001", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.SFAPP_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ summary: "燕麥色與灰階的搭法，附實穿照。" }),
});
console.log(response.status, await response.json());

回應

{
  "id": 1001,
  "title": "秋季針織穿搭指南",
  "summary": "燕麥色與灰階的搭法，附實穿照。",
  "body_html": "<h2>選色</h2><p>今年主打燕麥色。</p>",
  "cover_image": { "path": null, "url": null },
  "status": "draft",
  "published_at": null,
  "category_ids": [],
  "default_category_id": null,
  "view_count": 0,
  "public_url": null,
  "created_at": "2026-09-14T11:20:44+08:00",
  "updated_at": "2026-09-14T12:40:18+08:00",
  "warnings": []
}

GET`/v1/blog/posts/{id}`

路徑 id（整數，必填）識別碼。回文章物件，含 warnings。

請求

curl -s https://api.sfec.cloud/v1/blog/posts/1001 \
  -H "Authorization: Bearer $SFAPP_KEY"

import os

import requests

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

const response = await fetch("https://api.sfec.cloud/v1/blog/posts/1001", {
  headers: { Authorization: `Bearer ${process.env.SFAPP_KEY}` },
});
console.log(response.status, await response.json());

回應

{
  "id": 1001,
  "title": "秋季針織穿搭指南",
  "summary": "燕麥色與灰階的搭法。",
  "body_html": "<h2>選色</h2><p>今年主打燕麥色。</p>",
  "cover_image": {
    "path": "uploads/blog/9f2c1b7a4e5d4c8fa1b2c3d4e5f60718.jpg",
    "url": "https://cdn.example.com/yourshop/uploads/blog/9f2c1b7a4e5d4c8fa1b2c3d4e5f60718.jpg"
  },
  "status": "draft",
  "published_at": null,
  "category_ids": [12],
  "default_category_id": 12,
  "view_count": 0,
  "public_url": null,
  "created_at": "2026-09-14T11:20:44+08:00",
  "updated_at": "2026-09-14T12:05:02+08:00",
  "warnings": ["已移除不允許的標籤：<script>"]
}

GET`/v1/blog/posts`

查詢參數：

status（字串，可省略）篩選 draft、scheduled 或 published
category_id（整數，可省略）篩選這個分類的文章
cursor（字串，可省略）上一頁的 meta.next_cursor，原樣帶回
limit（整數，可省略）每頁筆數，1 到 50，預設 20

無分類功能時省略 category_id。data 依建立時間新到舊，meta.next_cursor 為 null 即最後一頁。

請求

curl -s "https://api.sfec.cloud/v1/blog/posts?status=published&limit=20" \
  -H "Authorization: Bearer $SFAPP_KEY"

import os

import requests

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

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

回應

{
  "data": [
    {
      "id": 1001,
      "title": "秋季針織穿搭指南",
      "summary": "燕麥色與灰階的搭法。",
      "cover_image": {
        "path": "uploads/blog/9f2c1b7a4e5d4c8fa1b2c3d4e5f60718.jpg",
        "url": "https://cdn.example.com/yourshop/uploads/blog/9f2c1b7a4e5d4c8fa1b2c3d4e5f60718.jpg"
      },
      "status": "published",
      "published_at": "2026-09-14T10:30:00+08:00",
      "category_ids": [],
      "default_category_id": null,
      "view_count": 218,
      "public_url": "https://www.example-shop.tw/post.php?action=view&id=1001",
      "created_at": "2026-09-13T16:02:11+08:00",
      "updated_at": "2026-09-14T10:30:00+08:00"
    }
  ],
  "meta": { "next_cursor": "MTAwMQ", "limit": 20 }
}

POST`/v1/blog/posts/{id}/publish`

路徑 id（整數，必填）識別碼。內文 published_at（字串，可為 null）發布時間，ISO 8601 且含時區。

省略或給過去時間即立即發布，未來時間即排程。對已發布的文章給未來時間會退回 scheduled。只改時間時再呼叫一次。回 200 與文章物件。

請求

curl -s -X POST https://api.sfec.cloud/v1/blog/posts/1001/publish \
  -H "Authorization: Bearer $SFAPP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"published_at":"2026-09-20T09:00:00+08:00"}'

import os

import requests

response = requests.post(
    "https://api.sfec.cloud/v1/blog/posts/1001/publish",
    headers={"Authorization": f"Bearer {os.environ['SFAPP_KEY']}"},
    json={"published_at": "2026-09-20T09:00:00+08:00"},
)
print(response.status_code, response.json())

const response = await fetch(
  "https://api.sfec.cloud/v1/blog/posts/1001/publish",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SFAPP_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ published_at: "2026-09-20T09:00:00+08:00" }),
  },
);
console.log(response.status, await response.json());

回應

{
  "id": 1001,
  "title": "秋季針織穿搭指南",
  "summary": "燕麥色與灰階的搭法。",
  "body_html": "<h2>選色</h2><p>今年主打燕麥色。</p>",
  "cover_image": { "path": null, "url": null },
  "status": "scheduled",
  "published_at": "2026-09-20T09:00:00+08:00",
  "category_ids": [],
  "default_category_id": null,
  "view_count": 0,
  "public_url": null,
  "created_at": "2026-09-14T11:20:44+08:00",
  "updated_at": "2026-09-14T13:02:55+08:00",
  "warnings": []
}

POST`/v1/blog/posts/{id}/unpublish`

路徑 id（整數，必填）識別碼。沒有請求內文。

已發布或已排程的文章收回成草稿，published_at 一併清空。對草稿呼叫會原樣回傳，回 200。

請求

curl -s -X POST https://api.sfec.cloud/v1/blog/posts/1001/unpublish \
  -H "Authorization: Bearer $SFAPP_KEY"

import os

import requests

response = requests.post(
    "https://api.sfec.cloud/v1/blog/posts/1001/unpublish",
    headers={"Authorization": f"Bearer {os.environ['SFAPP_KEY']}"},
)
print(response.status_code, response.json())

const response = await fetch(
  "https://api.sfec.cloud/v1/blog/posts/1001/unpublish",
  {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.SFAPP_KEY}` },
  },
);
console.log(response.status, await response.json());

回應

{
  "id": 1001,
  "title": "秋季針織穿搭指南",
  "summary": "燕麥色與灰階的搭法。",
  "body_html": "<h2>選色</h2><p>今年主打燕麥色。</p>",
  "cover_image": { "path": null, "url": null },
  "status": "draft",
  "published_at": null,
  "category_ids": [],
  "default_category_id": null,
  "view_count": 218,
  "public_url": null,
  "created_at": "2026-09-14T11:20:44+08:00",
  "updated_at": "2026-09-14T13:40:09+08:00",
  "warnings": []
}

DELETE`/v1/blog/posts/{id}`

路徑 id（整數，必填）識別碼。內文 confirmation_token（字串，第二次必填）第一次呼叫取得的確認碼。

刪除無法復原，分兩次送出。第一次不帶內文，回 409 與確認碼。details 另含 expires_in_seconds、post.title、post.status。標題交給人確認後，第二次帶確認碼送出，回 204。確認碼 5 分鐘內有效，綁定這篇文章與金鑰。已發布的文章先下架。

錯誤碼	狀態碼	處理動作	可重試
`confirmation_required`	409	取出確認碼後送第二次	否
`post_is_published`	409	先呼叫下架端點	否
`post_has_product_links`	409	請人在後台解除關聯	否

請求

# 第一次：取得確認碼，回 409
curl -s -X DELETE https://api.sfec.cloud/v1/blog/posts/1001 \
  -H "Authorization: Bearer $SFAPP_KEY"

# 第二次：帶確認碼刪除，回 204
curl -s -o /dev/null -w '%{http_code}\n' -X DELETE https://api.sfec.cloud/v1/blog/posts/1001 \
  -H "Authorization: Bearer $SFAPP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirmation_token":"AAAD6WjQ3sBnVDZ1Xk9mQpLd4TfR2bCy"}'

import os

import requests

url = "https://api.sfec.cloud/v1/blog/posts/1001"
headers = {"Authorization": f"Bearer {os.environ['SFAPP_KEY']}"}

first = requests.delete(url, headers=headers)
token = next(
    item["issue"]
    for item in first.json()["error"]["details"]
    if item["field"] == "confirmation_token"
)
print("請人確認後再刪除：", first.json()["error"]["message"])

second = requests.delete(url, headers=headers, json={"confirmation_token": token})
print(second.status_code)

const url = "https://api.sfec.cloud/v1/blog/posts/1001";
const headers = { Authorization: `Bearer ${process.env.SFAPP_KEY}` };

const first = await fetch(url, { method: "DELETE", headers });
const body = await first.json();
const token = body.error.details.find(
  (item) => item.field === "confirmation_token",
).issue;
console.log("請人確認後再刪除：", body.error.message);

const second = await fetch(url, {
  method: "DELETE",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ confirmation_token: token }),
});
console.log(second.status);

回應

{
  "error": {
    "code": "confirmation_required",
    "message": "即將永久刪除文章「秋季針織穿搭指南」（id=1001），此操作無法復原。請帶 confirmation_token 再送一次以確認。",
    "details": [
      { "field": "confirmation_token", "issue": "AAAD6WjQ3sBnVDZ1Xk9mQpLd4TfR2bCy" },
      { "field": "expires_in_seconds", "issue": "300" },
      { "field": "post.title", "issue": "秋季針織穿搭指南" },
      { "field": "post.status", "issue": "draft" }
    ],
    "request_id": "req_k4m2p7q9r3s5t8v6w2x4y7z3",
    "retryable": false
  }
}

文章

端點

文章物件

POST/v1/blog/posts

PATCH/v1/blog/posts/{id}

GET/v1/blog/posts/{id}

GET/v1/blog/posts

POST/v1/blog/posts/{id}/publish

POST/v1/blog/posts/{id}/unpublish