优声云打印机对接文档

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