本页用于公开业务 API 与扩展集成。接口能力以当前版本和账号权限为准,不应通过修改站点核心路由增加访问权限。

页面与 API 的区别

前台页面使用 /home、/store、/login、/register、/console 等真实路径。业务 API 返回 JSON;主题模板渲染接口可能按其用途返回 HTML,两者不能混为一谈。

API 请求收到首页、登录页或 Nginx 错误页时,应作为异常处理,不要仅凭 HTTP 200 判断成功。排查见常见问题。

后台路径适配

文档中的 /admin/ 仅是后台 API 的示例前缀。站点设置自定义后台路径后,插件、菜单和请求应使用当前后台前缀,不再请求旧默认入口。

不要把实际站点的隐藏后台路径写入公开示例或返回给未登录用户。

JSON 响应

{
  "status": 200,
  "msg": "ok",
  "data": {}
}

客户端需要同时处理 HTTP 错误和业务 status。字段与状态说明见错误处理。

登录与权限

类型 要求
公开内容 只读取当前接口允许公开的信息
会员业务 携带客户登录令牌,只操作自己的数据
后台管理 携带管理员令牌并具备对应模块权限
开放 API 使用为集成分配的 API 凭据及其访问限制

常用请求头:

Authorization: Bearer <token>

令牌只发送到本系统可信地址;不要发送到市场内嵌页、第三方站点或公开日志。

常用内容接口

方法 接口 用途
GET /home/content/siteConfig 前台所需站点和主题展示信息
GET /home/content/banners 轮播内容
GET /home/store/catalog 商店目录
GET /home/store/product?id=<id> 商品详情

更多商品、会员与订单接口见商品接口。公开展示信息不包含后台入口、私密服务配置或密钥。

工单与附件

工单操作需遵守登录与归属限制。常用接口:

方法 接口 用途
GET /home/ticket/departments 部门列表
GET /home/ticket/index 我的工单
GET /home/ticket/read?id=<id> 工单详情
POST /home/ticket/create 提交工单
POST /home/ticket/reply 回复工单
POST /home/ticket/upload 上传附件

附件上传使用 multipart/form-data,文件字段为 file。成功后,按接口返回的附件信息关联工单或回复:

{
  "attachments": [
    { "name": "说明.pdf", "url": "/uploads/tickets/example.pdf", "size": 12345 }
  ]
}

示例 URL 是占位值,实际应使用上传接口返回的地址。

单文件最大 500 MB,每条工单或回复最多 20 个附件。PHP、Nginx 和反向代理也必须允许对应请求大小;达到应用上限不代表所有服务器均可上传成功。

支付通知

按网关配置页面生成的通知地址接入,不自行拼接生产地址。浏览器返回只展示结果,实际付款状态必须以服务端核验后的账单结果为准。

支付配置与扩展接口见支付网关。

下载文档
原始 Markdown 文件