API调用协议
1.概述
优声云打印开放平台通讯协议是一个无状态的、轻量级的基于HTTP的 RPC 通讯协议。
2.安全说明
出于用户体验考虑,同时为了平衡兼容和安全风险,接口网关侧支持https,入驻用户请使用https 协议。
3.设计原则
本协议只定义数据交互的格式与方式,不关注数据的传输方式,不关注认证方式,不关注接口版本控制。
4.RPC 调用
开放平台的 RPC 调用主要用于客户端应用主动获取开放平台服务器端数据信息,是通过客户端应用向开放平台的API服务器发送HTTP POST或GET请求对象,而服务器返回响应对象实现的。
5.Content-type请求头
应用发起API调用请求时需要指定Content-type请求头,具体规则如下:
Content-Type:application/json
开发者发起的请求以表单方式提交数据
如无特殊说明,接口的所有参数值均为UTF-8编码
签名算法
- 将请求参数中除sign外的多个键值对,根据键按照字典序排序,并按照"key1value1key2value2…"的格式拼成一个字符串(空值不参与签名):
key1value1key2value2
- 将appsecret拼接在1中排序后的字符串后面得到待签名字符串:
key1value1key2value210bf3984d33900906df9fabdbfda59e8
- 使用md5算法加密待加密字符串即为sign:
a8767fa47a75da11a04a13be398c6eb8
- 将sign添加到请求参数中
需要urlencode的参数,请在urlencode前参与签名
打印
请求地址:https://open-api.ushengyun.com/printer/print
post:/print
*string:appid#应用id
*string:deviceid#设备编码
*string:devicesecret#设备秘钥
*string:printdata#打印内容,打印排版见附录-排版引擎
*string:timestamp#当前时间戳(单位秒)
*string:sign#请求签名
<<<
success
errNun为0只表示接口成功收到了订单,并不代表已经打印成功
{
"errNum": 0,
"errMsg": "success",
"retData": {"id":"","status":""}
}
id为记录的单号
status表示打印机的状态
0:打印机掉线
1:打印机在线
2:打印机缺纸或装纸不正确
当status等于0或者2时,表示设备状态异常,无法正常执行打印逻辑,待设备状态恢复正常后,系统会自动重试,订单会继续完成打印
<<<
error
{
"errNum": 2,
"errMsg": "提交超时",
}
{
"errNum": 3,
"errMsg": "打印机信息有误",
}
打印排版见附录-排版引擎
查询设备状态
post:/status
*string:appid#应用id
*string:deviceid#设备号
*string:devicesecret#设备秘钥
*string:timestamp#当前时间戳(单位秒)
*string:sign#请求签名
<<<
success
离线
{
"errNum": 0,
"errMsg": "success",
"retData": {"status":"0"}
}
在线
{
"errNum": 0,
"errMsg": "success",
"retData": {"status":"1"}
}
缺纸
{
"errNum": 0,
"errMsg": "success",
"retData": {"status":"2"}
}
<<<
error
{
"errNum": 2,
"errMsg": "提交超时",
}
{
"errNum": 3,
"errMsg": "打印机信息有误",
}
查询打印状态
建议有条件的开发者对接打印完成消息接口
post:/printstatus
*string:appid#应用id
*string:dataid#打印单号
*string:timestamp#当前时间戳(单位秒)
*string:sign#请求签名
<<<
success
未打印
{
"errNum": 0,
"errMsg": "success",
"retData": {"status":"0"}
}
已打印
{
"errNum": 0,
"retMsg": "success",
"retData": {"status":"1"}
}
<<<
error
{
"errNum": 2,
"errMsg": "提交超时",
}
{
"errNum": 3,
"errMsg": "打印机信息有误",
}
{
"errNum": 4,
"errMsg": "dataid error",
}