卡券中心前端对接文档

1. 文档说明

本文档面向商城前端/H5/小程序前端开发，说明 card-voucher-center 插件前台充值相关接口的调用方式、字段说明、状态值定义与业务对接流程。

前台接口由控制器 RechargeController 提供。

2. 路由规则

2.1 路由写法

本插件前台接口不是 /admin/... 形式，而是 YunShop 插件前台约定式路由：

route=plugin.card-voucher-center.frontend.recharge.{action}

框架会将短横线路由自动映射为控制器驼峰方法名。

例如：

  • scan-recharge 会映射到 scanRecharge

2.2 完整 URL 示例

以商城 app_id=12 为例：

/addons/yun_shop/api.php?i=12&type=5&route=plugin.card-voucher-center.frontend.recharge.index
/addons/yun_shop/api.php?i=12&type=5&route=plugin.card-voucher-center.frontend.recharge.detail
/addons/yun_shop/api.php?i=12&type=5&route=plugin.card-voucher-center.frontend.recharge.bind
/addons/yun_shop/api.php?i=12&type=5&route=plugin.card-voucher-center.frontend.recharge.scan-recharge

2.3 路由组成说明

  • plugin：插件路由固定前缀
  • card-voucher-center：插件标识
  • frontend：前台控制器命名空间
  • recharge：控制器名 RechargeController
  • {action}：方法名

3. 业务说明

前台业务核心是“卡券充值到账户余额”。

支持两种使用方式：

  • 手动输入券密充值
  • 扫码识别卡券后充值

支持两类兑换模式：

  • 仅输入券密
  • 输入券号和券密

卡券校验通过后，系统会给当前登录会员增加余额，并把卡券标记为已绑定、已兑换。

4. 状态值定义

4.1 兑换方式 redeem_method

值 名称 说明
1 仅输入券密 用户只需输入 voucher_secret
2 输入券号和券密 用户需要同时输入 voucher_code 与 voucher_secret

4.2 卡券状态 voucher_status

值 名称 说明
1 未激活 卡券已生成，但未激活
2 已激活 卡券可正常参与充值校验
3 已禁用 卡券已被禁用，不可继续使用
4 已作废 卡券已作废，不可继续使用

4.3 绑定状态 bind_status

值 名称 说明
0 未绑定 还没有绑定会员
1 已绑定 已绑定会员

4.4 兑换状态 redeem_status

值 名称 说明
0 未兑换 未给会员充值
1 已兑换 已完成充值

5. 接口列表

接口名称 方法 路由
充值页初始化 GET/POST plugin.card-voucher-center.frontend.recharge.index
卡券预校验 GET/POST plugin.card-voucher-center.frontend.recharge.detail
手动充值 POST plugin.card-voucher-center.frontend.recharge.bind
扫码充值 POST plugin.card-voucher-center.frontend.recharge.scan-recharge

6. 接口明细

6.1 充值页初始化

接口地址

route=plugin.card-voucher-center.frontend.recharge.index

接口用途

进入充值页面时，加载页面初始化信息：

  • 当前商城信息
  • 当前商城支持的兑换方式
  • 默认兑换方式
  • 使用说明文案

请求参数

无

返回字段

字段 类型 说明
app_id int 当前商城 ID
app_name string 当前商城名称
redeem_method_list array 当前商城支持的兑换方式列表
default_redeem_method int 默认兑换方式
tips array 使用说明数组，来源于产品档案 usage_rule
support_scan int 是否支持扫码，固定返回 1

redeem_method_list 字段说明

字段 类型 说明
value int 兑换方式值
label string 兑换方式名称

返回示例

{
  "result": 1,
  "msg": "获取成功",
  "data": {
    "app_id": 12,
    "app_name": "测试商城",
    "redeem_method_list": [
      {
        "value": 1,
        "label": "仅输入券密"
      },
      {
        "value": 2,
        "label": "输入券号和券密"
      }
    ],
    "default_redeem_method": 1,
    "tips": [
      "充值后不可退回",
      "请在有效期内使用"
    ],
    "support_scan": 1
  }
}

对接逻辑

  1. 页面打开先调用本接口。
  2. 根据 redeem_method_list 决定表单展示规则。
  3. 如果只返回一种兑换方式，前端应默认选中并隐藏切换入口。
  4. tips 建议作为页面底部说明直接展示。

6.2 卡券预校验

接口地址

route=plugin.card-voucher-center.frontend.recharge.detail

接口用途

在真正充值前先校验卡券是否存在、是否属于当前商城、是否可充值，并返回卡券摘要信息。

调用模式一：手动输入

请求参数

字段 是否必填 类型 说明
id 否 int 卡券明细 ID，有值时优先按 ID 查询
redeem_method 是 int 兑换方式，1/2
voucher_code 条件必填 string 券号，redeem_method=2 时必填
voucher_secret 是 string 券密

调用模式二：扫码识别

请求参数

字段 是否必填 类型 说明
id 否 int 卡券明细 ID
scan_result 是 string 扫码结果原始字符串

返回字段

字段 类型 说明
id int 卡券明细 ID
voucher_name string 卡券名称
app_id int 所属商城 ID
app_name string 所属商城名称
voucher_code string 券号
redeem_method int 兑换方式
redeem_method_name string 兑换方式名称
voucher_status int 卡券状态值
voucher_status_name string 卡券状态名称
bind_status int 是否已绑定
redeem_status int 是否已兑换
valid_start_at int 有效期开始时间戳
valid_end_at int 有效期结束时间戳
validity_text string 有效期文本
redeem_amount string/number 实际可充值金额

返回示例

{
  "result": 1,
  "msg": "获取成功",
  "data": {
    "id": 1001,
    "voucher_name": "100元储值券",
    "app_id": 12,
    "app_name": "测试商城",
    "voucher_code": "QH260629123401",
    "redeem_method": 2,
    "redeem_method_name": "输入券号和券密",
    "voucher_status": 2,
    "voucher_status_name": "已激活",
    "bind_status": 0,
    "redeem_status": 0,
    "valid_start_at": 1782662400,
    "valid_end_at": 1785254399,
    "validity_text": "2026-06-29 - 2026-07-28",
    "redeem_amount": "100.00"
  }
}

失败场景

常见失败信息：

  • 卡券不存在或校验失败
  • 当前卡券不属于本商城
  • 兑换方式不能为空
  • 券密不能为空
  • 券号不能为空
  • 扫码链接缺少卡券参数

对接逻辑

  1. 用户输入或扫码后，先调本接口。
  2. 成功后展示卡券信息与充值金额。
  3. 只有本接口成功，前端才允许点击“确认充值”。
  4. redeem_amount 必须以后端返回值为准，前端不要自行计算。

6.3 手动充值

接口地址

route=plugin.card-voucher-center.frontend.recharge.bind

接口用途

根据用户手动输入的卡券信息完成充值。

请求参数

与“卡券预校验-手动输入”一致：

字段 是否必填 类型 说明
id 否 int 卡券明细 ID
redeem_method 是 int 兑换方式
voucher_code 条件必填 string 券号
voucher_secret 是 string 券密

返回字段

字段 类型 说明
member_id int 当前会员 ID
id int 卡券明细 ID
redeem_amount string/number 实际充值金额
voucher_code string 券号
app_name string 所属商城名称

返回示例

{
  "result": 1,
  "msg": "充值成功",
  "data": {
    "member_id": 88,
    "id": 1001,
    "redeem_amount": "100.00",
    "voucher_code": "QH260629123401",
    "app_name": "测试商城"
  }
}

服务端处理逻辑

充值成功后，服务端会同时完成以下动作：

  • 校验会员是否已登录
  • 校验卡券状态是否允许充值
  • 调用余额变动服务增加会员余额
  • 写入绑定会员 ID、昵称、手机号
  • 将 bind_status 更新为 1
  • 将 redeem_status 更新为 1
  • 写入 bind_at
  • 写入 redeem_at
  • 写入 redeem_amount
  • 写入 redeem_relation

对接逻辑

  1. 调 detail 成功后再调本接口。
  2. 成功后刷新用户余额。
  3. 前端结果页金额用 redeem_amount。
  4. 如果接口返回错误，前端直接展示后端原始错误文案。

6.4 扫码充值

接口地址

route=plugin.card-voucher-center.frontend.recharge.scan-recharge

接口用途

扫码后直接完成充值。

请求参数

字段 是否必填 类型 说明
id 否 int 卡券明细 ID
scan_result 是 string 扫码结果原始字符串

返回字段

与手动充值一致：

字段 类型 说明
member_id int 当前会员 ID
id int 卡券明细 ID
redeem_amount string/number 实际充值金额
voucher_code string 券号
app_name string 所属商城名称

对接逻辑

  1. 小程序/H5 扫码拿到 scan_result。
  2. 可先调 detail 做预览，也可直接调本接口。
  3. 成功后进入充值成功页。
  4. 若扫码内容格式不符合服务端解析要求，会返回错误提示。

7. 字段详细说明

7.1 卡券识别字段

字段 说明
id 卡券明细主键，优先级最高，适合二维码内已固化卡券 ID 的场景
voucher_code 卡券编号，适用于“券号+券密”模式
voucher_secret 卡券密文，是充值校验核心字段
scan_result 原始扫码结果，服务端会自行解析出卡券参数

7.2 金额字段

字段 说明
redeem_amount 实际到账金额，由服务端根据卡券面额/总金额/销售数量计算，不允许前端自己算

7.3 时间字段

字段 说明
valid_start_at 卡券有效期开始时间戳
valid_end_at 卡券有效期结束时间戳
validity_text 服务端格式化后的有效期展示文案

8. 推荐对接流程

8.1 手动输入流程

  1. 调 index 获取初始化配置。
  2. 用户选择兑换方式并填写卡券信息。
  3. 调 detail 校验卡券。
  4. 前端展示券名称、有效期、到账金额。
  5. 用户点击确认后调 bind。
  6. 成功后刷新余额并跳转成功页。

8.2 扫码流程

  1. 调 index 获取页面配置。
  2. 调起扫码能力，拿到 scan_result。
  3. 可先调 detail 展示确认信息。
  4. 调 scan-recharge 执行充值。
  5. 成功后刷新余额并跳转成功页。

9. 对接注意事项

  1. 前台接口必须使用 route=plugin.card-voucher-center.frontend.recharge.{action}，不要写成后台 /admin/cardVoucher/... 路径。
  2. scan-recharge 路由必须带短横线，不能写成 scanRecharge。
  3. 实际充值金额一定以后端返回的 redeem_amount 为准。
  4. 充值接口要求会员已登录，未登录会报 请先登录。
  5. 同一张券充值成功后会进入已绑定、已兑换状态，不可重复使用。
  6. 如果卡券所属商城与当前 i={app_id} 不匹配，会返回 当前卡券不属于本商城。