寫給代理程式的規則

自動呼叫這組 API 的程式，把下列規則寫進指示裡。

先讀 /v1/me

features 決定哪些端點可用，limits 決定欄位怎麼填，quotas 是今天的剩餘額度。每次工作開始讀一次。

重試時沿用同一把冪等鍵

建立文章與建立分類必須帶 Idempotency-Key。逾時或收到 5xx 時用同一把鍵重送，伺服器回放上次結果。

處理 429

收到 429 時依 Retry-After 等待後重送。三個 429 錯誤碼的處理動作見錯誤碼。

用金鑰指定商店

請求內文出現 tenant_id、site_id、shop_id 這類鍵一律回 422 validation_failed。別家商店的識別碼回 404。

移除標題的 emoji

limits.title_allows_emoji 為 false 時，先移除標題裡的 emoji。直接送出回 422 title_charset_unsupported。

匯入機器可讀規格

把 https://api.sfec.cloud/v1/openapi.json 交給支援 OpenAPI 匯入的代理程式平台，認證選 Bearer 並填入金鑰。金鑰不寫進提示詞。

動作名稱即端點識別名稱，對照如下。

動作名稱	端點
`getMe`	GET /v1/me
`listBlogPosts`	GET /v1/blog/posts
`createBlogPost`	POST /v1/blog/posts
`getBlogPost`	GET /v1/blog/posts/{id}
`updateBlogPost`	PATCH /v1/blog/posts/{id}
`publishBlogPost`	POST /v1/blog/posts/{id}/publish
`unpublishBlogPost`	POST /v1/blog/posts/{id}/unpublish
`deleteBlogPost`	DELETE /v1/blog/posts/{id}
`listBlogCategories`	GET /v1/blog/categories
`createBlogCategory`	POST /v1/blog/categories
`uploadBlogImage`	POST /v1/media/images
`deleteBlogImage`	DELETE /v1/media/images/{id}
`listAuditEvents`	GET /v1/audit/events
`healthz`	GET /healthz

金鑰不帶 publish_blog 時，publishBlogPost 回 403。deleteBlogPost 第一次回 409 confirmation_required，刪除流程見文章。

查出功能開關與欄位上限

features 與 limits 的逐鍵說明與預設值見限制與配額。

import os

import requests

me = requests.get(
    "https://api.sfec.cloud/v1/me",
    headers={"Authorization": f"Bearer {os.environ['SFAPP_KEY']}"},
    timeout=10,
).json()

if not me["features"]["blog"]:
    raise SystemExit("這個商店沒有開通文章功能")

print("可帶分類：", me["features"]["blog_categories"])
print("標題可放 emoji：", me["limits"]["title_allows_emoji"])
print("今日還可新增文章：", me["quotas"]["posts_per_day"] - me["quotas"]["posts_created_today"])