發布與排程文章

文章的可見狀態由發布與下架端點控制。建立端點一律產出草稿。

status（字串，唯讀）文章目前的可見狀態，由發布時間與下架狀態推導。

建立與更新的請求內文沒有 status 與 published_at 這兩個欄位。送出它們回 422 validation_failed。

發布需要 publish_blog 權限範圍。只有 write_blog 的金鑰呼叫發布端點回 403 insufficient_scope。

1. 用 POST /v1/blog/posts 建立草稿，帶 Idempotency-Key。
2. 用 GET /v1/blog/posts/{id} 讀回草稿，核對內文與 warnings。
3. 用 POST /v1/blog/posts/{id}/publish 發布。內文省略 published_at 代表立即發布。

curl -sS -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":"<p>今年主打燕麥色。</p>"}'

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

curl -sS -X POST https://api.sfec.cloud/v1/blog/posts/1001/publish \
  -H "Authorization: Bearer $SFAPP_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'複製

published_at（字串，可為 null）發布或排定發布的時間。

帶未來的時間，狀態轉為 scheduled。帶過去的時間，狀態轉為 published，等於補登發布日期。

時間格式是 ISO 8601 且含時區位移，例如 2026-09-21T09:00:00+08:00。缺時區回 422 validation_failed。

curl -sS -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-21T09:00:00+08:00"}'複製

改排程時間時，再呼叫一次發布端點並帶新的時間。下架會清空 published_at。

POST /v1/blog/posts/{id}/unpublish 把 published 或 scheduled 收回成 draft，並清空 published_at。下架與發布同樣需要 publish_blog 權限範圍。

對草稿呼叫會原樣回傳該篇文章，不改動資料。

刪除只接受草稿。對 published 或 scheduled 的文章呼叫刪除回 409 post_is_published，先下架再刪。

分類是選用功能。呼叫分類端點前先讀 GET /v1/me 的 features.blog_categories。

• 為 true：分類端點可用，文章可帶 category_ids。
• 為 false：分類端點回 404 feature_unavailable，文章的 category_ids 只能是空陣列，列表查詢也不能帶 category_id。

category_ids（整數陣列，可為 null）這篇文章掛上的所有分類，元素為正整數且不可重複。

default_category_id（整數，可為 null）主要分類，值必須出現在 category_ids 裡，否則回 422 validation_failed。

更新文章時 category_ids 是整批覆蓋。加一個分類時，把原有的識別碼一起送回來。傳 null 或空陣列代表清空分類。

import os

import requests

BASE_URL = "https://api.sfec.cloud"
headers = {"Authorization": f"Bearer {os.environ['SFAPP_KEY']}"}

me = requests.get(f"{BASE_URL}/v1/me", headers=headers, timeout=10).json()
payload = {"title": "秋季針織穿搭", "body_html": "<p>今年主打燕麥色。</p>"}

if me["features"]["blog_categories"]:
    listed = requests.get(f"{BASE_URL}/v1/blog/categories", headers=headers, timeout=10).json()
    ids = [item["id"] for item in listed["data"] if item["name"] == "針織"]
    if ids:
        payload["category_ids"] = ids
        payload["default_category_id"] = ids[0]

print(payload)複製

建立分類前先列出既有分類。同一個父分類底下同名回 409 category_name_conflict，details 附既有分類的識別碼，沿用該識別碼即可。

分類深度上限見 限制與配額。分類的更名、搬移與刪除在商店後台操作。