API 调用说明

TanzCMS API 分为四类：公开 Open API、会员侧接口、后台管理接口和插件回调接口。不同类型的接口不能混用鉴权方式。

API 类型

类型	入口	鉴权
Open API	/api/v1/...	API 客户端 AppId/Secret
会员接口	/member/...	会员登录态、CSRF
后台接口	后台入口下的接口	管理员登录态、权限、CSRF
插件回调	/api/callback/{plugin}/{action}	插件签名、来源校验、幂等

Open API 鉴权

后台创建 API 客户端后会得到 app_id 和 secret。Secret 只在创建或重置时显示一次，应由接入方安全保存。

推荐使用 Bearer Token：

Authorization: Bearer {app_id}.{secret}
Accept: application/json

也可以使用请求头：

X-Api-AppId: {app_id}
X-Api-Secret: {secret}
Accept: application/json

权限范围

API 客户端按 scope 授权。常见 scope：

Scope	说明
system.ping	连接测试
site.read	读取站点信息
category.read	读取栏目
article.read	读取内容列表和详情
search.read	搜索内容
member.read	读取会员公开资料
form.submit	提交自定义表单

客户端还可以限制可访问栏目、模型和表单。接口层会自动按客户端授权范围收窄数据。

常用接口

方法	地址	说明
GET	/api/v1/ping	测试凭证和连通性
GET	/api/v1/site	读取站点信息
GET	/api/v1/categories	读取栏目列表，可用 tree=1 返回树
GET	/api/v1/articles	读取已发布内容列表
GET	/api/v1/articles/{id}	读取内容详情
GET	/api/v1/search	搜索已发布内容
GET	/api/v1/members	读取会员公开资料
POST	/api/v1/forms/{code}/submissions	提交自定义表单

分页和字段

列表接口通常支持：

page=1
pagesize=20
fields=id,title,url,published_at

pagesize 应设置合理上限，外部系统不要一次请求大量数据。需要同步全量内容时，应使用分页循环读取，并记录最近同步位置。

响应结构

成功响应：

{
  "code": 0,
  "message": "ok",
  "data": {},
  "pagination": {
    "page": 1,
    "pagesize": 20,
    "total": 100
  }
}

失败响应：

{
  "code": 403,
  "message": "没有接口权限"
}

回调接口

支付、短信、OAuth、物流、Webhook 等第三方主动通知应走统一回调入口：

/api/callback/{plugin}/{action}/{payload?}

回调处理必须具备：

• 签名校验。
• 来源限制或平台证书校验。
• 幂等处理，重复通知不能重复入账或重复发货。
• 请求日志和处理结果日志。
• 明确的成功响应格式。

插件不得自行挂载任意无需鉴权的公开端点。

安全注意

• 不在前端页面暴露 API Secret。
• 不把管理员 Cookie 当作 Open API 凭证。
• 不让公开 API 返回密码、密钥、手机号、邮箱等敏感字段。
• 表单提交接口只允许提交后台启用且客户端授权的表单。
• 第三方回调地址应使用 HTTPS。