常用业务接口清单,按应用归类。接口是否可用取决于系统版本、登录身份和相应权限。通用约定见 12 API 与路由,错误处理见 27 常见问题与错误处理。

文档中的 /admin/ 是示例前缀,自定义后台路径后应使用站点当前配置的前缀。真实密码、令牌和 API Key 不应出现在公开示例或日志中。

通用约定

  • 路径:/{app}/{控制器}/{动作}(控制器名转蛇形,如 ThemeTpl → theme_tpl)
  • 响应:{ "status": 200, "msg": "...", "data": ... }
  • 鉴权:需登录的接口带 Authorization: Bearer <JWT>(开放 API 兼容 JWT <token>)
  • 列表分页:data: { list: [], total: N }

一、前台公开接口(/home,无需登录)

Content 内容

方法 路径 说明
GET /home/content/siteConfig 站点 + 主题 bundle(站名、导航、SEO、主题配置)
GET /home/content/maintenance 维护公告
GET /home/content/affClick 推广链接点击记录
GET /home/content/banners 轮播图
GET /home/content/announcements 公告列表
GET /home/content/announcement?id= 公告详情
GET /home/content/kb 知识库分类+文章树
GET /home/content/kbArticle?id= 知识库文章详情

Store 商店

方法 路径 说明
GET /home/store/catalog 商品组树 + 商品 + 最低价
GET /home/store/group?id= 单商品组及其商品
GET /home/store/product?id= 商品详情(定价 + 可配置选项;上游商品可能返回跳转)
GET /home/store/redirect?id= 上游代理商品 301 跳转

主题 SSR(魔方 .tpl)

方法 路径 说明
GET /tpl/home、/tpl/cart 美化路由,转发到 theme_tpl/page
GET /home/theme_tpl/render?type=&page= 渲染指定模板(HTML 或 format=json)
GET /home/theme_tpl/page?path= SSR 首页/购物车入口

二、会员中心接口(/home,需登录)

说明

鉴权:UserAuth 中间件校验 Authorization: Bearer <JWT>(type=user)。

Auth 账户

方法 路径 说明
POST /home/auth/register 注册
POST /home/auth/login 登录换 JWT
GET /home/auth/me 当前用户信息
POST /home/auth/logout 登出
POST /home/auth/realname 提交实名认证
GET /home/auth/realnameQuery 查询实名结果

Console 控制台

方法 路径 说明
GET /home/console/summary 概览统计
GET /home/console/services 我的服务实例列表
GET /home/console/service?id= 服务实例详情
GET /home/console/invoices 我的账单
POST /home/console/updateProfile 修改资料
POST /home/console/changePassword 修改密码

Order 下单

方法 路径 说明
POST /home/order/create 创建订单(生成账单)
POST /home/order/checkPromo 校验优惠码
GET /home/order/index 我的订单

Invoice 账单 / 支付

方法 路径 说明
GET /home/invoice/read?id= 账单详情
GET /home/invoice/methods 可用支付方式
POST /home/invoice/pay 发起在线支付
POST /home/invoice/payCredit 余额支付
GET /home/invoice/status?id= 支付状态轮询

Ticket 工单

方法 路径 说明
GET /home/ticket/departments 工单部门
GET /home/ticket/index 工单列表
POST /home/ticket/create 新建工单(可携带附件)
GET /home/ticket/read?id= 工单详情(含附件)
POST /home/ticket/reply 回复工单(可携带附件)
POST /home/ticket/close 关闭工单
POST /home/ticket/upload 上传工单附件(≤500MB,最多 20 个)
说明

附件上传与约束详见 12 API 与路由 · 工单与附件。

Affiliate 推广

方法 路径 说明
GET /home/affiliate/index 推广概况
GET /home/affiliate/commissions 佣金明细
POST /home/affiliate/withdraw 申请提现
GET /home/affiliate/withdrawals 提现记录

三、开放 API v1(/api/v1,上下游对接)

供下游系统代理本系统商品。下游用「本系统账号 + API 密钥」换 JWT(2 小时),后续请求带 Authorization: JWT <token>(兼容 Bearer)。下单计入该账号名下并用账号余额实时结算。

方法 路径 说明
POST /api/v1/login username + password(API密钥) → JWT(含 IP 白名单校验)
GET /api/v1/products 商品目录
GET /api/v1/productsconfig?id= 商品详情(可配置选项 + 定价)
POST /api/v1/order 下单并用余额结算,返回开通凭据
GET /api/v1/host?id= 服务实例详情(状态轮询/凭据)
POST /api/v1/renew?id= 续费并用余额结算
GET /api/v1/credit 余额查询

示例:登录 + 下单

# 1. 换取 JWT
curl -X POST https://你的域名/api/v1/login \
  -d "username=downstream@x.com&password=<API密钥>"
# → { "status":200, "data": { "jwt":"...", "expire":7200 } }

# 2. 下单(余额结算)
curl -X POST https://你的域名/api/v1/order \
  -H "Authorization: JWT <jwt>" \
  -d "product_id=18&billing_cycle=monthly&qty=1"
# → { "status":200, "data": { "order_num":"...","hosts":[{...凭据}] } }

API 密钥在后台 上下游 → API 密钥(/admin/api_key/*)管理,可设 IP 白名单。


四、支付回调(/api)

支付通知地址使用网关配置页生成的结果,服务端请求方式以所选驱动约定为准。浏览器同步返回仅用于展示,付款结果以服务器核验后的账单为准。详见支付网关。


五、后台接口

后台接口数量较多,按权限模块组织,操作语义见 25 管理员操作文档。统一前缀 /admin/{控制器}/{动作},需 AdminAuth + 模块权限。常见模式:index(列表)、read(详情)、create/update/delete(增改删)。


下一篇:25 管理员操作文档

下载文档
原始 Markdown 文件