水机类 SIM 卡充值 — 前端 API 文档

对接流程

  • 商用水机（机主中心）：SIM卡列表 / 设备的SIM卡 → 创建充值订单（可多选）→ 拿 order_ids 走商城标准订单支付页 → 充值记录
  • 家用水机、厨下水机（设备中心）：查看SIM卡 → 创建充值订单（按设备）→ 拿 order_ids 走商城标准订单支付页 → 充值记录

通用说明

  • 所有接口都要求会员已登录。返回 result=1 为成功，result=0 为失败，失败原因在 msg 里，直接提示给用户即可。
  • SIM 卡有两个到期时间：机主到期时间 owner_expire_at（商城，机主每充值一次按"单次充值天数"顺延）和平台到期时间 platform_expire_at（中台）。任一到期设备都不可用。
  • expire_at 是有效到期时间 = 两者中较早的那个，页面上的"到期时间/有效期"直接显示它；expire_status 也按它计算。expire_warn=true（已到期或剩余 ≤10 天）时日期标红。
  • 支付：创建订单返回 order_ids（多个用英文逗号分隔），跳转商城标准订单支付页，和普通商品下单后的支付一致（支付页调用 order.merge-pay，参数 order_ids）。SIM 充值订单不会出现在"我的订单"里，也不支持退款。
  • 支付成功后系统自动向平台续费，一般几十秒内完成。期间充值记录显示"处理中"，SIM 卡的 renewing=true，这时不能重复充值。续费失败会原路退款，记录显示"失败（已退款）"。
  • 商用水机和家用、厨下的接口不同。家用和厨下共用同一套接口，只是路由的插件名不一样。

一、商用水机

1. SIM卡列表

简要描述：

机主名下所有设备的 SIM 卡列表（原型：SIM卡管理）。

请求域名:

  • http://xx.com

请求路由:

POST/&route=plugin.yz-supply-water-machine.frontend.business.sim-card.index

请求参数说明:

参数名 类型 是否必需 说明
page int 否 页码，默认1
page_size int 否 每页条数，默认15
sim_no string 否 SIM卡号，模糊搜索

返回示例:

正确时返回:

{
    "result": 1,
    "msg": "ok",
    "data": {
        "current_page": 1,
        "data": [
            {
                "sim_no": "89860861TEST00000603",
                "device_id": 3,
                "device_no": "860000000000603",
                "device_name": "SIM测试商用3",
                "address": "南山区测试路3号",
                "city": "深圳",
                "status": "未激活",
                "operator": "中国电信",
                "month_usage": "0.00",
                "expire_at": "2026-09-20 17:56:52",
                "expire_warn": true,
                "expire_status": "expired",
                "expire_status_text": "已到期",
                "owner_expire_at": "2026-09-20 17:56:52",
                "platform_expire_at": "2027-09-20 17:56:52",
                "recharge_amount": "50.00",
                "recharge_days": 365,
                "can_recharge": false,
                "renewing": false
            },
            {
                "sim_no": "89860861TEST00000601",
                "device_id": 1,
                "device_no": "860000000000601",
                "device_name": "SIM测试商用1",
                "address": "天河区测试路1号",
                "city": "广州",
                "status": "已激活",
                "operator": "中国移动",
                "month_usage": "12.50",
                "expire_at": "2030-09-27 17:56:52",
                "expire_warn": false,
                "expire_status": "normal",
                "expire_status_text": "正常",
                "owner_expire_at": "2026-09-20 17:56:52",
                "platform_expire_at": "2027-09-20 17:56:52",
                "recharge_amount": "45.00",
                "recharge_days": 365,
                "can_recharge": true,
                "renewing": false
            }
        ],
        "first_page_url": "http://xx.com?page=1",
        "from": 1,
        "last_page": 1,
        "last_page_url": "http://xx.com?page=1",
        "next_page_url": null,
        "path": "http://xx.com",
        "per_page": 15,
        "prev_page_url": null,
        "to": 2,
        "total": 2
    }
}

错误时返回:

{
    "result": 0,
    "msg": "您还不是机主, 请先申请机主!",
    "data": []
}

返回参数说明:

参数名 类型 说明
total int 总条数
per_page int 每页条数
current_page int 当前页
last_page int 最后一页
data array SIM卡列表
data[].sim_no string SIM卡号，创建充值订单时传这个
data[].device_id int 设备ID
data[].device_no string 设备号
data[].device_name string 设备名称
data[].address string 设备地址
data[].city string 设备所在城市，原型"(中国移动 广州)"里的城市
data[].status string SIM卡状态：已激活 / 未激活
data[].operator string 运营商
data[].month_usage string 本月用量(MB)
data[].expire_at string 有效到期时间（机主到期、平台到期中较早的一个），页面显示的"有效期/到期时间"，未设置时为空字符串
data[].expire_warn bool 是否标红：已到期或剩余≤10天
data[].expire_status string 到期状态（按 expire_at）：normal正常 / soon即将到期 / expired已到期 / unset未设置；expired 时设备不可用
data[].expire_status_text string 到期状态文字
data[].owner_expire_at string 机主到期时间（商城）
data[].platform_expire_at string 平台到期时间（中台）
data[].recharge_amount string 单次充值金额(元)
data[].recharge_days int 单次充值天数（后台"激活一次有效天数"，默认365），充值一次机主到期顺延这么多天
data[].can_recharge bool 能否充值，false 时置灰充值按钮
data[].renewing bool 是否有续费处理中的订单，true 时提示"续费处理中"

2. 设备的SIM卡

简要描述：

设备管理 → 查看sim卡弹窗，查询一台设备绑定的 SIM 卡。设备没绑卡时 data 为 null，前端提示"该设备未绑定SIM卡"。

请求域名:

  • http://xx.com

请求路由:

POST/&route=plugin.yz-supply-water-machine.frontend.business.sim-card.detail

请求参数说明:

参数名 类型 是否必需 说明
device_id int 是 设备ID

返回示例:

正确时返回:

{
    "result": 1,
    "msg": "ok",
    "data": {
        "sim_no": "89860861TEST00000601",
        "device_id": 1,
        "device_no": "860000000000601",
        "device_name": "SIM测试商用1",
        "address": "天河区测试路1号",
        "city": "广州",
        "status": "已激活",
        "operator": "中国移动",
        "month_usage": "12.50",
        "expire_at": "2030-09-27 17:56:52",
        "expire_warn": false,
        "expire_status": "normal",
        "expire_status_text": "正常",
        "owner_expire_at": "2026-09-20 17:56:52",
        "platform_expire_at": "2027-09-20 17:56:52",
        "recharge_amount": "45.00",
        "recharge_days": 365,
        "can_recharge": true,
        "renewing": false
    }
}

错误时返回:

{
    "result": 0,
    "msg": "设备不存在",
    "data": []
}

返回参数说明:

同「1. SIM卡列表」的 data[] 字段。弹窗展示：卡号 sim_no、状态 status、运营商 operator、本月用量 month_usage、到期时间 expire_at。

3. 创建充值订单

简要描述：

SIM卡管理页勾选一张或多张卡后充值。每张卡生成一个订单，返回的 order_ids 一起传给标准支付页合并支付。金额由服务端按卡计算，前端不需要传金额。

请求域名:

  • http://xx.com

请求路由:

POST/&route=plugin.yz-supply-water-machine.frontend.business.sim-recharge-create.index

请求参数说明:

参数名 类型 是否必需 说明
sim_nos array 是 SIM卡号数组，1~20张，如 sim_nos[]=898...601&sim_nos[]=898...602；也支持逗号分隔的字符串

返回示例:

正确时返回:

{
    "result": 1,
    "msg": "成功",
    "data": {
        "order_ids": "231494,231495",
        "amount": "95.00"
    }
}

错误时返回:

{
    "result": 0,
    "msg": "SIM卡89860861TEST00000603暂不支持续费，请联系平台",
    "data": []
}

返回参数说明:

参数名 类型 说明
order_ids string 订单ID，多个用英文逗号分隔，传给标准支付页
amount string 本次应付总金额(元)

常见错误 msg：请选择SIM卡 / 单次最多充值20张 / SIM卡xxx不存在 / SIM卡xxx不属于您的设备 / SIM卡xxx暂不支持续费，请联系平台 / SIM卡xxx续费处理中，请稍后再试 / SIM卡充值订单金额异常，请联系平台

4. 充值记录

简要描述：

机主的 SIM 卡缴费记录（原型：SIM卡缴费记录）。只返回已支付的记录，未支付和已取消的不返回。

请求域名:

  • http://xx.com

请求路由:

POST/&route=plugin.yz-supply-water-machine.frontend.business.sim-card.records

请求参数说明:

参数名 类型 是否必需 说明
page int 否 页码，默认1
page_size int 否 每页条数，默认15
sim_no string 否 SIM卡号，模糊搜索

返回示例:

正确时返回:

{
    "result": 1,
    "msg": "ok",
    "data": {
        "current_page": 1,
        "data": [
            {
                "id": 4,
                "sim_no": "89860861TEST00000602",
                "device_no": "860000000000602",
                "device_name": "SIM测试商用2",
                "amount": "50.00",
                "pay_type_name": "余额",
                "days": 365,
                "paid_at": "2026-09-23 18:17:24",
                "status": 3,
                "status_text": "失败（已退款）",
                "remark": "中台续费失败：SIM卡充值失败：该SIM卡未设置续费金额，请联系运营人员设置后再充值"
            },
            {
                "id": 3,
                "sim_no": "89860861TEST00000601",
                "device_no": "860000000000601",
                "device_name": "SIM测试商用1",
                "amount": "45.00",
                "pay_type_name": "余额",
                "days": 365,
                "paid_at": "2026-09-23 18:16:45",
                "status": 2,
                "status_text": "成功",
                "remark": ""
            }
        ],
        "first_page_url": "http://xx.com?page=1",
        "from": 1,
        "last_page": 1,
        "last_page_url": "http://xx.com?page=1",
        "next_page_url": null,
        "path": "http://xx.com",
        "per_page": 15,
        "prev_page_url": null,
        "to": 2,
        "total": 2
    }
}

返回参数说明:

参数名 类型 说明
total int 总条数
data array 记录列表
data[].id int 记录ID
data[].sim_no string SIM卡号
data[].device_no string 设备号
data[].device_name string 设备名称
data[].amount string 支付金额(元)
data[].pay_type_name string 支付方式
data[].days int 本次充值顺延的机主到期天数
data[].paid_at string 充值时间
data[].status int 状态：1处理中 / 2成功 / 3失败（已退款） / 4失败（请联系客服）
data[].status_text string 状态文字，直接展示；原型里"成功"用绿色，"失败"用红色
data[].remark string 失败原因，可不展示

二、家用水机 / 厨下水机

两个插件的接口完全一样，只是路由里的插件名不同：

插件 路由前缀
家用水机 plugin.yz-supply-home-water-machin.frontend.sim.
厨下水机 plugin.yz-supply-under-sink-machine.frontend.sim.

下面的示例以厨下水机为例。

5. 查看SIM卡

简要描述：

设备中心 → 查看sim卡弹窗（原型：卡号、状态、运营商、本月用量、到期时间、单次充值金额、单次充值天数、充值按钮）。设备没绑卡时 data 为 null。

请求域名:

  • http://xx.com

请求路由:

POST/&route=plugin.yz-supply-under-sink-machine.frontend.sim.sim-card.detail
POST/&route=plugin.yz-supply-home-water-machin.frontend.sim.sim-card.detail

请求参数说明:

参数名 类型 是否必需 说明
device_id int 是 设备ID

返回示例:

正确时返回:

{
    "result": 1,
    "msg": "ok",
    "data": {
        "sim_no": "89860862TEST00000701",
        "device_id": 1,
        "device_no": "860000000000701",
        "device_name": "SIM测试厨下1",
        "address": "天河区测试路7号",
        "location_name": "广州站",
        "status": "已激活",
        "operator": "中国移动",
        "month_usage": "5.00",
        "expire_at": "2029-11-21 17:56:52",
        "expire_warn": false,
        "expire_status": "normal",
        "expire_status_text": "正常",
        "owner_expire_at": "2026-09-20 17:56:52",
        "platform_expire_at": "2027-09-20 17:56:52",
        "recharge_amount": "40.00",
        "recharge_days": 365,
        "can_recharge": true,
        "renewing": false
    }
}

错误时返回:

{
    "result": 0,
    "msg": "设备不存在",
    "data": []
}

返回参数说明:

参数名 类型 说明
sim_no string 卡号
device_id int 设备ID
device_no string 设备IMEI
device_name string 设备名称
address string 安装地址
location_name string 场所名称
status string SIM卡状态：已激活 / 未激活
operator string 运营商
month_usage string 本月用量(MB)
expire_at string 有效到期时间（机主到期、平台到期中较早的一个），弹窗里的"到期时间"显示它，未设置时为空字符串
expire_warn bool 是否标红：已到期或剩余≤10天
expire_status string 到期状态（按 expire_at）：normal正常 / soon即将到期 / expired已到期 / unset未设置；expired 时设备不可用
expire_status_text string 到期状态文字
owner_expire_at string 机主到期时间（商城）
platform_expire_at string 平台到期时间（中台）
recharge_amount string 单次充值金额(元)
recharge_days int 单次充值天数（后台"激活一次有效天数"，默认365），充值一次机主到期顺延这么多天
can_recharge bool 能否充值，false 时置灰充值按钮
renewing bool 是否有续费处理中的订单，true 时提示"续费处理中"

6. 创建充值订单

简要描述：

查看sim卡弹窗点"充值"，按设备下单（一张卡一个订单），返回 order_ids 跳转标准支付页。金额由服务端计算。

请求域名:

  • http://xx.com

请求路由:

POST/&route=plugin.yz-supply-under-sink-machine.frontend.sim.sim-recharge-create.index
POST/&route=plugin.yz-supply-home-water-machin.frontend.sim.sim-recharge-create.index

请求参数说明:

参数名 类型 是否必需 说明
device_id int 是 设备ID

返回示例:

正确时返回:

{
    "result": 1,
    "msg": "成功",
    "data": {
        "order_ids": "231496",
        "amount": "40.00"
    }
}

错误时返回:

{
    "result": 0,
    "msg": "该设备未绑定SIM卡",
    "data": []
}

返回参数说明:

参数名 类型 说明
order_ids string 订单ID，传给标准支付页
amount string 应付金额(元)

常见错误 msg：设备不存在 / 该设备未绑定SIM卡 / 该SIM卡暂不支持续费，请联系平台 / 该SIM卡未设置充值金额，请联系平台 / SIM卡续费处理中，请稍后再试 / SIM卡充值订单金额异常，请联系平台

7. 充值记录

简要描述：

设备中心 → SIM卡缴费记录。只返回已支付的记录。

请求域名:

  • http://xx.com

请求路由:

POST/&route=plugin.yz-supply-under-sink-machine.frontend.sim.sim-card.records
POST/&route=plugin.yz-supply-home-water-machin.frontend.sim.sim-card.records

请求参数说明:

参数名 类型 是否必需 说明
page int 否 页码，默认1
page_size int 否 每页条数，默认15
sim_no string 否 SIM卡号，模糊搜索

返回示例:

正确时返回:

{
    "result": 1,
    "msg": "ok",
    "data": {
        "current_page": 1,
        "data": [
            {
                "id": 1,
                "sim_no": "89860862TEST00000701",
                "device_no": "860000000000701",
                "device_name": "SIM测试厨下1",
                "amount": "40.00",
                "pay_type_name": "余额",
                "days": 365,
                "paid_at": "2026-09-24 08:51:41",
                "status": 2,
                "status_text": "成功",
                "remark": ""
            }
        ],
        "first_page_url": "http://xx.com?page=1",
        "from": 1,
        "last_page": 1,
        "last_page_url": "http://xx.com?page=1",
        "next_page_url": null,
        "path": "http://xx.com",
        "per_page": 15,
        "prev_page_url": null,
        "to": 1,
        "total": 1
    }
}

返回参数说明:

同「4. 充值记录」。