生钛圈 API 文档

V2.12

日期	版本	说明
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	充电桩下单接口，设备详情，设备列表接口支持充电桩设备

1. 文档简介

1.1. 特别声明

未得到本公司的书面许可，不得为任何目的、以任何形式或手段（包括但不限于机械的或电子的）复制或传播本文档的任何部分。对于本文档涉及的技术和产品，本公司拥有其专利

（或正在申请专利）、商标、版权或其它知识产权。除非得到本公司的书面许可协议，本文档不授予这些专利、商标、版权或其它知识产权的许可。

本文档因产品功能示例和描述的需要，所使用的任何人名、企业名和数据都是虚构的，并仅限于本公司内部测试使用，不等于本公司有对任何第三方的承诺和宣传。

1.2. 阅读对象

贵公司的技术部门的开发、维护及管理人员，应具备以下基本知识：

1. 1. 了解HTTPS/HTTP 协议等内容。
  2. 了解信息安全的基本概念。
  3. 了解计算机至少一种编程语言。

1.3. 产品说明

黑皮钛后台接口均采用 http GET/POST 接口，返回值为JSON 格式。商家账户可以申请成为生钛圈开发者，申请之后会得到一个appid，appid 会在接口调用中使用，用于鉴权，商家账户只能通过接口查询本商家的信息。调用接口都会有返回值，返回值中error 状态如果为’0’，则调用是成功的，如果不为 0，根据不同返回值查看是否参数有问题，或者其他问题。如有疑问，请联系相关工程师。

限流：每个商家账号，单个接口请求，每分钟不得超过 100 次（超过后不再返回数据）

2. 使用流程

准备阶段：

1. 申请测试号等信息；
2. 取得开发手册（本文档）等资料；

开发阶段：

1. 根据提供的DEMO 结合开发文档快速熟悉对接接口；
2. 根据本系统提供的接口，在自己的系统上进行开发，实现所需要的业务功能；
3. 对自己系统的业务功能进行全面测试；
4. 与测试环境进行联调。

生产使用：

1. 使用系统提供的正式资料。

3. 接口列表

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 进行充值。

调试工具：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（套餐充值）

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（挂失）
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_afterdisco unt	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（挂失）
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

请求类型：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		Text	否	设备通道 0,1,2,3 对应 1,2,3,4 路出水口，不传默认 1 路出水口
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_afterdisco unt	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	下单时间

返回成功示例：

{

"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"

}

返回失败示例：

{

"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

接口备注：暂无描述

调试工具：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. 添加设备接口

接口地址：http://api.happy-ti.com:2028/adddevice?appid=2beea5cb3ce00296dba32e36b8a9dc3f&saler=hptserverdemo&deviceId=860344045231887&location=123123123123&type=shop_happyfu

请求类型：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(在线) 用户下单前根据此状态是否在线来进行下单，离线，水箱空不要进行下单（高版本请调用 3.3.5 接口）
data.version		Object	设备版本
data.limit	9	String	单次消费限额
data.tds	0	String	TDS 值
data.signal	-20	String	信号值
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 参数说明：

参数名	示例值	参数类型	是否必填	参数描述
appid	2beea5cb3ce00296 dba32e36b8a9dc3f	Text	是	开发者账号的 appid
saler	hptserverdemo	Text	是	商家账号
deviceId	860344045231887	Text	是	设备编号

返回成功参数说明：

参数名	示例值	参数类型	参数描述
code	0	Number	状态码
msg	操作成功	String	返回文字描述
data		Object	返回数据

返回成功示例：

{

"code": 0,

"msg": "操作成功",

"data": {}

}

返回失败参数说明：

参数名	示例值	参数类型	参数描述
code	-1	String	状态码
msg	没有查找到该设备	String	返回文字描述
data	{}	Object	返回数据

返回失败示例：

{

"code": "069",

"msg": "没有查找到该设备",

"data": []

}

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.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 如果此参数有误就看 flow_params_1、flow_params_2	500	Text	是	流量计参数
price_2	2	Text	是	第二路水价（元）
water_2	7.5	Text	是	第二路出水量（升）
status	calibrate	Text	是	设备状态： calibrate_timer 计时模式校准中calibrate 校准价格calibrate_flow 流量计校准中

如果此参数有误就看：接口地址：api.happy-

ti.com:2028/device/checkwaterprice?saler=hptserverdemo&appid=2beea5cb3ce00296

dba32e36b8a9dc3f&deviceId=860344045231888&flow_mode=%E8%AE%A1%E6%97%

B6%E6%A8%A1%E5%BC%8F&price_1=2&water_1=8&flow_params_1=500&price_2=2

&water_2=7.5&status=calibrate&flow_params_2=500

flow_params_1	500	Text	是	流量计参数 1
flow_params_2	500	Text	是	流量计参数 2

返回成功示例：

{

"code": 0,

"msg": "操作成功",

"data": []

}

返回失败参数说明：

参数名	示例值	参数类型	参数描述
code	5004	String	状态码
msg	非官方 SIM 卡	String	返回文字描述
data	{}	Object	返回数据

返回失败示例：

{

"code": "5004",

"msg": "非官方 SIM 卡",

"data": []

}

3.3.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 卡充值链接