RESTful API 接口

❗️注意：如自行封装 API 接口，建议设置 HTTP 请求头的 UA，平台可能会拒绝无 UA 的请求

开始前

  1. 获取分配的appid和appsecret

  2. 阅读接口调用协议约定，准备请求的所需的参数

接口调用协议约定

  1. 协议：https;

  2. 所有请求方法都用 POST;

  3. 请求与响应内容都是json;

  4. 请求内容通用参数：

    通用参数类型备注
    appidstring应用ID
    reqidstring请求唯一标识, 可以用uuid也可以其他方式生成,一小时内相同reqid会被拒绝
    timestamplongtimestamp，请求时间戳，精确豪秒(UTC+8),跟服务端时间相差超过5分钟会拒绝
    signstring参数签名,通过appid,appscret,timestamp,biz和reqid参数计算获得,算法示例
    biztypeint业务类型,需要跟业务接口相匹配, 定义见表
    bizstring业务参数, json字符串, 详情见各API的业务参数定义

请求参数示例：

{
    "timestamp": 1670408954964,
    "appid": "13246***",
    "reqid": "6fcd97f4-9ffb-4de8-bf9f-dcb9b8f3e7fe",
    "sign": "UDEzqIGFYw32McyktcUMes2X5RrtJIblAQ1FfD1VY5I=",
    "biztype": 1,
    "biz": "[{\"sn\":\"680002000***\", 	  \"key\":\"42d5ea3c5b3b79a990146de2e8d44debe3df4b31693f4ac4b02330d395b064fb\"}]"
}

  1. 响应参数通用参数

    通用参数类型备注
    codeInt错误码, 0: 无错误 其他:见表
    messagestring错误原因
    datajson业务结果
  {
    "code": 0,  
    "message":"成功", 
    "data": {
      "fail" : [{"sn": "680002000***", "reason": "无效的打印机序列号"}],
    }             
  }

签名算法

String appid= "";
String biz = "";
String appSecret = "";
long timestamp = 0L;
int biztype = 1;
String signMessage = String.format("%s%d%s%d%s", appid, timestamp, biz, biztype, reqid);
try {
    String sign = HMAC.sign(signMessage.getBytes(StandardCharsets.UTF_8), 	appSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
} catch (NoSuchAlgorithmException | InvalidKeyException e) {
}

业务接口定义

1. 打印小票

POST https://saas.excelsecu.com/openapi/v1/iot/printer/print

  • 业务参数

    请求参数名称类型长度/范围是否必填备注
    sn打印机序列号string50是
    tts播报内容string32否不传参数视为不播报语音，只打印小票;
    content小票模板的base64编码string8k否最大支持8k字节，不传就不打票，与播报音源不能同时为空字符串,模板格式
    count打印小票张数int1~5否不传默认1， 取值范围: 1~5

请求示例：

{
    "timestamp": 1670408954964,
    "appid": "13246***",
    "sign": "MfR2FrF4mkQD+tVSgrGSYp1Xub+T/zcM76eaj5FZkJo=",
    "biz": "{\"sn\":\"680002000***\", \"content\":\"既打印小票\", \"tts\":\"也播语音\"}"
}

  • 响应说明

    请求参数名称类型备注
    code响应码int0 表示接收打印请求成功
    message响应消息string响应码对应的说明
    data
    - printId打印请求IDstring打印请求受理ID，用于后续小票打印的状态跟踪
    - sn打印机序列号string当前打印机序列号

示例：

{
    "code": 0,
    "message": "成功",
    "data": {
        "sn": "680002000***",
        "printId": "8812090001010100145817255982****"
    }
}

2. 获取打印状态

POST https://saas.excelsecu.com/openapi/v1/iot/printer/print-status

  • 业务参数

    请求参数名称类型长度/范围是否必填备注
    sn打印机序列号string50是
    printId打印请求IDstring32是

请求示例：

{
    "timestamp": 1670408954964,
    "appid": "13246***",
    "sign": "sTYhIKCJ9k2A69BO1STaTo9yYBaq242Ri8NR3ETO6O8=",
    "biz": "{\"sn\":\"680002000***\", \"printId\": \"8812070001010100200430280975****\"}"
}

  • 响应说明

    请求参数名称类型备注
    code响应码int0 表示接收打印请求成功
    message响应消息string响应码对应的说明
    data
    - printId打印请求IDstring打印请求受理ID，用于后续小票打印的状态跟踪， 长度为19位
    - status打印状态string打印状态 1: 待打印 3:已打印 4:设备未就绪 5:已失败 6:已失效

示例：

{
    "code": 0,
    "message": "成功",
    "data": {
        "status": 6,
        "printId": "8812070001010100200430280975****"
    }
}

3. 清除打印队列

POST https://saas.excelsecu.com/openapi/v1/iot/printer/clear-queue

  • 业务参数

    请求参数名称类型长度/范围是否必填备注
    sn打印机序列号string50是

请求示例：

{
    "timestamp": 1670408954964,
    "appid": "13246***",
    "sign": "WbAMkch+Cs3xHMSyrV3xfZpXgxKgYEyUXCthLnD0xk4=",
    "biz": "{\"sn\":\"680002000***\"}"
}

  • 响应说明

    请求参数名称类型备注
    code响应码int0 表示接收打印请求成功
    message响应消息string响应码对应的说明
    data

示例：

{
    "code": 0,
    "message": "成功",
    "data": {}
}

4. 添加打印机

POST https://saas.excelsecu.com/openapi/v1/iot/printer/add

  • 业务参数

    请求参数名称类型长度/范围是否必填备注
    sn打印机序列号string50是
    key设备密钥string64否未添加过的设备必须提供，已经添加的打印机不再验证设备密钥

请求示例：

{
    "timestamp": 1670408954964,
    "appid": "13246***",
    "sign": "UDEzqIGFYw32McyktcUMes2X5RrtJIblAQ1FfD1VY5I=",
    "biz": "[{\"sn\":\"680002000***\", \"key\":\"42d5ea3c5b3b79a990146de2e8d44debe3df4b31693f4ac4b02330d395b064fb\"}]"
}

  • 响应说明

    请求参数名称类型备注
    code响应码int0 表示接收打印请求成功
    message响应消息string响应码对应的说明
    data
    - fail失败列表jsonarray添加失败的设备序号和原因

示例：

{
    "code": 0,
    "message": "成功",
    "data": {
        "fail": [
            {
                "sn": "680002000***",
                "reason": "打印机已添加"
            }
        ]
    }
}

5. 删除打印机

注意：在大多数情况，不应该调用删除接口。调用删除接口，等同于删除了该打印机的绑定关系，后续无法调用其他接口

POST https://saas.excelsecu.com/openapi/v1/iot/printer/remove

  • 业务参数

    请求参数名称类型长度/范围是否必填备注
    sn打印机序列号string50是

请求示例：

{
    "timestamp": 1670408954964,
    "appid": "13246***",
    "sign": "lit6OhKjaNOWWIYeb8XqYgsh2mPwndd7MfO84a9FAbo=",
    "biz": "[{\"sn\":\"680002000***\"}]"
}

  • 响应说明

    请求参数名称类型备注
    code响应码int0 表示接收打印请求成功
    message响应消息string响应码对应的说明
    data
    - fail失败列表jsonarray删除失败的设备序号和原因

示例：

{
    "code": 0,
    "message": "成功",
    "data": {
        "fail": []
    }
}

6. 获取设备状态

POST https://saas.excelsecu.com/openapi/v1/iot/printer/device-status

  • 业务参数

    请求参数名称类型长度/范围是否必填备注
    sn打印机序列号string50是

请求示例：

{
    "timestamp": 1670408954964,
    "appid": "13246***",
    "sign": "WbAMkch+Cs3xHMSyrV3xfZpXgxKgYEyUXCthLnD0xk4=",
    "biz": "{\"sn\":\"680002000***\"}"
}

  • 响应说明

    请求参数名称类型备注
    code响应码int0 表示接收打印请求成功
    message响应消息string响应码对应的说明
    data
    - status设备状态string设备状态 online: 在线 offline:离线 lacking: 缺纸

示例：

{
    "code": 0,
    "message": "成功",
    "data": {
        "status": "online"
    }
}

业务类型

业务码业务类型
1添加打印机
2删除打印机
3打印小票
4清除队列
5设备状态
6打印状态
Last Updated: