生钛圈 API 文档
V2.14
|
日期 |
版本 |
说明 |
|
2022/5/17 |
V2.0 |
第一版 |
|
2022/6/20 |
V2.1 |
增加会员卡，设备相关接口 |
|
2022/6/30 |
V2.2 |
新增下单，查单，消费记录接口 |
|
2022/07/18 |
V2.3 |
新增会员卡远程停止灌装接口 |
|
2022/08/03 |
V2.4 |
会员卡开卡支持批量开卡 |
|
2022/08/15 |
V2.5 |
消费记录接口返回水量 |
|
2022/08/24 |
V2.6 |
增加 3.3.5 设备上线接口 |
|
2022/10/14 |
V2.7-v2.8 |
3.2.3 增加结束时间筛选 |
|
2023/04/18 |
V2.9 |
零钱打水场景说明，删除旧版设备详情，零钱打水接口 |
|
2023/04/23 |
V2.10 |
会员卡充值套餐补充说明 |
|
2023/04/25 |
V2.11 |
接口限流（单接口每分钟请求 100 次限制） |
|
2023/05/23 |
V2.12 |
充电桩下单接口，设备详情，设备列表接口支持充电桩设备 |
| 2023/08/02 | V2.13 | 简化下单流程 |
| 2023/09/21 | V2.14 | 查单返回数据补充退款金额字段 |
1. 文档简介
1.1. 特别声明
未得到本公司的书面许可，不得为任何目的、以任何形式或手段（包括但不限于机械的或电子的）复制或传播本文档的任何部分。对于本文档涉及的技术和产品，本公司拥有其专利
（或正在申请专利）、商标、版权或其它知识产权。除非得到本公司的书面许可协议，本文档不授予这些专利、商标、版权或其它知识产权的许可。
本文档因产品功能示例和描述的需要，所使用的任何人名、企业名和数据都是虚构的， 并仅限于本公司内部测试使用，不等于本公司有对任何第三方的承诺和宣传。
1.2. 阅读对象
贵公司的技术部门的开发、维护及管理人员，应具备以下基本知识：
-
-
- 了解HTTPS/HTTP 协议等内容。
- 了解信息安全的基本概念。
- 了解计算机至少一种编程语言。
-
1.3. 产品说明
黑皮钛后台接口均采用 http GET/POST 接口，返回值为JSON 格式。商家账户可以登录https://server.happy-ti.com/申请成为生钛圈开发者，申请之后会得到一个appid，appid 会在接口调用中使用，用于鉴权，商家账户只能通过接口查询本商家的信息。调用接口都会有返回值，返回值中error 状态如果为’0’， 则调用是成功的，如果不为 0，根据不同返回值查看是否参数有问题，或者其他问题。如有疑问，请联系相关工程师。
限流：每个商家账号，单个接口请求，每分钟不得超过 100 次（超过后不再返回数据）
2. 使用流程
- 准备阶段：
-
- 申请测试号等信息；
- 取得开发手册（本文档）等资料；
- 开发阶段：
-
- 根据提供的DEMO 结合开发文档快速熟悉对接接口；
- 根据本系统提供的接口，在自己的系统上进行开发，实现所需要的业务功能；
- 对自己系统的业务功能进行全面测试；
- 与测试环境进行联调。
- 生产使用：
-
- 使用系统提供的正式资料。
3. 接口列表
请优先查看第4，第5章节
3.1. 会员卡
3.1.1. 会员卡充值
cxszn注释：实体卡IC卡充值
接口地址：api.happy- ti.com:2028/addvalue?appid=2beea5cb3ce00296dba32e36b8a9dc3f&user=hptserverd emo&card=rm99991234&value=10&income=5&password=123456&trad_id=123
请求类型：multipart/form-data 请求方式：post
接口备注：1.该接口默认为自定义充值。2.通过线上营销模块拉取我方后台充值套 餐数据，填入type 与对应id 进行充值，注意区分type类型（常规套餐，时效套餐）。
调试工具：ApiPost
URI 参数说明：
|
参数名 |
示例值 |
参数类型 |
是否必填 |
参数描述 |
|
appid |
2beea5cb3ce00296 dba32e36b8a9dc3f |
Text |
是 |
暂无描述 |
|
user |
hptserverdemo |
Text |
是 |
商家账号（与其他接 |
|
card |
rm99991234 |
Text |
是 |
会员卡号 |
|
value |
10 |
Text |
是 |
充值金额 |
|
income |
5 |
Text |
是 |
实收现金金额 |
|
password |
123456 |
Text |
是 |
商家账号密码 |
|
trad_id |
123 |
Text |
是 |
可选，充值订单号 |
|
type |
addvalue |
Text |
否 |
不填写为自定义充值。可选择充值类型：addvalue（普通充值又称常规套餐充值）； policy（时效套餐充值） |
|
id |
Text |
否 |
套餐 id（传递 type 类型时，必传对应商品 id，通过 3.2.4 接口获取） |
返回成功参数说明：
|
参数名 |
示例值 |
参数类型 |
参数描述 |
|
error |
0 |
String |
错误响应 |
|
addvalue |
10 |
String |
充值金额 |
|
value |
43.15 |
String |
充值后卡内金额 |
|
number |
rm99991234 |
String |
充值卡号 |
返回成功示例：
{
"error": "0",
"addvalue": "10",
"value": "43.15",
"number": "rm99991234"
}
返回失败参数说明：
|
参数名 |
示例值 |
参数类型 |
参数描述 |
|
error |
no card |
String |
错误响应 |
返回失败示例：
{
"error": "no card"
}
3.1.2. 获取卡片消费记录
接口地址：api.happy- ti.com:2028/getconsume?appid=2beea5cb3ce00296dba32e36b8a9dc3f&user=hptserve rdemo&card=rm99991234
请求类型：multipart/form-data
请求方式：get
接口备注：暂无描述
调试工具：ApiPost
URI 参数说明：
|
参数名 |
示例值 |
参数类型 |
是否必填 |
参数描述 |
|
appid |
2beea5cb3ce00296 dba32e36b8a9dc3f |
Text |
是 |
暂无描述 |
|
user |
hptserverdemo |
Text |
是 |
暂无描述 |
|
card |
rm99991234 |
Text |
是 |
暂无描述 |
返回成功参数说明：
|
参数名 |
示例值 |
参数类型 |
参数描述 |
|
data |
Object |
返回数据 |
|
|
data.card_num |
rm99991234 |
String |
卡号 |
|
data.after_value |
0 |
String |
消费后卡内金额 |
|
data.saler |
hptserverdemo |
String |
商家账号 |
|
data.value |
0.10 |
String |
充值金额 |
|
data.location |
云 K |
String |
设备地址 |
|
data.time |
2022-05-11 10:49:18 |
String |
上传时间 |
|
data.device |
868626040703343 |
String |
设备编号 |
|
data.cost_value |
0.10 |
String |
实际扣款金额 |
|
error |
0 |
String |
错误响应 |
返回成功示例：
{
"data": [
{
"card_num": "rm99991234", "after_value": "0",
"saler": "hptserverdemo", "value": "0.10",
"location": "云 K",
"time": "2022-05-11 10:49:18",
"device": "868626040703343",
"cost_value": "0.10"
},
{
"card_num": "rm99991234", "after_value": "0",
"saler": "hptserverdemo", "value": "0.10",
"location": "云 K",
"time": "2022-05-11 10:49:18",
"device": "868626040703343",
"cost_value": "0.10"
}
],
"error": "0"
}
返回失败参数说明：
3.1.3. 获取卡片详情
接口地址：api.happy- ti.com:2028/cardinfo?appid=2beea5cb3ce00296dba32e36b8a9dc3f&user=hptserverde mo&card=rm99991234
请求类型：multipart/form-data 请求方式：get
接口备注：暂无描述 调试工具：ApiPost
URI 参数说明：
|
参数名 |
示例值 |
参数类型 |
是否必填 |
参数描述 |
|
appid |
2beea5cb3ce00296 dba32e36b8a9dc3f |
Text |
是 |
暂无描述 |
|
user |
hptserverdemo |
Text |
是 |
暂无描述 |
|
card |
rm99991234 |
Text |
是 |
暂无描述 |
返回成功参数说明：
|
参数名 |
示例值 |
参数类型 |
参数描述 |
|
data |
Object |
返回数据 |
|
|
data.status |
normal |
String |
会员卡状态normal（正常） lost（挂失）cancel已注销（不能使用） |
|
data.shopname |
860344045231884 |
String |
上次刷卡设备编号 |
|
data.saler |
hptserverdemo |
String |
商家账号 |
|
data.number |
rm99991234 |
String |
充值卡号 |
|
data.value |
43.149999237061 |
Number |
充值金额 |
|
data.last_day |
Object |
会员卡套餐到期时间 |
|
|
data.owner |
13252817449 |
String |
持有用户 |
|
data.card_policy |
Object |
会员卡套餐 id |
|
|
error |
0 |
String |
错误响应 |
返回成功示例：
{
"data": {
"status": "normal",
"shopname": "860344045231884",
"saler": "hptserverdemo", "number": "rm99991234", "value": 43.14999923706055,
"last_day": null,
"owner": "13252817449",
"card_policy": null
},
"error": "0"
}
3.1.4. 获取卡片充值记录
接口地址：api.happy- ti.com:2028/getaddvalue?appid=2beea5cb3ce00296dba32e36b8a9dc3f&user=hptserv erdemo&card=rm99991234
请求类型：multipart/form-data
请求方式：get
接口备注：暂无描述
调试工具：ApiPost
URI 参数说明：
|
参数名 |
示例值 |
参数类型 |
是否必填 |
参数描述 |
|
appid |
2beea5cb3ce00296 dba32e36b8a9dc3f |
Text |
是 |
暂无描述 |
|
user |
hptserverdemo |
Text |
是 |
暂无描述 |
|
card |
rm99991234 |
Text |
是 |
暂无描述 |
返回成功参数说明：
|
参数名 |
示例值 |
参数类型 |
参数描述 |
|
data |
Object |
返回数据 |
|
|
data.card_num |
rm99991234 |
String |
卡号 |
|
data.saler |
hptserverdemo |
String |
商家账号 |
|
data.value |
5 |
Number |
充值金额 |
|
data.operater |
hptserverdemo |
String |
操作人 |
|
data.time |
2022-05-11 10:46:48 |
String |
充值时间 |
|
data.value_afterdiscount |
10 |
Number |
实际到账金额 |
|
error |
0 |
String |
错误响应 |
返回成功示例：
{
"data": [
{
"card_num": "rm99991234", "saler": "hptserverdemo", "value": 5,
"operater": "hptserverdemo", "time": "2022-05-11 10:46:48",
"value_afterdiscount": 10
}
],
"error": "0"
}
3.1.5. 开卡接口
接口地址：api.happy- ti.com:2028/card/opencards?saler=hptserverdemo&appid=2beea5cb3ce00296dba32e3 6b8a9dc3f&deviceId=&number=10400040002&userid=hptserverdemo
请求类型：multipart/form-data
请求方式：get
接口备注：号段持有者可以为其他任意商家进行开卡 支持单张开卡和批量开卡两种模式
调试工具：ApiPost
URI 参数说明：
|
参数名 |
示例值 |
参数类型 |
是否必填 |
参数描述 |
|
saler |
hptserverdemo |
Text |
是 |
商家账号 |
|
appid |
2beea5cb3ce00296 dba32e36b8a9dc3f |
Text |
是 |
开发者账号的 appid |
|
deviceId |
Text |
否 |
设备编号 |
|
|
number |
10400040002 |
Text |
是 |
会员卡号 |
|
userid |
hptserverdemo |
Text |
是 |
开卡商家（所开会员卡归属商家） |
|
totalNumber |
3 |
Number |
否 |
传入后以 number 为起始卡号，进行批量开卡，一次最多开200 张 |
单张开卡，批量开卡返回成功示例：
{
"code": 0,
"msg": "操作成功",
"data": []
}
单张开卡返回失败示例：
{
"code": "-1",
"msg": "此卡已存在",
"data": []
}
批量开卡返回失败示例：data 中包含所有开卡异常数据，不包括开卡成功数据！
{
"code": "-1",
"msg": "开卡失败", "data": [
{
"number": 10400040002,
"err": "此卡已存在"
},
{
"number": 10400040003,
"err": "此卡已存在"
}
]
}
3.1.6. 获取会员卡列表
接口地址：api.happy- ti.com:2028/card/getlist?saler=hptserverdemo&appid=2beea5cb3ce00296dba32e36b8 a9dc3f&page=1
请求类型：multipart/form-data
请求方式：get
接口备注：获取会员卡信息,一页最多20 条数据
调试工具：ApiPost
URI 参数说明：
|
参数名 |
示例值 |
参数类型 |
是否必填 |
参数描述 |
|
saler |
hptserverdemo |
Text |
是 |
商家账号 |
|
appid |
2beea5cb3ce00296 dba32e36b8a9dc3f |
Text |
是 |
开发者账号的 appid |
|
page |
1 |
Text |
是 |
分页页码，数字类型，默认为第一页 |
返回成功参数说明：
|
参数名 |
示例值 |
参数类型 |
参数描述 |
|
code |
0 |
Number |
状态码 |
|
msg |
操作成功 |
String |
返回文字描述 |
|
data |
Object |
返回数据 |
|
|
data.index |
1 |
String |
会员卡序号 |
|
data.number |
rm99991234 |
String |
会员卡卡号 |
|
data.value |
30 |
String |
会员卡余额（赠送部分） |
|
data.cash |
25.00 |
String |
会员卡余额（实收部分） |
|
data.status |
normal |
String |
会员卡状态normal（正常） lost（挂失）cancel已注销（不能使用） |
|
data.shopname |
Object |
上次消费的设备编号 |
|
|
data.create_time |
2022-05-17 16:19:52 |
String |
创建时间 |
|
data.card_policy |
5239 |
String |
会员卡套餐 id（不再使用） |
|
data.last_day |
2022-06-28 23:59:59 |
String |
会员卡套餐到期时间 （不再使用） |
|
data.name |
年卡 |
String |
主标题 |
|
data.policy_data |
Object |
会员卡套餐信息 |
|
|
data.policy_data.id |
320 |
String |
套餐 id |
|
data.policy_data.number |
rm99991234 |
String |
充值卡号 |
|
data.policy_data.policy_id |
5239 |
String |
套餐 ID |
|
data.policy_data.name |
年卡 |
String |
主标题 |
|
data.policy_data.type |
define |
String |
充值类型：addvalue （普通充值）； policy（套餐充值） |
|
|
|||
|
data.policy_data.value |
10 |
Number |
充值金额 |
|
data.policy_data.period |
31 |
String |
赠送周期 |
|
data.policy_data.balance |
10.00 |
String |
可用金额 |
|
data.policy_data.saler |
13252817441 |
String |
商家账号 |
|
data.policy_data.expire_time |
2022-06-28 |
String |
到期时间 |
|
data.policy_data.silent_time |
2021-07-08 11:35:51 |
String |
沉默期时间 |
|
data.policy_data.start_time |
2021-05-28 11:38:25 |
String |
开始时间 |
|
data.policy_data.last_consume_time |
2021-08-10 |
String |
上次消费时间 |
|
data.policy_data.create_time |
2021-05-28 11:35:51 |
String |
创建时间 |
|
data.policy_data.active_mode |
0 |
String |
|
|
data.policy_data.remark |
Object |
备注 |
|
|
data.policy_data.extend_data |
Object |
套餐扩展数据 |
|
|
data.policy_data.extend_data.next_time |
已截至 |
String |
下次赠送时间 |
|
data.policy_data.extend_data.total_amount |
已赠完 |
String |
剩余赠送金额 |
|
data.policy_data.next_time |
已截至 |
String |
暂无描述 |
|
data.policy_data.total_amount |
已赠完 |
String |
暂无描述 |
|
data.policy_data.renew |
0 |
Number |
是否支持续费 0 代表 不支持 1 代表支持 |
返回成功示例：
{
"code": 0,
"msg": "操作成功", "data": [
{
"index": "1",
"number": "rm99991234", "value": "30",
"cash": "25.00",
"status": "normal", "shopname": null,
"create_time": "2022-05-17 16:19:52",
"card_policy": "5239",
"last_day": "2022-06-28 23:59:59",
"name": "年卡", "policy_data": [
{
"id": "320",
"number": "rm99991234", "policy_id": "5239",
"name": "年卡",
"type": "define", "value": 10,
"period": "31",
"balance": "10.00",
"saler": "13252817441",
"expire_time": "2022-06-28",
"silent_time": "2021-07-08 11:35:51",
"start_time": "2021-05-28 11:38:25",
"last_consume_time": "2021-08-10",
"create_time": "2021-05-28 11:35:51",
"active_mode": "0", "remark": null,
"extend_data": {
"next_time": "已截至", "total_amount": "已赠完"
},
"next_time": "已截至", "total_amount": "已赠完", "renew": 0
}
]
},
{
"index": "2",
"number": "10400040001",
"value": "0",
"cash": "0.00",
"status": "normal",
"shopname": "",
"create_time": "2022-06-15 16:26:35", "card_policy": "",
"last_day": "",
"name": "",
"policy_data": ""
},
{
"index": "3",
"number": "10400040002",
"value": "0",
"cash": "0.00",
"status": "normal",
"shopname": "",
"create_time": "2022-06-16 11:44:02",
"card_policy": "",
"last_day": "",
"name": "",
"policy_data": ""
}
]
}
3.1.7. 获取会员卡号段
接口地址：api.happy- ti.com:2028/card/getsection?saler=hptserverdemo&appid=2beea5cb3ce00296dba32e3 6b8a9dc3f
请求类型：multipart/form-data
请求方式：get
接口备注：获取当前开发者账号所持有的号段信息（用于开卡）
调试工具：ApiPost
URI 参数说明：
|
参数名 |
示例值 |
参数类型 |
是否必填 |
参数描述 |
|
saler |
hptserverdemo |
Text |
是 |
商家账号 |
|
appid |
2beea5cb3ce00296 dba32e36b8a9dc3f |
Text |
是 |
开发者账号的 appid |
返回成功参数说明：
|
参数名 |
示例值 |
参数类型 |
参数描述 |
|
code |
0 |
Number |
状态码 |
|
msg |
操作成功 |
String |
返回文字描述 |
|
data |
Object |
返回数据 |
|
|
data.card_start |
10400040001 |
String |
号段起始 |
|
data.card_end |
10400040100 |
String |
号段结束 |
返回成功示例：
{
"code": 0,
"msg": "操作成功", "data": [
{
"card_start": "10400040001",
"card_end": "10400040100"
}
]
}
3.1.8. 会员卡挂失，解除挂失接口
接口地址：api.happy- ti.com:2028/card/lossreport?saler=hptserverdemo&appid=2beea5cb3ce00296dba32e3 6b8a9dc3f&card=rm99991234&action=
请求类型：multipart/form-data
请求方式：get
接口备注：对开发者账号下的会员卡进行挂失和解除挂失操作
调试工具：ApiPost
URI 参数说明：
|
参数名 |
示例值 |
参数类型 |
是否必填 |
参数描述 |
|
saler |
hptserverdemo |
Text |
是 |
商家账号 |
|
appid |
2beea5cb3ce00296 dba32e36b8a9dc3f |
Text |
是 |
开发者账号的 appid |
|
card |
rm99991234 |
Text |
是 |
会员卡号 |
|
action |
normal |
Text |
是 |
normal 为解除挂失 lost 为挂失 |
返回成功参数说明：
|
参数名 |
示例值 |
参数类型 |
参数描述 |
|
code |
0 |
Number |
状态码 |
|
msg |
操作成功 |
String |
返回文字描述 |
|
data |
{} |
Object |
返回数据 |
返回成功示例：
{
"code": 0,
"msg": "操作成功",
"data": []
}
返回失败参数说明：
|
参数名 |
示例值 |
参数类型 |
参数描述 |
|
code |
017 |
String |
状态码 |
|
msg |
参数丢失 |
String |
返回文字描述 |
|
data |
{} |
Object |
返回数据 |
返回失败示例：
{
"code": "017",
"msg": "参数丢失",
"data": []
}
3.1.9. 无卡消费设备通知接口(远程刷卡)
接口地址：api.happy- ti.com:2028/notify?appid=2beea5cb3ce00296dba32e36b8a9dc3f&user=hptserverdemo
&card=rm99991234&value=10&income=5&password=817441&device=8603440452318 84
请求类型：multipart/form-data
请求方式：post
接口备注：暂无描述
调试工具：ApiPost
URI 参数说明：
|
参数名 |
示例值 |
参数类型 |
是否必填 |
参数描述 |
|
appid |
2beea5cb3ce00296 dba32e36b8a9dc3f |
Text |
是 |
开发者账号的 appid |
|
user |
hptserverdemo |
Text |
是 |
商家账号 |
|
card |
rm99991234 |
Text |
是 |
会员卡号 |
|
password |
817441 |
Text |
是 |
商家账号密码 |
|
device |
860344045231884 |
Text |
是 |
设备编号 |
返回成功示例：
{
"data": "通知成功",
"error": "0"
}
返回失败参数说明： 返回失败示例：
{
"data": "设备不在线！",
"error": "0"
}
3.1.10. 会员卡远程停止灌装接口
接口地址：api.happy- ti.com:2028/card/stop?saler=hptserverdemo&appid=2beea5cb3ce00296dba32e36b8a 9dc3f&deviceId=860344045231884&number=rm99991234&ch=1
请求类型：multipart/form-data
请求方式：get
接口作用：调用成功后，会直接将设备上已经刷过去的会员卡金额消掉
接口备注：会员卡远程停止灌装接口，成功时返回status为1。 返回失败时一共有两种结构，一种为status 不为0，另一种为code msg data 模式。
调试工具：ApiPost
URI 参数说明：
|
参数名 |
示例值 |
参数类型 |
是否必填 |
参数描述 |
|
saler |
hptserverdemo |
Text |
是 |
商家账号 |
|
appid |
2beea5cb3ce00296 dba32e36b8a9dc3f |
Text |
是 |
开发者账号的 appid |
|
deviceId |
860344045231884 |
Text |
是 |
设备编号 |
|
number |
rm99991234 |
Text |
是 |
会员卡号 |
|
ch |
1 |
Text |
否 |
设备通道非必填，多路设备可填 0，1， 2，3 对应 1，2，3， 4 路 |
返回成功参数说明：
|
参数名 |
示例值 |
参数类型 |
参数描述 |
|
message |
通知成功！ |
String |
返回信息描述 |
|
status |
1 |
String |
1 代表成功 0 代表错误 |
返回成功示例：
{
"message": "通知成功！",
"status": "1"
}
返回失败参数说明：
|
参数名 |
示例值 |
参数类型 |
参数描述 |
|
code |
024 |
String |
状态码 |
|
msg |
会员卡数据为空 |
String |
返回文字描述 |
|
data |
{} |
Object |
返回数据 |
返回失败示例：
{
"code": "024",
"msg": "会员卡数据为空",
"data": []
}
3.2. 线上营销模块
3.2.1. 零钱下单接口
接口地址：api.happy- ti.com:2028/trade/qrcreate?saler=hptserverdemo&appid=2beea5cb3ce00296dba32e3 6b8a9dc3f&deviceId=860344045231880&value=1&userid=1&ch=&location=%E6%B5% 8B%E8%AF%95&salerOrderId=123
接口地址：api.happy- ti.com:2028/trade/v2/qrcreate?saler=hptserverdemo&appid=2beea5cb3ce00296dba32e36b8a9dc3f&deviceId=860344045231880&value=1&userid=1&ch=&location=%E6%B5%8B%E8%AF%95&salerOrderId=123
请求类型：multipart/form-data
请求方式：get
接口备注：应用在零钱支付场景，用户完成支付调用此接口，我方系统会通知设备 相应金额。之后请您通过调用查单接口获取订单状态，若10 分钟内订单状态没有 变成finished，则代表本次下单未成功通知到设备，需要您完成退款等流程。
调试工具：ApiPost
URI 参数说明：
|
参数名 |
示例值 |
参数类型 |
是否必填 |
参数描述 |
|
saler |
hptserverdemo |
Text |
是 |
商家账号 |
|
appid |
2beea5cb3ce00296 dba32e36b8a9dc3f |
Text |
是 |
开发者账号的 appid |
|
deviceId |
860344045231880 |
Text |
是 |
设备编号 |
|
value |
1 |
Text |
是 |
支付金额(元，金额最低单位为角不支持分) |
|
userid |
1 |
Text |
是 |
用户唯一标识 |
|
ch |
0 |
Text |
否 |
设备通道 0,1,2,3 对 应 1,2,3,4 路出水 口， 注意：当设备型号为wind_p系列和 HD_cloud_a系列时传1，2对应1,2 路，不传则都显示金额） |
|
location |
测试 |
Text |
是 |
设备地址 |
|
salerOrderId |
123 |
Text |
是 |
商户单号（后续查单使用，不要重复，需要唯一） |
返回成功参数说明：
|
参数名 |
示例值 |
参数类型 |
参数描述 |
|
code |
0 |
String |
状态码 |
|
msg |
操作成功 |
String |
返回文字描述 |
|
data |
{} |
Object |
返回数据 |
返回成功示例：
{
"code": "0",
"msg": "操作成功",
"data": []
}
返回失败参数说明：
|
参数名 |
示例值 |
参数类型 |
参数描述 |
|
code |
069 |
String |
状态码 |
|
msg |
没有查找到该设备 |
String |
返回文字描述 |
|
data |
{} |
Object |
返回数据 |
返回失败示例：
{
"code": "069",
"msg": "没有查找到该设备",
"data": []
}
3.2.2. 零钱查单接口
接口地址：api.happy- ti.com:2028/trade/query?saler=hptserverdemo&appid=2beea5cb3ce00296dba32e36b8 a9dc3f&deviceId=860344045231880&salerOrderId=123
请求类型：multipart/form-data
请求方式：get
接口备注：根据传入SalerOrderId 查询下单数据是否已经成功通知到设备
调试工具：ApiPost
URI 参数说明：
|
参数名 |
示例值 |
参数类型 |
是否必填 |
参数描述 |
|
saler |
hptserverdemo |
Text |
是 |
商家账号 |
|
appid |
2beea5cb3ce00296 dba32e36b8a9dc3f |
Text |
是 |
开发者账号的 appid |
|
deviceId |
860344045231880 |
Text |
是 |
设备编号 |
|
salerOrderId |
123 |
Text |
是 |
商户单号 |
返回成功参数说明：
|
参数名 |
示例值 |
参数类型 |
参数描述 |
|
code |
0 |
Number |
状态码 |
|
msg |
操作成功 |
String |
返回文字描述 |
|
data |
Object |
返回数据 |
|
|
data.key_id |
5 |
String |
ID 号 |
|
data.card_num |
860344045231880 |
String |
设备号 |
|
data.alipay_number |
qr404523188030145803591c1 |
String |
黑皮钛系统单号 |
|
data.operater |
1 |
String |
操作人 |
|
data.saler |
hptserverdemo |
String |
商家账号 |
|
data.value |
1 |
String |
支付金额 |
|
data.value_afterdiscount |
1 |
String |
实际金额 |
|
data.card_aftervalue |
0 |
String |
支付后余额（会员卡充值场景下使用） |
|
data.status |
success |
String |
success 下单成功， 未通知到设备； finished 已通知到设备 |
|
data.device |
860344045231880 |
String |
设备编号 |
|
data.location |
测试 |
String |
设备地址 |
|
data.type |
qrcode |
String |
充值类型qrcode 零钱支付 |
|
data.remark |
123 |
String |
商户单号 |
|
data.time |
2022-06-30 14:58:03 |
String |
下单时间 |
| data.balance | 0.5 | string | 订单未消费金额（适用于用户进行退款，订单变为finished状态10分钟后，可查看此字段，null不需要退款，其它数值则为应退金额） |
返回成功示例：
{
"code": 0,
"msg": "操作成功", "data": {
"key_id": "5",
"card_num": "860344045231880",
"alipay_number": "qr404523188030145803591c1",
"operater": "1",
"saler": "hptserverdemo",
"value": "1",
"value_afterdiscount": "1",
"card_aftervalue": "0",
"status": "success",
"device": "860344045231880",
"location": "测试",
"type": "qrcode",
"remark": "123",
"time": "2022-06-30 14:58:03",
"balance":"0.5"
}
}
返回失败示例：
{
"code": "022",
"msg": "数据不存在",
"data": []
}
3.2.3. 获取消费记录列表
接口地址：api.happy- ti.com:2028/record/getlist?saler=hptserverdemo&appid=2beea5cb3ce00296dba32e36 b8a9dc3f&page=1&beginTime=2022-07-05 14:25:43&endTime=2022-07-29 14:25:43
请求类型：multipart/form-data
请求方式：get
接口备注：获取商家下所有消费记录，一页20 条数据，可传入时间进行拉取
调试工具：ApiPost
URI 参数说明：
|
参数名 |
示例值 |
参数类型 |
是否必填 |
参数描述 |
|
saler |
hptserverdemo |
Text |
是 |
商家账号 |
|
appid |
2beea5cb3ce00296 dba32e36b8a9dc3f |
Text |
是 |
开发者账号的 appid |
|
page |
1 |
Text |
否 |
分页页码，数字类型，默认为第一页 |
|
beginTime |
Y-m-d H:i:s |
Text |
否 |
起始时间 |
|
endTime |
Y-m-d H:i:s |
Text |
否 |
结束时间 |
返回成功参数说明：
|
参数名 |
示例值 |
参数类型 |
参数描述 |
|
code |
0 |
Number |
状态码 |
|
msg |
操作成功 |
String |
返回文字描述 |
|
data |
Object |
返回数据 |
|
|
data.key_id |
24 |
String |
ID 号 |
|
data.card_num |
10400032001 |
String |
卡号 |
|
data.shop_num |
864917055633721 |
String |
设备号 |
|
data.value |
0.41 |
String |
充值金额 |
|
data.path |
charger |
String |
qrcode 零钱支付 |
|
data.time |
2022-06-20 14:41:07 |
String |
上传时间 |
|
data.pay_id |
charge4aa30b2c4173f8105-1 |
String |
订单 ID |
|
data.location |
测试 |
String |
设备地址 |
|
data.after_value |
29.39 |
String |
消费后卡内金额 |
|
data.cost_value |
0.41 |
String |
实际扣款金额 |
|
data.water1 |
15 |
String |
第一路出水量（升） |
|
data.water2 |
0 |
String |
第二路出水量（升） |
返回成功示例：
{
"code": 0,
"msg": "操作成功",
"data": [
{
"key_id": "24",
"card_num": "10400032001",
"shop_num": "864917055633721",
"value": "0.41",
"path": "charger",
"time": "2022-06-20 14:41:07",
"pay_id": "charge4aa30b2c4173f8105-1", "location": "测试",
"after_value": "29.39",
"cost_value": "0.41",
"water1": "15",
"water2": "0",
}
]
}
返回失败参数说明：
|
参数名 |
示例值 |
参数类型 |
参数描述 |
|
code |
025 |
String |
状态码 |
|
msg |
数据错误 |
String |
返回文字描述 |
|
data |
{} |
Object |
返回数据 |
返回失败示例：
{
"code": "025",
"msg": "数据错误",
"data": []
}
3.2.4. 获取充值套餐与时效套餐列表
接口地址：api.happy- ti.com:2028/getproducts?appid=2beea5cb3ce00296dba32e36b8a9dc3f&user=hptserve rdemo
请求类型：multipart/form-data
请求方式：get
接口备注：policy属性内商品对应充值类型为policyrecharge属性内商品对应充值类型为addvalue
调试工具：ApiPost
URI 参数说明：
|
参数名 |
示例值 |
参数类型 |
是否必填 |
参数描述 |
|
appid |
2beea5cb3ce00296 dba32e36b8a9dc3f |
Text |
是 |
暂无描述 |
|
user |
hptserverdemo |
Text |
是 |
暂无描述 |
返回成功参数说明：
|
参数名 |
示例值 |
参数类型 |
参数描述 |
|
policy |
Object |
时效套餐 |
|
|
policy.status |
1 |
Number |
套餐状态 1 商家 2 下架 |
|
policy.index |
5239 |
Number |
时效套餐 ID |
|
policy.sub_name |
日卡 |
String |
副标题 |
|
policy.name |
日卡 |
String |
主标题 |
|
policy.pay_type |
2 |
Number |
支付渠道 1：线下； 2：全部；3：线上 |
|
policy.price |
10 |
Number |
价格 |
|
policy.default_days |
15 |
Number |
有效天数 |
|
policy.period |
0 |
Number |
赠送周期 |
|
policy.limit_times |
-1 |
Number |
限制购买次数 |
|
policy.marking_price |
15 |
Number |
划线价格 |
|
policy.type |
day |
String |
充值类型：addvalue （普通充值）；policy（套餐充值） |
|
|
|||
|
policy.silent_day |
10 |
Number |
沉默期 |
|
policy.day_value |
1 |
Number |
每次赠送金额 |
|
recharge |
Object |
充值套餐 |
|
|
recharge.status |
1 |
Number |
状态 1 ：上架 |
|
recharge.index |
92795 |
Number |
套餐 ID |
|
recharge.name |
测试 |
String |
套餐名称 |
|
recharge.price |
0.1 |
Number |
套餐购买价格 |
|
recharge.value |
1 |
String |
到账金额 |
|
recharge.marking_price |
1 |
Number |
划线价格 |
|
recharge.type |
recharge |
String |
充值类型（暂未使用） |
|
recharge.limit_times |
-1 |
Number |
限制充值次数-1 代 表不限次数 1 代表只能购买一次 |
|
error |
0 |
String |
错误响应 |
返回成功示例：
{
"policy": [
{
"status": 1,
"index": 5239, "sub_name": "日卡",
"name": "日卡", "pay_type": 2,
"price": 10,
"default_days": 15,
"period": 0,
"limit_times": -1,
"marking_price": 15,
"type": "day", "silent_day": 10,
"day_value": 1
},
{
"status": 1,
"index": 6045, "sub_name": "每月喝水",
"name": "月卡线上 A", "pay_type": 2,
"price": 10,
"default_days": 30,
"period": 0,
"limit_times": -1,
"marking_price": 30, "type": "month", "silent_day": 10,
"day_value": 31
},
{
"status": 1,
"index": 7281,
"sub_name": "一年喝水无忧", "name": "年卡",
"pay_type": 2,
"price": 100.1,
"default_days": 365,
"period": 31,
"limit_times": -1,
"marking_price": 200, "type": "define",
"silent_day": 30,
"day_value": 50
},
{
"status": 1,
"index": 8120,
"sub_name": "2",
"name": "1",
"pay_type": 1,
"price": 3,
"default_days": 5,
"period": 5,
"limit_times": -1,
"marking_price": 4, "type": "define", "silent_day": 1,
"day_value": 1
}
],
"recharge": [
{
"status": 1,
"index": 92795, "name": "测试",
"price": 0.1,
"value": "1",
"marking_price": 1, "type": "recharge", "limit_times": -1
},
{
"status": 1,
"index": 94660,
"name": "1",
"price": 12,
"value": "10",
"marking_price": 0, "type": "recharge", "limit_times": -1
},
{
"status": 1,
"index": 94697,
"name": "3",
"price": 3,
"value": "3",
"marking_price": 0, "type": "recharge", "limit_times": -1
}
],
"error": "0"
}
3.3. 设备模块
3.3.1. 添加设备接口
请求类型：multipart/form-data
请求方式：get
接口备注：暂无描述
调试工具：ApiPost
URI 参数说明：
|
参数名 |
示例值 |
参数类型 |
是否必填 |
参数描述 |
|
appid |
2beea5cb3ce00296 dba32e36b8a9dc3f |
Text |
是 |
商家账号对应appid |
|
saler |
hptserverdemo |
Text |
是 |
商家账号 |
|
deviceId |
860344045231887 |
Text |
是 |
设备编号 |
|
location |
123123123123 |
Text |
是 |
设备地址 |
|
type |
shop_happyfu |
Text |
是 |
设备类型一共四种shop 售水机； shop_liquid 售液机；shop_happyfu 嗨皮付shop_water 水控； |
返回成功参数说明：
|
参数名 |
示例值 |
参数类型 |
参数描述 |
|
code |
0 |
Number |
状态码 |
|
msg |
操作成功 |
String |
返回文字描述 |
|
data |
{} |
Object |
返回数据 |
返回成功示例：
{
"code": 0,
"msg": "操作成功",
"data": []
}
返回失败参数说明：
|
参数名 |
示例值 |
参数类型 |
参数描述 |
|
code |
-1 |
String |
状态码 |
|
msg |
设备已被其他嗨皮付用户绑定 |
String |
返回文字描述 |
|
data |
{} |
Object |
返回数据 |
返回失败示例：
{
"code": "-1",
"msg": "设备已被其他嗨皮付用户绑定", "data": []
}
3.3.2. 删除设备
接口地址：api.happy- ti.com:2028/deldevice?appid=2beea5cb3ce00296dba32e36b8a9dc3f&saler=hptserverd emo&deviceId=8603440452318877
请求类型：multipart/form-data
请求方式：get
接口备注：暂无描述
调试工具：ApiPost
URI 参数说明：
|
参数名 |
示例值 |
参数类型 |
是否必填 |
参数描述 |
|
appid |
2beea5cb3ce00296 dba32e36b8a9dc3f |
Text |
是 |
开发者账号的 appid |
|
saler |
hptserverdemo |
Text |
是 |
商家账号 |
| deviceId | 是 | 设备编号 |
返回成功示例：
{
"code": 0,
"msg": "操作成功",
"data": []
}
返回失败示例：
{
"code": "-1",
"msg": "设备不存在",
"data": []
}
3.3.3. 获取设备列表接口
接口地址：api.happy- ti.com:2028/getdevicelist?appid=2beea5cb3ce00296dba32e36b8a9dc3f&saler=hptserv erdemo&type=shop_happyfu
请求类型：multipart/form-data
请求方式：get
接口备注：暂无描述
调试工具：ApiPost
URI 参数说明：
|
参数名 |
示例值 |
参数类型 |
是否必填 |
参数描述 |
|
appid |
2beea5cb3ce00296 dba32e36b8a9dc3f |
Text |
是 |
开发者账号的 appid |
|
saler |
hptserverdemo |
Text |
是 |
商家账号 |
|
type |
shop_happyfu |
Text |
是 |
设备类型一共四种shop 售水机； shop_liquid 售液机；shop_happyfu 嗨皮付shop_water 水控； |
|
page |
1 |
Text |
否 |
分页，一页最多 20 条数据 |
返回成功参数说明：
|
参数名 |
示例值 |
参数类型 |
参数描述 |
|
code |
0 |
Number |
状态码 |
|
msg |
操作成功 |
String |
返回文字描述 |
|
data |
Object |
返回数据 |
|
|
data.id |
860344045231887 |
String |
设备ID |
|
data.location |
北京测试 |
String |
设备地址 |
|
data.water_time |
1 |
String |
一元钱脉冲数（请传入"1"或"2"） |
|
data.price_time |
4 |
String |
脉冲宽度（毫秒） |
|
data.port2_pricetime |
5 |
Number |
一个脉冲对应电磁阀打开时长(秒) |
|
data.create_time |
2022-03-25 |
String |
创建时间 |
返回成功示例：
{
"code": 0,
"msg": "操作成功", "data": [
{
"id": "860344045231887",
"location": "北京测试",
"water_time": "1",
"price_time": "4",
"port2_pricetime": 5,
"create_time": "2022-03-25"
},
{
"id": "864917055581029",
"location": "投币器",
"water_time": "2",
"price_time": "200",
"port2_pricetime": 6,
"create_time": "2022-02-21"
}
]
}
3.3.4. 获取设备详情（新版）
接口地址：api.happy- ti.com:2028/device/getdetail?appid=2beea5cb3ce00296dba32e36b8a9dc3f&saler=hpt serverdemo&deviceId=860344045231887
请求类型：multipart/form-data
请求方式：get
接口备注：该接口为设备详情接口，提供更加强大数据支持，同时旧版已不再维护。
调试工具：ApiPost
URI 参数说明：
|
参数名 |
示例值 |
参数类型 |
是否必填 |
参数描述 |
|
appid |
2beea5cb3ce00296 dba32e36b8a9dc3f |
Text |
是 |
开发者账号的 appid |
|
saler |
hptserverdemo |
Text |
是 |
商家账号 |
|
deviceId |
860344045231887 |
Text |
是 |
设备编号 |
返回成功参数说明：
|
参数名 |
示例值 |
参数类型 |
参数描述 |
|
code |
0 |
Number |
状态码 |
|
msg |
操作成功 |
String |
返回文字描述 |
|
data |
Object |
返回数据 |
| data.id | 860344045231887 | String | 设备编号 |
| data.saler | hptserverdemo | String | 商家账号 |
| data.lastconnect | Object | 上次连接时间 | |
| data.day_limit | 999 | String | 单日消费限额 |
| data.flow_para | 500 | String | 流量计参数 1 |
| data.location | 123123123123 | String | 设备地址 |
| data.status | normal | Object | 设备状态（英文） |
| data.status_cn | 离线 | String | 设备状态（中文） |
| data.pay_status | offline | String | 设备支付状态:empty(水箱空);offline(离 线);online(在线)
注：无需使用
|
| data.version | Object | 设备版本 | |
| data.limit | 9 | String | 单次消费限额（第一路） |
| data.limit2 | 9 | String | 单次消费限额（第二 路） |
| data.tds | 0 | String | TDS 值 |
| data.signal | -20 | String | 信号值（越大越强， 30为上限） |
| data.price_time | 100 | String | 脉冲宽度（毫秒） |
| data.price_1 | 20 | String | 第一路水价（元） |
| data.water_1 | 75 | String | 第一路出水量（升） |
| data.price_2 | 20 | String | 第二路水价（元） |
| data.water_2 | 75 | String | 第二路出水量（升） |
| data.port_1_price | 0.3 | String | 第一路每升水价格（为校准价格，单位元） |
| data.port_2_price | 0.3 | String | 第二路每升水价格（不支持第二路则无视） |
| data.create_time | 2022-05-10 | String | 创建时间 |
| data.extra | Object | 设备扩展数据 |
返回成功示例：
{"code":0,
"msg":"操作成功",
"data":{
"id":"860344045231887",
"saler":"13252817441",
"lastconnect":null,
"day_limit":"999",
"flow_para":"500",
"location":"123123123123",
"status":null,
"status_cn":"离线",
"pay_status":"offline",
"version":null,
"limit":"9",
"tds":"0",
"signal":"-20",
"price_time":"100",
"price_1":"20",
"water_1":"75",
"price_2":"20",
"water_2":"75",
"create_time":"2022-05-10",
"port_1_price":"0.3",
"port_2_price":"0.3",
"extra":{
"support_dual_port":"0"//1代表支持双出水0代表不支持
}
}
}
返回失败参数说明：
|
参数名 |
示例值 |
参数类型 |
参数描述 |
|
code |
-1 |
String |
状态码 |
|
msg |
没有查找到该设备 |
String |
返回文字描述 |
|
data |
{} |
Object |
返回数据 |
返回失败示例：
{
"code": "069",
"msg": "没有查找到该设备",
"data": []
}
3.3.5. 设备通知上线（设备版本>=7.5）已废弃
注意：此接口已废弃
接口地址：api.happy- ti.com:2028/device/notify?appid=2beea5cb3ce00296dba32e36b8a9dc3f&saler=hptser verdemo&deviceId=860344045231887
请求类型：multipart/form-data
请求方式：get
接口备注：
1.该接口通知版本号大于等于7.5 的设备上线（仅在下单前进行调用， 来监测设备是否在线，避免用户支付后由于设备断网造成无法取水的情况），调 用后3s，调用3.3.4 接口获取设备支付状态（未上线则继续调用）2.低版本设备无需调用
调试工具：ApiPost
URI 参数说明：
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
返回成功参数说明：
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
返回成功示例：
{
"code": 0,
"msg": "操作成功",
"data": {}
}
返回失败参数说明：
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
返回失败示例：
{
"code": "069",
"msg": "没有查找到该设备",
"data": []
}
3.3.6(3.3.7).修改售水机售液机参数接口
接口地址：api.happy- ti.com:2028/device/editshopparams?saler=hptserverdemo&appid=2beea5cb3ce00296 dba32e36b8a9dc3f&deviceId=868626040703343&location=3&light_on_time=00:00:00 &light_off_time=17:15:06&O3_on_time=10&O3_off_time=30&temp_low=10&temp_hi gh=30&day_limit=100&limit=10&temp_alert=10
请求类型：multipart/form-data 请求方式：get
接口备注：暂无描述 调试工具：ApiPost
URI 参数说明：
|
参数名 |
示例值 |
参数类型 |
是否必填 |
参数描述 |
|
saler |
hptserverdemo |
Text |
是 |
商家账号 |
|
appid |
2beea5cb3ce00296 dba32e36b8a9dc3f |
Text |
是 |
开发者账号的 appid |
|
deviceId |
868626040703343 |
Text |
是 |
设备编号 |
|
location |
3 |
Text |
是 |
设备地址 |
|
light_on_time |
00:00:00 |
DateTime |
是 |
灯箱开启时间 |
|
light_off_time |
17:15:06 |
DateTime |
是 |
灯箱关闭时间 |
|
O3_on_time |
10 |
Number |
是 |
臭氧启动时长(秒) |
|
O3_off_time |
30 |
Number |
是 |
臭氧启动周期(秒) |
|
temp_low |
10 |
Number |
是 |
温控启动温度(度) |
|
temp_high |
30 |
Number |
是 |
温控关闭温度(度) |
|
day_limit |
100 |
Number |
是 |
单日消费限额(元) |
|
limit |
10 |
Number |
是 |
单次消费限额(元) |
|
temp_alert |
10 |
Number |
是 |
报警温度 |
请求体参数说明：
|
参数名 |
示例值 |
参数类型 |
是否必填 |
参数描述 |
|
location |
地址 |
Text |
是 |
暂无描述 |
返回成功示例：
{
"code": "0",
"msg": "操作成功",
"data": []
}
返回失败参数说明：
|
参数名 |
示例值 |
参数类型 |
参数描述 |
|
code |
1009 |
String |
状态码 |
|
msg |
温控关闭温度应高于启动温度！ |
String |
返回文字描述 |
|
data |
{} |
Object |
返回数据 |
返回失败示例：
{
"code": "1009",
"msg": "温控关闭温度应高于启动温度！", "data": []
}
3.3.8. 售水机校准价格(3.3.9)
接口地址：api.happy- ti.com:2028/device/checkshopprice?saler=hptserverdemo&appid=2beea5cb3ce00296d ba32e36b8a9dc3f&deviceId=860344045231889&flow_mode=计时模式&price_1=2&water_1=8&flow_para=500&price_2=2&water_2=7.5&status=calibrate
请求类型：multipart/form-data
请求方式：get
接口备注：
- 1.设备版本号>6.93 则显示三总模式，否则不显示流量计校准
- 2.计时模 式和流量计模式不显示第二路价格和水量
- 3.extra信息不为空且support_dual_port 为1显示第二路价格和水量，否则不显示
- 4.extra为空则显示为流量计参数设置 模式
- 5.获取到的cali_water 和cali_price 都需要除10之后显示出来，提交时乘10 恢复原数据。
调试工具：ApiPost
URI 参数说明：
|
参数名 |
示例值 |
参数类型 |
是否必填 |
参数描述 |
|
saler |
hptserverdemo |
Text |
是 |
商家账号 |
|
appid |
2beea5cb3ce00296 dba32e36b8a9dc3f |
Text |
是 |
开发者账号的 appid |
|
deviceId |
860344045231889 |
Text |
是 |
设备编号 |
|
flow_mode |
计时模式 |
Text |
是 |
计费模式：计时模式；流量计参数设置；流量计校准 |
|
price_1 |
2 |
Text |
是 |
第一路水价（元） |
|
water_1 |
8 |
Text |
是 |
第一路出水量（升） |
|
flow_para |
500 |
Text |
是 |
流量计参数 |
|
price_2 |
2 |
Text |
是 |
第二路水价（元） |
|
water_2 |
7.5 |
Text |
是 |
第二路出水量（升） |
|
status |
calibrate |
Text |
是 |
设备状态： calibrate_timer 计时模式校准中calibrate 校准价格calibrate_flow 流量计校准中 |
返回成功示例：
{
"code": 0,
"msg": "操作成功",
"data": []
}
返回失败参数说明：
|
参数名 |
示例值 |
参数类型 |
参数描述 |
|
code |
5004 |
String |
状态码 |
|
msg |
非官方 SIM 卡 |
String |
返回文字描述 |
|
data |
{} |
Object |
返回数据 |
返回失败示例：
{
"code": "5004",
"msg": "非官方 SIM 卡",
"data": []
}
3.3.10(11). 远程开关机接口
接口地址：api.happy- ti.com:2028/device/powercontrol?saler=hptserverdemo&appid=2beea5cb3ce00296dba 32e36b8a9dc3f&deviceId=860344045231884&action=on
请求类型：multipart/form-data
请求方式：get
接口备注：暂无描述
调试工具：ApiPost
URI 参数说明：
|
参数名 |
示例值 |
参数类型 |
是否必填 |
参数描述 |
|
saler |
hptserverdemo |
String |
是 |
商家账号 |
|
appid |
2beea5cb3ce00296 dba32e36b8a9dc3f |
String |
是 |
开发者账号的 appid |
|
deviceId |
860344045231884 |
String |
是 |
设备编号 |
|
action |
on |
String |
是 |
on 代表开机off 代表关机 |
请求体参数说明：
|
参数名 |
示例值 |
参数类型 |
是否必填 |
参数描述 |
|
无请求参数KEY/VALUE 类型 |
||||
返回成功参数说明：
|
参数名 |
示例值 |
参数类型 |
参数描述 |
|
code |
0 |
Number |
状态码 |
|
msg |
操作成功 |
String |
返回文字描述 |
|
data |
{} |
Object |
返回数据 |
返回成功示例：
{
"code": "0",
"msg": "操作成功",
"data": []
}
返回失败参数说明：
|
参数名 |
示例值 |
参数类型 |
参数描述 |
|
code |
018 |
Number |
状态码 |
|
msg |
参数错误 |
String |
返回文字描述 |
|
data |
{} |
Object |
返回数据 |
返回失败示例：
{
"code": "018",
"msg": "参数错误",
"data": []
}
3.4. SIM 卡模块
3.4.1. 获取 SIM 卡列表
接口地址：api.happy- ti.com:2028/simcard/getlist?appid=2beea5cb3ce00296dba32e36b8a9dc3f&saler=hpts erverdemo&page=1
请求类型：multipart/form-data
请求方式：get
接口备注：暂无描述
调试工具：ApiPost
URI 参数说明：
|
参数名 |
示例值 |
参数类型 |
是否必填 |
参数描述 |
|
appid |
2beea5cb3ce00296 dba32e36b8a9dc3f |
Text |
是 |
开发者账号的 appid |
|
saler |
hptserverdemo |
Text |
是 |
商家账号 |
|
page |
1 |
Text |
是 |
分页页码，数字类型,默认为第一页 |
返回成功参数说明：
|
参数名 |
示例值 |
参数类型 |
参数描述 |
|
code |
0 |
Number |
状态码 |
|
msg |
操作成功 |
String |
返回文字描述 |
|
data |
Object |
返回数据 |
|
|
data.iccid |
89860445101970725795 |
String |
SIM 卡编号 |
|
data.imei |
860344046670650 |
String |
设备编号 |
|
data.vendor |
中国移动 |
String |
运营商 |
|
data.status |
已销卡 |
String |
sim 卡状态 |
|
data.valid_date |
2021-09-24 17:45:08 |
String |
sim 卡到期时间 |
|
data.location |
我的家 |
String |
设备地址 |
|
data.precharge_effec t_date |
TimeStamp |
预充值生效时间 |
|
|
data.used |
0 |
String |
sim 卡流量使用量 MB |
返回成功示例：
{
"code": 0,
"msg": "操作成功", "data": [
{
"iccid": "89860445101970725795",
"imei": "860344046670650",
"vendor": "中国移动",
"status": "已销卡",
"valid_date": "2021-09-24 17:45:08",
"location": "我的家", "precharge_effect_date": null, "used": "0"
},
{
"iccid": "89860467092090056456",
"imei": "868626040703343",
"vendor": "中国移动",
"status": "已激活",
"valid_date": "2022-05-22 17:30:56",
"location": "云 K", "precharge_effect_date": null, "used": "2.3671875"
},
{
"iccid": "89860490102040109095",
"imei": "864917055581029",
"vendor": "中国移动",
"status": "正常",
"valid_date": "2023-02-28 00:00:00",
"location": "投币器", "precharge_effect_date": null, "used": "0.000"
}
]
}
3.4.2. 获取 SIM 卡充值链接（仅支持微信打开支付）
接口地址：api.happy- ti.com:2028/simcard/getchargelink?appid=2beea5cb3ce00296dba32e36b8a9dc3f&sale r=hptserverdemo&iccid=89860467092090056456
请求类型：multipart/form-data
请求方式：get
接口备注：暂无描述 调试工具：ApiPost
URI 参数说明：
|
参数名 |
示例值 |
参数类型 |
是否必填 |
参数描述 |
|
appid |
2beea5cb3ce00296 dba32e36b8a9dc3f |
Text |
是 |
开发者账号的 appid |
|
saler |
hptserverdemo |
Text |
是 |
商家账号 |
|
iccid |
898604670920900 56456 |
Text |
是 |
SIM 卡编号 |
请求体参数说明：
|
参数名 |
示例值 |
参数类型 |
是否必填 |
参数描述 |
|
无请求参数KEY/VALUE 类型 |
||||
返回成功参数说明：
|
参数名 |
示例值 |
参数类型 |
参数描述 |
|
code |
0 |
Number |
状态码 |
|
msg |
操作成功 |
String |
返回文字描述 |
|
data |
Object |
返回数据 |
|
|
data.link |
http://wx.happy- ti.com/wxpay/simcard/pay.ht ml?sign=NSf5wGRkEbmnoIvBZz |
String |
sim 卡充值链接 |
|
E3GSQfGi60V4YPXj062%2FPqZ 3v2y%2BqM%2BbZ8uH4mnLsN dBJr |
返回成功示例：
{
"code": 0,
"msg": "操作成功", "data": {
"link": "http://wx.happy- ti.com/wxpay/simcard/pay.html?sign=NSf5wGRkEbmnoIvBZzE3GSQfGi60V4YP Xj062%2FPqZ3v2y%2BqM%2BbZ8uH4mnLsNdBJr"
}
}
4. 接口业务场景流程说明
4.1. 零钱打水
步骤一：根据扫码设备ID 获取设备信息（3.3.4 接口）
步骤二：设备版本号>=7.5 需要调用 3.3.5 接口通知设备上线后再次调用获取设备信息
（3.3.4 接口），判断设备pay_status(此状态只做为支付状态使用，不代表设备网络状态)是否在线（非在线状态不可下单）；设备版本号低于 7.5 则可直接使用上一步返回的 pay_status
步骤三：调用 3.2.1 接口进行下单，下单成功后，调用 3.2.2 接口进行查单，判断是否通知到设备，完成后续逻辑（退款等）。
备注：旧版零钱下单接口需要切换到新版下单接口（3.2.1 接口），否则高版本设备可能会出现通知不到的情况。
步骤一：调用3.2.1接口进行下单，若返回code为1008，则需要再次下单
步骤二：下单成功后，调用3.2.2接口进行查单，判断是否通知到设备，完成后续逻辑（退款等）。
4.2无卡消费（刷卡）
步骤一：会员卡调用充值接口进行充值（无实际交易，只是对会员卡余额进行控制，可充负数进行主动扣费）。
步骤二：会员卡不记名，请在您的系统中完成用户绑定关系。
步骤三：调用3.1.9接口，相当于刷卡操作，会把会员卡余额通知到设备，打水完成自动扣费（通过3.1.2接口查询对应消费记录）。
5. 备注说明
5.1. 服务不可用情况
请在程序中实现接口的异常捕获机制，出现异常时及时与我们联系（需要请求完整报文数据）。
5.2. 接口调用异常提示说明
- 提示参数丢失，请检查请求参数字段。
- 提示数据错误，请检查appid 与商家账号是否一致且正确；检查参数值是否符合要求。
- 调用接口返回code270031,您已经被限流（单接口一分钟内最多请求100次，请合理调用）
暂无评论内容