本页用于公开业务 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 和反向代理也必须允许对应请求大小;达到应用上限不代表所有服务器均可上传成功。
支付通知
按网关配置页面生成的通知地址接入,不自行拼接生产地址。浏览器返回只展示结果,实际付款状态必须以服务端核验后的账单结果为准。
支付配置与扩展接口见支付网关。