生钛圈 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次,请合理调用)
暂无评论内容