说明
飞天诚信智能物联平台对外提供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×tamp=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)) 待签名参数生成规则和请求签名生成规则相同 |