Logo

菜单

Aツ韩先生
Aツ韩先生
发布于 2026-02-02 / 23 阅读
0
0

小氢云发卡系统模板开发教程

接口文档

前台公共接口文档

本文档列出了系统中所有前台公共接口，包括接口地址、请求参数、响应示例和接口说明。

目录

系统配置接口

1. 获取系统配置

接口说明：获取系统基础配置信息，包括管理路径、应用名称、版本号等。

接口地址：GET /api/config

请求参数：无

响应示例：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "admin_path": "/admin",
    "app_name": "小氢云发卡系统",
    "version": "1.0.0"
  }
}

字段说明：

  • admin_path: 管理端路径
  • app_name: 应用名称
  • version: 应用版本号

网站信息接口

2. 获取站点配置

接口说明：获取前台站点配置信息，包括 Logo、公告、联系方式等配置项。

接口地址：GET /api/home/config

请求参数：无

响应示例：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "app_name": "小氢云发卡系统",
    "version": "1.0.0",
    "admin_path": "/admin",
    "base_url": "https://example.com"
  }
}

字段说明：

  • app_name: 应用名称
  • version: 应用版本号
  • admin_path: 管理端路径
  • base_url: 基础URL

3. 获取网站信息

接口说明：获取网站所有配置信息，以 key-value 格式返回，包括网站名称、Logo、公告、联系方式等。

接口地址：GET /api/home/site-info

请求参数：无

响应示例：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "site_title": "小氢云发卡系统",
    "site_name": "小氢云发卡",
    "site_keywords": "发卡系统,虚拟商品,自动发货",
    "site_description": "专业的虚拟商品发卡系统，支持自动发货，安全可靠",
    "site_notice": "<p>欢迎使用小氢云发卡系统！</p>",
    "site_logo": "",
    "last_login_ip": "",
    "pc_template": "default",
    "pe_template": "default"
  }
}

重要说明（别再被示例误导）：

  • 该接口返回的是 site_config 表里 所有 配置项的 key/value（map[string]string），字段数量 不是固定的。
  • 你在后台「网站设置/模板/授权/支付渠道」等新增或更新了配置项，这里就会多返回对应的 key。

4. 获取支付渠道

接口说明：获取启用的支付渠道列表，返回各支付渠道的启用状态。

接口地址：GET /api/home/payment-channels

请求参数：无

响应示例：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "alipay": true,
    "wxpay": true,
    "qqpay": false
  }
}

说明：

  • alipay: 支付宝支付是否启用
  • wxpay: 微信支付是否启用
  • qqpay: QQ支付是否启用

重要说明：

  • 这里的 qqpay 只是“渠道开关”展示；当前后端下单与支付接口匹配逻辑里，payment_method 仅支持 alipay / wxpay（见 PaymentInterfaceRepository.GetEnabledByPaymentMethod）。

分类接口

5. 获取分类列表

接口说明：获取所有启用的商品分类列表，用于前台展示分类导航。

接口地址：GET /api/home/category/list

请求参数：无（前台接口固定只返回启用的分类）

响应示例：

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": 1,
      "name": "游戏点卡",
      "image": "https://example.com/category1.jpg",
      "sort": 1,
      "status": 1,
      "created_at": "2024-01-01T12:00:00Z",
      "updated_at": "2024-01-01T12:00:00Z"
    },
    {
      "id": 2,
      "name": "会员充值",
      "image": "",
      "sort": 2,
      "status": 1,
      "created_at": "2024-01-01T12:00:00Z",
      "updated_at": "2024-01-01T12:00:00Z"
    }
  ]
}

字段说明：

  • id: 分类ID（整数）
  • name: 分类名称（字符串）
  • image: 分类图片URL（字符串，可能为空字符串）
  • sort: 排序值（整数），数字越小越靠前
  • status: 状态（整数，1=启用，0=禁用）
  • created_at: 创建时间（ISO 8601格式）
  • updated_at: 更新时间（ISO 8601格式）

商品接口

6. 获取商品列表

接口说明：获取商品列表，支持分页、分类筛选、关键词搜索。前台接口固定只返回启用的商品。

接口地址：GET /api/home/goods/list

请求参数：

参数名 类型 必填 说明
page int 否 页码，默认1
size int 否 每页数量，默认20
category_id int 否 分类ID，筛选指定分类的商品
name string 否 商品名称关键词，模糊搜索

请求示例：

GET /api/home/goods/list?page=1&size=20&category_id=1&name=点卡

响应示例：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "list": [
      {
        "id": 1,
        "category_id": 1,
        "name": "王者荣耀点卡100元",
        "image": "https://example.com/goods1.jpg",
        "description": "王者荣耀点卡100元面值，可用于游戏内充值",
        "price": "100.00",
        "stock": 100,
        "status": 1,
        "sales": 50,
        "created_at": "2024-01-01T12:00:00Z",
        "updated_at": "2024-01-01T12:00:00Z"
      },
      {
        "id": 2,
        "category_id": 1,
        "name": "和平精英点卡50元",
        "image": "",
        "description": "",
        "price": "50.00",
        "stock": 200,
        "status": 1,
        "sales": 30,
        "created_at": "2024-01-01T12:00:00Z",
        "updated_at": "2024-01-01T12:00:00Z"
      }
    ],
    "total": 100
  }
}

字段说明：

  • id: 商品ID（整数）
  • category_id: 分类ID（整数）
  • name: 商品名称（字符串）
  • image: 商品图片URL（字符串，可能为空字符串）
  • description: 商品描述（字符串，可能为空字符串）
  • price: 商品价格（字符串格式，保留两位小数）
  • stock: 库存数量（整数，实际卡密库存）
  • status: 状态（整数，1=启用，0=禁用）
  • sales: 已售数量（整数）
  • created_at: 创建时间（ISO 8601格式）
  • updated_at: 更新时间（ISO 8601格式）
  • total: 总记录数（整数）

7. 获取商品详情

接口说明：根据商品 ID 获取商品详细信息，包括商品描述、价格、库存等。

接口地址：GET /api/home/goods/:id

请求参数：

参数名 类型 必填 说明
id int 是 商品ID（路径参数）

请求示例：

GET /api/home/goods/1

响应示例：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "category_id": 1,
    "name": "王者荣耀点卡100元",
    "image": "https://example.com/goods1.jpg",
    "description": "<p>王者荣耀点卡100元面值，可用于游戏内充值</p><p>支持多种支付方式，安全可靠</p>",
    "price": "100.00",
    "stock": 100,
    "status": 1,
    "sales": 50,
    "created_at": "2024-01-01T12:00:00Z",
    "updated_at": "2024-01-01T12:00:00Z"
  }
}

字段说明：

  • id: 商品ID
  • category_id: 分类ID
  • name: 商品名称
  • image: 商品图片URL（可能为空字符串）
  • description: 商品描述（HTML格式，可能为空字符串）
  • price: 商品价格（字符串格式，保留两位小数）
  • stock: 库存数量（实际卡密库存，整数）
  • status: 状态（1=启用，0=禁用）
  • sales: 已售数量（整数）
  • created_at: 创建时间（ISO 8601格式）
  • updated_at: 更新时间（ISO 8601格式）

错误响应：

  • 商品不存在：{"code": 404, "msg": "商品不存在"}
  • 商品已下架：{"code": 404, "msg": "商品已下架"}

订单接口

8. 创建订单

接口说明：创建订单，如果商品支持自动发卡且库存充足，会直接返回成功；否则返回支付 URL，需要跳转到支付页面完成支付。

接口地址：POST /api/home/order/create

请求参数：

参数名 类型 必填 说明
goods_id int 是 商品ID
quantity int 是 购买数量
contact_info string 否 联系方式（邮箱/QQ等），用于接收卡密
payment_method string 否 支付方式：alipay（支付宝） / wxpay（微信支付）。注意：当前不支持 qqpay 作为下单支付方式

请求示例：

{
  "goods_id": 1,
  "quantity": 2,
  "contact_info": "user@example.com",
  "payment_method": "alipay"
}

响应示例（需要支付）：

{
  "code": 201,
  "msg": "订单创建成功，请前往支付",
  "url": "https://example.com/api/home/payment/ORD1234567890123456789",
  "data": {
    "id": 1,
    "order_no": "ORD1234567890123456789",
    "goods_id": 1,
    "quantity": 2,
    "total_price": "200.00",
    "status": "pending",
    "contact_info": {
      "String": "user@example.com",
      "Valid": true
    },
    "payment_method": {
      "String": "alipay",
      "Valid": true
    },
    "created_at": "2024-01-01T12:00:00Z",
    "updated_at": "2024-01-01T12:00:00Z"
  }
}

响应示例（免费商品自动发卡成功）：

{
  "code": 200,
  "msg": "订单创建成功，卡密已发送至您的邮箱",
  "data": {
    "id": 1,
    "order_no": "ORD1234567890123456789",
    "goods_id": 1,
    "quantity": 2,
    "total_price": "0.00",
    "status": "sent",
    "contact_info": {
      "String": "user@example.com",
      "Valid": true
    },
    "payment_method": {
      "String": "",
      "Valid": false
    },
    "created_at": "2024-01-01T12:00:00Z",
    "updated_at": "2024-01-01T12:00:00Z"
  }
}

字段说明：

  • id: 订单ID
  • order_no: 订单号
  • goods_id: 商品ID
  • quantity: 购买数量
  • total_price: 订单总价（字符串格式，保留两位小数）
  • status: 订单状态（pending=待支付，paid=已支付待发卡，sent=已发卡，cancelled=已取消）
  • contact_info: 联系方式（对象，结构为 {"String": "...", "Valid": true/false}，来自 database/sql.NullString 的默认JSON序列化）
  • payment_method: 支付方式（对象，结构为 {"String": "alipay|wxpay", "Valid": true/false}）
  • created_at: 创建时间（ISO 8601格式）
  • updated_at: 更新时间（ISO 8601格式）

说明：

  • code=200: 订单创建成功，卡密已自动发放（如果支持自动发卡）
  • code=201: 订单创建成功，需要跳转到支付页面完成支付
  • url: 支付页面URL（仅在code=201时返回；后端会把相对路径补全为绝对地址）
  • status: 订单状态（pending=待支付，paid=已支付待发卡，sent=已发卡，cancelled=已取消）
  • HTTP状态码：当 code=201 时，HTTP 状态码也会返回 201；其它情况为 200

9. 查询订单

接口说明：根据订单号或联系方式查询订单信息，如果订单已发货，会返回卡密信息。不返回待支付（pending）状态的订单。

接口地址：GET /api/home/order/query

请求参数：

参数名 类型 必填 说明
order_no string 否 订单号（与contact_info至少填一个）
contact_info string 否 联系方式（与order_no至少填一个）
page int 否 页码，默认1
size int 否 每页数量，默认20

请求示例：

GET /api/home/order/query?order_no=ORDER20240101001

或

GET /api/home/order/query?contact_info=user@example.com&page=1&size=20

响应示例：

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": 1,
      "order_no": "ORD1234567890123456789",
      "goods_id": 1,
      "quantity": 2,
      "total_price": "200.00",
      "status": "sent",
      "contact_info": "user@example.com",
      "created_at": "2024-01-01T12:00:00Z",
      "cards": [
        "CARD001 PASSWORD001",
        "CARD002 PASSWORD002"
      ]
    },
    {
      "id": 2,
      "order_no": "ORD1234567890123456790",
      "goods_id": 2,
      "quantity": 1,
      "total_price": "100.00",
      "status": "paid",
      "contact_info": "user2@example.com",
      "created_at": "2024-01-01T13:00:00Z"
    }
  ]
}

字段说明：

  • id: 订单ID
  • order_no: 订单号
  • goods_id: 商品ID
  • quantity: 购买数量
  • total_price: 订单总价（字符串格式，保留两位小数）
  • status: 订单状态（paid=已支付待发卡，sent=已发卡，cancelled=已取消）
  • contact_info: 联系方式（字符串，可能为空字符串）
  • created_at: 创建时间（ISO 8601格式）
  • cards: 卡密列表（仅在status=sent时返回，格式：卡号 密码，多个卡密用数组返回。如果卡密没有密码，则只返回卡号）

错误响应：

  • 参数错误：{"code": 400, "msg": "请输入订单号或联系方式"}

支付接口

10. 支付页面

接口说明：获取支付页面 HTML，自动提交支付表单到支付平台。此接口返回 HTML 页面，不是 JSON 格式。

接口地址：GET /api/home/payment/:order_no

请求参数：

参数名 类型 必填 说明
order_no string 是 订单号（路径参数）

请求示例：

GET /api/home/payment/ORDER20240101001

响应：返回 HTML 页面，自动跳转到支付平台

错误响应：

  • 订单不存在：返回文本 "订单不存在"
  • 订单状态不正确：返回文本 "订单状态不正确"
  • 订单未指定支付方式：返回文本 "订单未指定支付方式"
  • 支付接口未配置：返回文本 "支付接口未配置或未启用"

11. 支付回调（兼容旧路径）

接口说明：支付平台回调接口，兼容旧路径。支持 GET 和 POST 请求。

接口地址：ANY /api/payment/callback

请求参数：由支付平台传递，不同支付平台参数不同

响应：

  • 成功：返回文本 "success"
  • 失败：返回文本 "fail"

说明：此接口由支付平台调用，不需要前端调用。

12. 支付异步通知

接口说明：支付平台异步回调接口（服务器回调），用于接收支付结果通知。

接口地址：ANY /api/payment/notify

请求参数：由支付平台传递，不同支付平台参数不同

响应：

  • 成功：返回文本 "success"
  • 失败：返回文本 "fail"

说明：此接口由支付平台服务器调用，不需要前端调用。

13. 支付同步返回

接口说明：支付平台同步回调接口（用户浏览器回跳），支付完成后跳转回本站，展示支付结果和卡密信息。

接口地址：ANY /api/payment/return

请求参数：由支付平台传递，不同支付平台参数不同

响应：返回 HTML 页面，展示支付结果和卡密信息（如果已发卡）

说明：此接口由支付平台在用户支付完成后跳转调用，不需要前端主动调用。

14. 支付同步验证

接口说明：同步验证订单支付状态，用于前端轮询查询订单是否已支付。

接口地址：GET /api/user/getPay2

请求参数：

参数名 类型 必填 说明
order_no string 是 订单号

请求示例：

GET /api/user/getPay2?order_no=ORDER20240101001

响应示例（已支付）：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "order_no": "ORD1234567890123456789",
    "status": "paid",
    "paid": true
  }
}

响应示例（待支付）：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "order_no": "ORD1234567890123456789",
    "status": "pending",
    "paid": false,
    "message": "订单状态查询完成"
  }
}

响应示例（已发卡）：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "order_no": "ORD1234567890123456789",
    "status": "sent",
    "paid": true
  }
}

字段说明：

  • order_no: 订单号
  • status: 订单状态（pending=待支付，paid=已支付待发卡，sent=已发卡）
  • paid: 是否已支付（布尔值）
  • message: 提示信息（仅在待支付时返回）

产品版本接口

15. 获取产品版本列表

接口说明：获取产品版本列表（更新日志），代理到授权站获取。

接口地址：GET /api/frontend/product-versions

请求参数：

参数名 类型 必填 说明
product_id int 否 产品ID（后端强制设置为3，忽略前端传递的值）
page int 否 页码
size int 否 每页数量

请求示例：

GET /api/frontend/product-versions?page=1&size=20

响应示例（有分页信息）：

{
  "code": 200,
  "msg": "操作成功",
  "data": [],
  "total": 10,
  "page": 1,
  "size": 20
}

响应示例（无分页信息）：

{
  "code": 200,
  "msg": "操作成功",
  "data": []
}

说明：

  • 此接口会代理到授权站获取数据，如果授权站返回 code=1，本站会转换为 code=200。
  • data 内部字段 完全以授权站返回为准（本站不定义版本项的字段模型；这里只保证外层包装结构与分页字段）。

节点管理接口

16. 获取公共节点列表

接口说明：获取所有可用节点列表（登录前使用），包含节点连接状态和延迟信息。

接口地址：GET /api/admin/getPublicNodeList

请求参数：无

响应示例：

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": 1,
      "name": "节点1",
      "location": "北京",
      "url": "https://node1.example.com",
      "status": 1,
      "ping": 50
    },
    {
      "id": 2,
      "name": "节点2",
      "location": "上海",
      "url": "https://node2.example.com",
      "status": 1,
      "ping": 80
    }
  ]
}

字段说明：

  • id: 节点ID
  • name: 节点名称
  • location: 节点位置
  • url: 节点URL
  • status: 节点状态（1=可用，0=不可用）
  • ping: 延迟（毫秒）

17. 获取当前公共节点

接口说明：获取当前使用的节点信息（登录前使用）。

接口地址：GET /api/admin/getPublicCurrentNode

请求参数：无

响应示例：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "name": "节点1",
    "location": "北京",
    "url": "https://node1.example.com",
    "status": 1,
    "ping": 50
  }
}

错误响应：

  • 没有可用节点：{"code": 500, "msg": "没有可用的节点"}

18. 切换公共节点

接口说明：切换当前使用的节点（登录前使用）。

接口地址：POST /api/admin/switchPublicNode

请求参数：

参数名 类型 必填 说明
node_id int 是 节点ID

请求示例：

{
  "node_id": 2
}

响应示例：

{
  "code": 200,
  "msg": "切换节点成功",
  "data": null
}

错误响应：

  • 节点不存在：{"code": 400, "msg": "节点不存在"}
  • 切换失败：{"code": 500, "msg": "切换节点失败: xxx"}

通用响应格式

所有接口统一使用以下响应格式：

成功响应

{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}

分页响应

{
  "code": 200,
  "msg": "操作成功",
  "data": [],
  "total": 100,
  "page": 1,
  "size": 20
}

错误响应

{
  "code": 400,
  "msg": "错误信息"
}

状态码说明：

  • 200: 操作成功
  • 201: 创建成功（需要支付）
  • 400: 请求参数错误
  • 404: 资源不存在
  • 500: 服务器内部错误
  • 407: 授权密钥未配置 / 授权校验失败（LicenseAuth 中间件拦截）
  • 409: 体验授权过期（LicenseAuth 中间件拦截）
  • 401: 未登录（管理端接口常见）
  • 403: 无权限访问（如图片预览越权）

HTTP 状态码说明（很关键）：

  • 本项目大多数 JSON 接口 无论成功/失败，HTTP 都返回 200，真正的业务状态看 JSON 里的 code（见 pkg/response/response.go）。
  • 例外：
    • POST /api/home/order/create：当返回体 code=201 时，HTTP 也会返回 201
    • GET /health：不是统一响应结构（直接 {status,time}）
    • GET /api/home/payment/:order_no：返回 HTML（不是 JSON）
    • ANY /api/payment/*：返回纯文本 success/fail（不是 JSON）

其他公共接口（补充：非“前台业务API”但同样公开）

A1. 健康检查

接口说明：服务存活检测（无统一包装）。

接口地址：GET /health

请求参数：无

响应示例：

{
  "status": "ok",
  "time": "2026-02-01T12:00:00+08:00"
}

A2. 获取管理员登录验证码图片

接口说明：返回验证码 PNG 图片流（不是 JSON）。

接口地址：GET /api/admin/getLoginCode

请求参数：

参数名 类型 必填 说明
type string 否 验证码类型（默认 adminLogin），用于区分存储key

响应：image/png 二进制图片

A3. 图片预览（管理端上传图片回显）

接口说明：通过安全校验后返回图片文件流（不是 JSON）。

接口地址：GET /api/admin/upload/preview

请求参数：

参数名 类型 必填 说明
path string 是 上传后返回的相对路径（文件名）

响应：image/jpeg / image/png / image/webp 等二进制图片

A4. 前台静态资源（模板资源）

接口说明：按当前模板配置动态读取并返回前台静态资源文件（不是 JSON）。

接口地址：

  • GET /assets/pc/*filepath
  • GET /assets/pe/*filepath

请求参数：路径参数 filepath（如：/assets/pc/assets/index-xxxx.js）

响应：对应文件内容（Content-Type 按扩展名推断）

A5. 前台首页

接口说明：根据 User-Agent 判断 PC/ 移动端，返回对应模板的 index.html（不是 JSON）。

接口地址：GET /

请求参数：无

响应：text/html; charset=utf-8

注意事项

  1. 认证要求：所有前台公共接口都不需要登录认证，但部分接口需要 License 授权（通过 LicenseAuth 中间件）。

  2. 访问统计：/api/home/* 和 /api/config 接口会自动统计访问量（PV）。

  3. 支付回调：支付相关回调接口由支付平台调用，前端不需要主动调用。

  4. 订单查询：查询订单接口不会返回待支付（pending）状态的订单，只返回已支付或已发货的订单。

  5. 卡密显示：卡密信息仅在订单已发货（status=sent）时返回，且卡密已通过邮箱发送，页面不再显示卡密内容。

  6. 商品库存：商品详情接口返回的库存是实际卡密库存，不是商品配置的库存。

  7. 支付方式：创建订单时如果不指定支付方式，系统会根据配置自动选择或要求用户选择。

  8. 节点管理：节点管理接口分为公共接口（登录前）和管理接口（登录后），公共接口返回完整的节点信息包括 URL。

更新日志

  • 2024-01-01: 初始版本，包含所有前台公共接口文档


开发教程

你可以直接把文档喂给 AI 或使用 f12 抓包接口

该系统比较简单，模板功能比较少。

模板开发手机端可以使用 vue3，打包成单页项目：index.html、assets。

把打包好的模板放进 public/template/pc 或 pe 目录中，然后再创建一个 config.json 文件，里面存放的是模板的信息

模板配置文件说明

config.json 字段说明

每个模板目录下必须包含一个 config.json 文件，用于描述模板的基本信息。

配置字段

字段 类型 必填 说明
version string ✅ 模板版本号，建议使用语义化版本号（如：1.0.0）
name string ✅ 模板名称，必须与模板目录名一致（如：default、jingfaka）
display_name string ✅ 在管理后台显示的模板名称
description string ✅ 模板描述信息，用于说明模板的特点和功能
author string ⭕ 模板作者或开发团队（可选）
homepage string ⭕ 模板主页或文档链接（可选，留空表示无）
thumbnail string ⭕ 模板缩略图路径，相对于模板目录（可选，留空表示无）

配置示例

{
  "version": "1.0.0",
  "name": "default",
  "display_name": "默认PC模板",
  "description": "小氢云发卡系统默认PC端模板，采用现代化设计风格，支持响应式布局，适配各种屏幕尺寸",
  "author": "小氢云团队",
  "homepage": "",
  "thumbnail": ""
}

注意事项

  1. JSON 格式：配置文件必须使用标准 JSON 格式，不支持注释
  2. name 字段：必须与模板目录名完全一致
  3. 路径说明：thumbnail 路径相对于模板根目录，例如：thumbnail.png 表示模板目录下的 thumbnail.png 文件
  4. 版本号：建议使用语义化版本号（Semantic Versioning），格式：主版本号.次版本号.修订号

小氢云商城系统 V1.0.83 升级通知

评论