身分

身分物件描述一把金鑰的所屬應用程式、商店功能開關與用量上限。

基底網址是 https://api.sfec.cloud，只提供 HTTPS。範例從環境變數 SFAPP_KEY 讀金鑰。

端點

方法與路徑	中文名	所需權限
`GET /v1/me`	取得身分與功能開關	任一有效金鑰
`GET /v1/openapi.json`	取得 OpenAPI 文件	公開
`GET /healthz`	檢查服務狀態	公開
`GET /quickstart.sh`	取得啟動腳本	公開

身分物件

欄位全部唯讀。

欄位	型別	必填或可為 null	用途
`app_id`	字串	必填	金鑰所屬的應用程式識別碼。
`app_name`	字串	必填	應用程式名稱。
`shop_name`	字串	必填	商店顯示名稱。
`shop_public_url`	字串	必填	商店前台網址，結尾不含斜線。
`scopes`	字串陣列	必填	金鑰擁有的權限範圍。
`features`	物件	必填	商店開通的功能開關，值皆為布林值，逐鍵說明見限制與配額。
`limits`	物件	必填	欄位與圖片的上限，逐鍵說明見限制與配額。
`quotas`	物件	必填	每日配額與今日已用量。
`rate_limits`	物件	必填	每分鐘讀寫次數與同時處理中的請求上限。
`api_version`	字串	必填	目前的 API 版本，格式為日期。
`key_expires_at`	字串	可為 null	金鑰到期時間；不設到期日時為 `null`。

端點細節

權限寫在上方的端點清單表。

GET`/v1/me`

沒有參數。回應是身分物件。

錯誤碼	狀態碼	處理動作	可重試
`unauthorized`	401	檢查 `Authorization` 標頭的金鑰。	否
`not_found`	404	確認金鑰對應的商店存在。	否
`rate_limited`	429	依 `Retry-After` 等待後重送。	是
`tenant_not_certified`	503	等商店完成開通後再試。	否

請求

curl -s https://api.sfec.cloud/v1/me -H "Authorization: Bearer $SFAPP_KEY"

import os

import requests

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

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

回應

{
  "app_id": "app_7f3a9c1e",
  "app_name": "內容代理程式",
  "shop_name": "範例商店",
  "shop_public_url": "https://www.example-shop.tw",
  "scopes": ["read_audit", "read_blog", "write_blog"],
  "features": {
    "blog": true,
    "blog_categories": false,
    "media_upload": true,
    "summary": true,
    "cover_image": true,
    "published_at_sort": true
  },
  "limits": {
    "title_max_chars": 255,
    "title_allows_emoji": false,
    "summary_max_chars": 1000,
    "body_max_bytes": 1048576,
    "categories_supported": false,
    "category_max_depth": 9,
    "list_limit_max": 50,
    "image_max_bytes": 10485760,
    "image_max_pixels": 25000000,
    "image_max_total_pixels": 50000000,
    "image_max_width": 1600,
    "image_max_gif_frames": 100,
    "image_formats": ["image/jpeg", "image/png", "image/gif", "image/webp"]
  },
  "quotas": {
    "posts_per_day": 50,
    "posts_created_today": 3,
    "images_per_day": 200,
    "images_uploaded_today": 12
  },
  "rate_limits": {
    "read_per_minute": 120,
    "write_per_minute": 30,
    "concurrent_requests": 4
  },
  "api_version": "2026-09-14",
  "key_expires_at": "2027-09-14T00:00:00+08:00"
}

GET`/v1/openapi.json`

沒有參數，不需金鑰。回應是一份 OpenAPI 文件，最外層有 openapi、info、servers、paths、components、security 六個鍵。把網址交給 SDK 產生器或代理程式平台即可產生串接程式碼，步驟見代理程式指南。

非預期失敗回 500 internal_error，見錯誤。

請求

curl -s https://api.sfec.cloud/v1/openapi.json | head -c 200

import requests

response = requests.get("https://api.sfec.cloud/v1/openapi.json")
document = response.json()
print(document["info"]["version"], sorted(document["paths"]))

const response = await fetch("https://api.sfec.cloud/v1/openapi.json");
const document = await response.json();
console.log(document.info.version, Object.keys(document.paths));

回應

{
  "openapi": "3.1.0",
  "info": { "title": "sfapp 商家平台 API", "version": "2026-09-14" },
  "servers": [{ "url": "https://api.sfec.cloud" }],
  "paths": { "/v1/me": { "get": { "operationId": "getMe" } } },
  "components": {
    "securitySchemes": { "sfappBearer": { "type": "http", "scheme": "bearer" } }
  },
  "security": [{ "sfappBearer": [] }]
}

GET`/healthz`

沒有參數，不需金鑰。回應欄位：

status（字串，必填）服務存活時為 ok
api_version（字串，必填）目前的 API 版本

非預期失敗回 500 internal_error，見錯誤。

請求

curl -s https://api.sfec.cloud/healthz

import requests

response = requests.get("https://api.sfec.cloud/healthz")
print(response.status_code, response.json())

const response = await fetch("https://api.sfec.cloud/healthz");
console.log(response.status, await response.json());

回應

{ "status": "ok", "api_version": "2026-09-14" }

GET`/quickstart.sh`

沒有參數，不需金鑰。回應是 text/x-shellscript 純文字。腳本依序查身分、建草稿、讀回，金鑰讀自環境變數 SFAPP_KEY。腳本只需要 curl 與 python3，不發布、不刪除、不上傳圖片。

非預期失敗回 500 internal_error，見錯誤。

請求

curl -fsSL https://api.sfec.cloud/quickstart.sh -o quickstart.sh
SFAPP_KEY="$SFAPP_KEY" bash quickstart.sh

import requests

response = requests.get("https://api.sfec.cloud/quickstart.sh")
with open("quickstart.sh", "w", encoding="utf-8") as script_file:
    script_file.write(response.text)
print("已存成 quickstart.sh，讀過內容後再執行：SFAPP_KEY=... bash quickstart.sh")

import { writeFile } from "node:fs/promises";

const response = await fetch("https://api.sfec.cloud/quickstart.sh");
await writeFile("quickstart.sh", await response.text(), "utf-8");
console.log("已存成 quickstart.sh，執行前先讀過內容。");

回應

#!/usr/bin/env bash
# 矽羽商家平台 API 快速開始
set -euo pipefail

身分

端點

身分物件

端點細節

GET/v1/me

GET/v1/openapi.json

GET/healthz

GET/quickstart.sh

GET`/v1/me`

GET`/v1/openapi.json`

GET`/healthz`

GET`/quickstart.sh`