支付对接 1 更新于 2026-10-13

API 接口文档

一、应用市场接口

供 CMS 客户端（后台「应用市场」）拉取应用清单。

GET /api/market/list?type=template|plugin&charge=free|paid&tag=blog&kw=关键词&page=1

参数	必填	说明
`type`	否	`template`（模板）/ `plugin`（源码），不传返回全部
`charge`	否	`free` / `paid`，不传返回全部
`tag`	否	分类 slug
`kw`	否	关键词，匹配标题与简介
`page`	否	页码，默认 1
`limit`	否	每页条数，默认 20，最大 50

响应

{
  "code": 1,
  "msg": "ok",
  "data": {
    "total": 14,
    "page": 1,
    "pages": 1,
    "items": [
      {
        "id": 2,
        "name": "blog-mo",
        "title": "墨白 · 极简博客模板",
        "type": "template",
        "type_name": "模板",
        "category": "博客类型",
        "category_slug": "blog",
        "summary": "排版优先的极简博客主题……",
        "cover": "",
        "version": "1.1.3",
        "price": "9.90",
        "is_free": false,
        "demo_url": "",
        "tags": ["博客", "极简", "深色模式"],
        "downloads": 2410,
        "rating": 4.92,
        "author": "文枢官方团队",
        "updated_at": "2026-10-11 10:20",
        "download_url": "/api/market/download?id=2",
        "detail_url": "/app/2",
        "homepage": "/app/2"
      }
    ]
  }
}

字段说明：

download_url：安装包下载地址（免费应用直接可下，付费应用需先携带授权令牌）

price：元字符串，0.00 表示免费

二、单个应用详情

GET /api/market/detail?id=2

返回该应用的完整信息与版本列表。

三、下载安装包

GET /api/market/download?id=2&token=<授权令牌>

情况	行为
免费应用	直接返回 zip 流
付费应用 + 有效令牌	返回 zip 流，并记录下载日志
付费应用 + 无令牌	`403 {"code":403,"msg":"该应用需要购买后下载"}`

四、开放接口签名

站内开放接口使用 HMAC-SHA256 签名，规则与文枢CMS 内核一致：

sign = HMAC-SHA256( METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + BODY, AppSecret )

头	说明
`X-App-Id`	应用 ID
`X-Timestamp`	Unix 时间戳（秒），与服务端偏差不得超过 300 秒
`X-Sign`	上述签名的小写十六进制
`Content-Type`	`application/json`

PATH 含 /api 前缀，例如 POST /api/order/query。

TS=$(date +%s)
BODY='{"order_no":"WS20261010ABCDEF"}'
SIGN=$(printf 'POST\n/api/order/query\n%s\n%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$APP_SECRET" -hex | awk '{print $2}')

curl -X POST "https://example.com/api/order/query" \
  -H "X-App-Id: 1001" \
  -H "X-Timestamp: $TS" \
  -H "X-Sign: $SIGN" \
  -H "Content-Type: application/json" \
  -d "$BODY"

五、公开接口

以下接口无需签名，按 IP 限流（默认 60 次 / 分钟）：

接口	说明
`GET /api/market/list`	应用市场列表
`GET /api/market/detail`	应用详情
`GET /api/article/list`	文章列表
`GET /api/doc/list`	文档目录
`GET /api/version`	当前 CMS 版本信息

六、错误码

code	说明
`1`	成功
`-1`	通用失败
`401`	未授权（缺少或失效的令牌）
`403`	无权限（如需购买后下载）
`404`	资源不存在
`419`	CSRF 令牌失效
`429`	请求过于频繁
`500`	服务器错误

统一响应结构：

{ "code": -1, "msg": "错误描述", "data": null }

七、版本兼容

客户端接入时请：

只依赖 code / msg / data 三个顶层字段

items 中新增字段视为向后兼容，不要因为多出字段就报错

遇到 429 做指数退避重试，遇到 4xx 不要重试

上一篇支付渠道对接