说明

飞天诚信智能物联平台对外提供HTTPSRest方式的接口,所有的请求均采用POST方法。编码方式为UTF-8,消息体参数及返回结果为JSON格式。

注意:使用API前需要先获取Appkey和Appsecret。Appkey用于标识访问的应用,AppSecret用于传输数据时,对传输报文进行签名。

报文签名说明:

第一步:各接口中非空参数按照参数名ascii码从小到大排序,使用URL键值对的格式,拼接成待签名字符串,即

key1=value1&key2=value2&key3=value3

拼接成字符串。

假设发送的参数为:

{ appkey : 9A0A8659F005D6984697E2CA0A9CF3B7, timestamp :20181221162001, nonce : dpRxkhjbauiclpKoqt }

则待签名数据 appkey=9A0A8659F005D6984697E2CA0A9CF3B7&nonce=dpRxkhjbauiclpKoqt&timestamp=20181221162001

第二步: 使用apisecret作为签名密钥,对A进行签名,得到签名结果B

B=HmacSHA256(A, appsecret);

第三步:将B加入到参数列表中,得出最终发送的数据为:

{ appkey : 9A0A8659F005D6984697E2CA0A9CF3B7, timestamp :20181221162001, nonce : dpRxkhjbauiclpKoqt, sign:Base64URLEncode(B) }

使用流程

第一步:创建我的应用

为了正常运行开发环境,您需要建立一个应用并获得相应的【应用标识】、【应用安全密钥】和【应用服务器地址】,具体步骤如下:

1.点击进入飞天智能物联平台登录页面,登录飞天智能物联平台。

2.在管理平台左侧列表中,点击【添加应用】,跳转至添加应用界面,进行应用添加。

3.输入【应用名称】,应用描述(可选),点击【保存】按钮后,页面跳转至应用列表可查看新添加应用的【应用标识】【应用安全密钥】【应用服务器地址】等关键信息,在API初始化时需要用到这些参数。

第二步:集成您需要的接口

应用添加完成之后,您可以根据您的业务需要进行接口集成,请参见RESTful接口详细介绍。

设备绑定

请求地址:https://serverurl/v1/audio/

接口功能:将终端设备和商户二维码牌进行绑定。上传设备编号、二维码牌标识推送给消息服务平台,验证通过后,将此设备和码牌进行绑定。

参数名 参数说明 value是否必须
appkey 应用appkey
method 请求的接口名,bindDevice
devicesn 设备编号
paycode 码牌编号(收钱码的二维码内容,或唯一标识)
timestamp 时间戳,格式yyyyMMddHHmmss
nonce client端产生的随机字符串。长度不超过32位
sign 请求参数的签名 Base64Url_encode(HmacSHA256(待签名参数, appsecret)) 其中待签名字符串生成方式详见“报文签名说明”
参数名 参数说明
code 返回响应码
msg 结果描述
nonce 请求时的nonce,原样带回
sign 响应数据的签名 Base64Url_encode(HmacSHA256(待签名参数, appsecret)) 待签名参数生成规则和请求签名生成规则相同

获取码牌绑定的设备

请求地址:https://serverurl/v1/audio/

接口功能:上传二维码牌编号,获取二维码牌对应绑定的设备编号。

参数名 参数说明 value是否必须
appkey 应用appkey
method 请求的接口名,getBindDevice
paycode 码牌编号(收钱码的二维码内容,或唯一标识)
timestamp 时间戳,格式yyyyMMddHHmmss
nonce client端产生的随机字符串。长度不超过32位
sign 请求参数的签名 Base64Url_encode(HmacSHA256(待签名参数, appsecret)) 其中待签名字符串生成方式详见“报文签名说明”

消息推送(指定设备编号)

请求地址:https://serverurl/v1/audio/

接口功能:向指定的设备推送语音消息。

参数名 参数说明 value是否必须
appkey 应用appkey
method 请求的接口名,push
devicesn 设备编号,可以指定设备编号向该设备推送消息
message 播报金额,int类型,单位:分
push_template 语音模板(1支付宝;2微信;3扫码(默认);4银联)
timestamp 时间戳,格式yyyyMMddHHmmss
nonce client端产生的随机字符串。长度不超过32位
sign 请求参数的签名 Base64Url_encode(HmacSHA256(待签名参数, appsecret)) 其中待签名字符串生成方式详见“报文签名说明”
参数名 参数说明
code 返回响应码
msg 结果描述
nonce 请求时的nonce,原样带回
pushsn 消息流水号
sign 响应数据的签名 Base64Url_encode(HmacSHA256(待签名参数, appsecret)) 待签名参数生成规则和请求签名生成规则相同

消息推送(使用收钱码)

请求地址:https://serverurl/v1/audio/

接口功能:向指定的设备推送语音消息。

参数名 参数说明 value是否必须
appkey 应用appkey
method 请求的接口名,pushByPaycode
paycode 收钱码,指定收钱码,向绑定的设备推送消息
message 播报金额,int类型,单位:分
push_template 语音模板(1支付宝;2微信;3扫码(默认);4银联)
timestamp 时间戳,格式yyyyMMddHHmmss
nonce client端产生的随机字符串。长度不超过32位
sign 请求参数的签名 Base64Url_encode(HmacSHA256(待签名参数, appsecret)) 其中待签名字符串生成方式详见“报文签名说明”
参数名 参数说明
code 返回响应码
msg 结果描述
pushsn 消息流水号
nonce 请求时的nonce,原样带回
sign 响应数据的签名 Base64Url_encode(HmacSHA256(待签名参数, appsecret)) 待签名参数生成规则和请求签名生成规则相同

查询设备状态

请求地址:https://serverurl/v1/audio/

接口功能:检查某个指定的设备的绑定状态。

参数名 参数说明 value是否必须
appkey 应用appkey
method 请求的接口名,getDeviceInfo
devicesn 设备编号
timestamp 时间戳,格式yyyyMMddHHmmss
nonce client端产生的随机数。最大长度32位
sign 请求参数的签名 Base64Url_encode(HmacSHA256(待签名参数, appsecret)) 其中待签名字符串生成方式详见“报文签名说明”
参数名 参数说明
code 返回响应码
msg 结果描述
status 设备的状态(0未绑定,1已绑定)
nonce 请求时的nonce,原样带回
sign 响应数据的签名 Base64Url_encode(HmacSHA256(待签名参数, appsecret)) 待签名参数生成规则和请求签名生成规则相同

设备解绑

请求地址:https://serverurl/v1/audio/

接口功能:解除终端设备和二维码牌的绑定关系。

参数名 参数说明 value是否必须
appkey 应用appkey
method 请求的接口名,unbindDevice
devicesn 设备编号
timestamp 时间戳,格式yyyyMMddHHmmss
nonce client端产生的随机数。最大长度32位
sign 请求参数的签名 Base64Url_encode(HmacSHA256(待签名参数, appsecret)) 其中待签名字符串生成方式详见“报文签名说明”
参数名 参数说明
code 返回响应码
msg 结果描述
nonce 请求时的nonce,原样带回
sign 响应数据的签名 Base64Url_encode(HmacSHA256(待签名参数, appsecret)) 待签名参数生成规则和请求签名生成规则相同

获取消息列表

请求地址:https://serverurl/v1/audio/

接口功能:根据设备id和时间段查询消息列表。

参数名 参数说明 value是否必须
appkey 应用appkey
method 请求的接口名,getMessage
devicesn 设备编号
start_time 开始时间时间戳(int类型秒数)
end_time 结束时间时间戳(int类型秒数)
start_row 分页起始行(>=0)
page_size 分页每页行数(1<value<100)
timestamp 时间戳,格式yyyyMMddHHmmss
nonce client端产生的随机数。最大长度32位
sign 请求参数的签名 Base64Url_encode(HmacSHA256(待签名参数, appsecret)) 其中待签名字符串生成方式详见“报文签名说明”
参数名 参数说明
code 返回响应码
msg 结果描述
list 获取的消息列表
nonce 请求时的nonce,原样带回
sign 响应数据的签名 Base64Url_encode(HmacSHA256(待签名参数, appsecret)) 待签名参数生成规则和请求签名生成规则相同

获取消息统计信息

请求地址:https://serverurl/v1/audio/

接口功能:根据设备id和时间段查询消息统计信息。

参数名 参数说明 value是否必须
appkey 应用appkey
method 请求的接口名,getMessageStatistics
devicesn 设备编号
start_time 开始时间时间戳(int类型秒数)
end_time 结束时间时间戳(int类型秒数)
timestamp 时间戳,格式yyyyMMddHHmmss
nonce client端产生的随机数。最大长度32位
sign 请求参数的签名 Base64Url_encode(HmacSHA256(待签名参数, appsecret)) 其中待签名字符串生成方式详见“报文签名说明”
参数名 参数说明
code 返回响应码
msg 结果描述
success_count 成功播报的条数
success_rate 播报的成功率(单位%)
nonce 请求时的nonce,原样带回
sign 响应数据的签名 Base64Url_encode(HmacSHA256(待签名参数, appsecret)) 待签名参数生成规则和请求签名生成规则相同

查询消息信息

请求地址:https://serverurl/v1/audio/

接口功能:根据消息流水号查询消息信息。

参数名 参数说明 value是否必须
appkey 应用appkey
method 请求的接口名,getOneMessage
pushsn 消息流水号
timestamp 时间戳,格式yyyyMMddHHmmss
nonce client端产生的随机数。最大长度32位
sign 请求参数的签名 Base64Url_encode(HmacSHA256(待签名参数, appsecret)) 其中待签名字符串生成方式详见“报文签名说明”
参数名 参数说明
code 返回响应码
msg 结果描述
data 查询到的消息数据(JSON格式)
nonce 请求时的nonce,原样带回
sign 响应数据的签名 Base64Url_encode(HmacSHA256(待签名参数, appsecret)) 待签名参数生成规则和请求签名生成规则相同