系统平台API接口-饮水机接口

文档历史记录

日期	版本	作者	描述	审阅者
2018-10-28	1.0	陈微战	撰写

引言

编写目的

   思迅达物联平台为第三方平台提供饮水机设备通讯API接口，适用人群：开发人员、运维人员。

背景

   项目名称：思迅达饮水机项目

   任务提出者：杭州东骏科技有限公司

   开发者：杭州东骏科技有限公司

   用户：第三方平台

定义

术语/缩写	含义
-/--	-/--

基本需求

   说明：API基础URL

   测试环境: https://qa-api.supeeder.com/api/gateway

   生产环境: https://api.supeeder.com/api/gateway

HTTP标准包头字段（必填）

字段	类型	约束	说明
app_id	string	必填	平台给API接口商的系统appid
psd_entry	long	必填	当前调用日期的毫秒数，13位长度整型数值，例如：1527751383732, 误差在10分钟之内

HTTP公共请求体参数（必填）

字段	类型	约束	说明
api	string	必填	接口api，具体值参见每章节接口地址，例如3.1.1接口地址中api项值
nonce	string(16)	必填	随机串, 由16个ASCII可见字符(除空格)组成, 即ASCII码范围从0x21 至 0x7E, 每次调用需重新生成nonce
version	string	选填	接口版本号，默认为1.0
sign	string	必填	签名，加密方式为MD5加密，详见签名方式

   说明：下述所有接口的请求包体中不再重复累述，务必在发起调用时带上。

异步通知

请求头

   说明：服务方将在客户端提供的回调地址请求头中增加如下头信息。

属性	类型	约束	说明
app_id	string	必填	调用方的app_id原路传回给客户端
api	string	必填	参见异步通知接口API
version	string	必填	固定值为1.0，供客户端调用方判断标识，无实际意义。

数据格式

   说明：服务方发起异步数据数据格式为：Json字符串，Content-Type：Application/json，Charset：UTF-8。

重试机制

 目前接口平台针对失败或超时的异步请求响应制定如下重试机制：
 a)频率：第一次：1s，第二次：10s，第三次：30s，第四次：3m，第五次：1h，最后一
   次：1d；
 b)请第三方根据实际情况制定重试通知的幂等处理。

安全规则

签名方式

   1)必须带有nonce随机串, 由16个ASCII可见字符(除空格)组成, 即ASCII码范围从0x21 至 0x7E, 每次调用需重新生成nonce；

   2)参数名ASCII码从小到大排序（字典序）；

   3)参数名区分大小写；

   4)排序后的参数串需要加上&key=商户的密钥, 再生成签名，

     * key为每个已开通商户自己(或默认)设置的密钥, 请妥善保管切勿泄漏, 可定时修改*

   5)使用MD5加密并全部转大写得到sign签名串, 发送时带上此sign字段；

   举例：假设传送的参数如下：

        nonce : 1234abcd1234abcd

        api： net.charge.test

        version :  1.0

        data1 :  aaa

        data2 :  bbb

   第一步：对参数按照key=value的格式，并按照参数名ASCII字典序排序如下：

       stringA="api=net.charge.test&data1=aaa&data2=bbb&nonce=1234abcd1234abcd&version=1.0";

   第二步：拼接API密钥：

       stringSignTemp="stringA&key=123123123123123"

       sign=MD5(stringSignTemp).toUpperCase()="154ADAB370EF191E882E548BE71568EE"

   得到最终发送的数据 (真正发送时参数无需排序, 不允许发送key)：

   示例

    {
        "nonce"="1234abcd1234abcd",
        "api"="net.charge.test",
        "version"="1.0",
        "data1"="aaa",
        "data2"="bbb",
        "sign"="154ADAB370EF191E882E548BE71568EE"
    }

响应解析

设备基础接口

同步接口：设备基础信息查询

业务说明

   为用户提供根据设备号查询设备基础信息服务。

请求地址

URL	详见基本需求说明
API	business.equip.water.dispenser.base.info.query
Method	GET

请求包体

属性	类型	约束	格式枚举	说明
equipCd	string(20)	必填	示例	设备号

响应包体

属性		类型	约束	格式枚举	说明
code		int	必填	参见返回码	私有返回码： 10001：设备号非法。 0：请求失败 1：请求成功，更多参见返回码示例。
msg		string	选填		若请求失败，此处会包含失败信息
data		Object	必填		内容
	cd	string(20)	必填		设备号
	name	string(20)	必填		设备名称
	equipTypeName	string(64)	必填		设备类型名称
	status	string(32)	必填	normal\| stop	启动状态
	isOnline	Boolean	必填	true\|false	在离线状态，true：在线，false：离线
	longitude	double(22,6)	选填		经度，GPS坐标，精度保留6位
	latitude	double(22,6)	选填		纬度，GPS坐标，精度保留6位

示例

{
    "code":1,
    "data":
    {
        "cd":"2222222212121",
        "name ":"饮水机测试设备",
        "equipTypeName":"类型名称",
        "status":"normal",
        "isOnline":true,
        "longitude":104.92882,
        "latitude":30.298192
    }
}

同步接口：设备在离线查询

业务说明

   为用户提供查询设备在离线查询。

请求地址

URL	详见基本需求说明
API	net.equip.online.query
Method	GET

请求包体

属性	类型	约束	格式枚举	说明
equipCd	string(20)	必填	示例	设备号

响应包体

属性		类型	约束	格式枚举	说明
code		int	必填	参见返回码	0：请求失败 1：请求成功，更多参见返回码示例。
msg		string	选填		若请求失败，此处会包含失败信息
data		Object	必填		内容
	online	boolean	必填	true\|false	在离线状态，true：在线，false：离线

示例

{
    "code":1,
    "data":
    {
         "online":false
    }
}

饮水机模块通信

同步接口：打开或关闭控制板开关

业务说明

   提供下发打开或关闭饮水机控制板总开关。

请求地址

URL	详见基本需求说明
API	net.equip.water.dispenser.board.control.switch
Method	POST

请求包体

属性	类型	约束	格式枚举	说明
equipCd	string(20)	必填		设备号
switchFlag	int(1)	必填	0\|1	开关，0：关，1：开

响应包体

属性		类型	约束	格式枚举	说明
code		int	必填	参见返回码	私有返回码： 10001：开（关）失败； 10002：开关非法。公共响应码： 0：请求失败 1：请求成功，更多参见返回码示例。
msg		string	选填		若请求失败，此处会包含失败信息

示例

{
    "code":1
}

同步接口：打开或关闭出水板开关

业务说明

   提供下发打开或关闭饮水机出水板开关。

请求地址

URL	详见基本需求说明
API	net.equip.water.dispenser.board.effluent.switch
Method	POST

请求包体

属性	类型	约束	格式枚举	说明
equipCd	string(20)	必填		设备号
switchFlag	int(1)	必填	0\|1	开关，0：关，1：开

响应包体

属性		类型	约束	格式枚举	说明
code		int	必填	参见返回码	私有返回码： 10001：开关非法。公共响应码： 0：请求失败 1：请求成功，更多参见返回码示例。
msg		string	选填		若请求失败，此处会包含失败信息

示例

{
    "code":1
}

同步接口：设置饮水机脉冲数

业务说明

   提供下发设置饮水机脉冲数，例如：当设置为2000脉冲时，具体对应多少水量由第三方平台设定，若第三方平台设置为3500ml，则上报时2000脉冲即为3500ml水量。

请求地址

URL	详见基本需求说明
API	net.equip.water.dispenser.pulse.set
Method	POST

请求包体

属性	类型	约束	格式枚举	说明
equipCd	string(20)	必填		设备号
pulse	int	必填		脉冲数

响应包体

属性		类型	约束	格式枚举	说明
code		int	必填	参见返回码	私有返回码： 10001：脉冲设置失败； 10002：脉冲数非法。公共响应码： 0：请求失败 1：请求成功，更多参见返回码示例。
msg		string	选填		若请求失败，此处会包含失败信息

示例

{
    "code":1
}

同步接口：设置出水板工作模式

业务说明

   提供下发设置出水板工作模式。

请求地址

URL	详见基本需求说明
API	net.equip.water.dispenser.board.effluent.workmode.set
Method	POST

请求包体

属性	类型	约束	格式枚举	说明
equipCd	string(20)	必填		设备号
code	int(1)	必填	0\|1	工作模式，0：租金滤芯模式，1：流量计费模式。

响应包体

属性		类型	约束	格式枚举	说明
code		int	必填	参见返回码	私有返回码： 10001：工作模式非法。公共响应码： 0：请求失败 1：请求成功，更多参见返回码示例。
msg		string	选填		若请求失败，此处会包含失败信息

示例

{
    "code":1
}

同步接口：打开饮水机出水阀开关

业务说明

   提供下发打开饮水机出水阀开关。

请求地址

URL	详见基本需求说明
API	net.equip.water.dispenser.outlet.switch.open
Method	POST

请求包体

属性	类型	约束	说明
equipCd	string(20)	必填	设备号
port	int	必填	端口号
pulse	int	必填	脉冲数

响应包体

属性		类型	约束	格式枚举	说明
code		int	必填	参见返回码	私有返回码： 10001：打开失败； 10002：端口非法； 10003：脉冲数非法。公共响应码： 0：请求失败 1：请求成功，更多参见返回码示例。
msg		string	选填		若请求失败，此处会包含失败信息

示例

{
    "code":1
}

异步通知：饮水机出水上报

业务说明

   服务端异步通知第三方平台饮水机出水阀状态、出水脉冲数等出水信息。

请求地址

URL	第三方平台提供的notifyUrl地址
API	net.equip.water.dispenser.async.notice.outlet.info
Method	POST

请求包体

属性	类型	约束	格式枚举	说明
equipCd	string(20)	必填		设备号
port	int	必填		端口号
pulse	int	必填		脉冲数
portStatus	int(1)	必填	0\|1	出水阀状态，0：关闭，1：打开

响应包体

响应	类型	约束	说明
SUCCESS	string	必填	通知接收并处理成功
FAIL	string	必填	通知已接收但是处理失败，将触发通知重发，详见异步通知重试机制
无响应或超时		必填	通知已接收但是处理失败，将触发通知重发，详见异步通知重试机制

示例

   SUCCESS

异步通知：饮水机出水完成上报

业务说明

   服务端异步通知第三方平台饮水机出水完成。

请求地址

URL	第三方平台提供的notifyUrl地址
API	net.equip.water.dispenser.async.notice.outlet.finish
Method	POST

请求包体

属性	类型	约束	格式枚举	说明
equipCd	string(20)	必填		设备号
port	int(1)	必填		出水阀编号
waterQty	double(5,2)	必填		水量，单位：毫升，保留两个小数
portStatus	int(1)	必填	0\|1	出水阀状态，0：关闭，1：打开

响应包体

响应	类型	约束	说明
SUCCESS	string	必填	通知接收并处理成功
FAIL	string	必填	通知已接收但是处理失败，将触发通知重发，详见异步通知重试机制
无响应或超时		必填	通知已接收但是处理失败，将触发通知重发，详见异步通知重试机制

示例

   SUCCESS

富氢水站API接口说明

业务说明

   服务端发送刷卡结果通知。

请求地址

URL	第三方平台提供的notifyUrl地址
API	net.equip.drink.async.notice.swipe.failed
Method	POST

请求包体

属性	类型	约束	格式枚举	说明
equipCd	string	必填		设备号
code	string	必填		发送方结果通知
cardNo	string	必填		卡号
type	string	必填	1/2	返回类型枚举，1表示刷卡返回处理，2表示出水前返回处理

响应包体

响应		类型	约束	格式枚举	说明
code		int	必填		0：请求失败,1：请求成功，
msg		string	选填		若请求失败，此处会包含失败信息

示例

   "code": 1

系统平台API接口-饮水机接口

目录

文档历史记录

引言

编写目的

背景

定义

基本需求

HTTP标准包头字段（必填）

HTTP公共请求体参数（必填）

异步通知

请求头

数据格式

重试机制

安全规则

签名方式

响应解析

设备基础接口

同步接口：设备基础信息查询

业务说明

请求地址

请求包体

响应包体

示例

同步接口：设备在离线查询

业务说明

请求地址

请求包体

响应包体

示例

饮水机模块通信

同步接口：打开或关闭控制板开关

业务说明

请求地址

请求包体

响应包体

示例

同步接口：打开或关闭出水板开关

业务说明

请求地址

请求包体

响应包体

示例

同步接口：设置饮水机脉冲数

业务说明

请求地址

请求包体

响应包体

示例

同步接口：设置出水板工作模式

业务说明

请求地址

请求包体

响应包体

示例

同步接口：打开饮水机出水阀开关

业务说明

请求地址

请求包体

响应包体

示例

异步通知：饮水机出水上报

业务说明

请求地址

请求包体

响应包体

示例

异步通知：饮水机出水完成上报

业务说明

请求地址

请求包体

响应包体

示例

富氢水站API接口说明

业务说明

请求地址

请求包体

响应包体

示例

导航菜单