RESTful API 接口

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

公共参数

签名生成

IoT 平台要求开发者对请求进行签名，平台在收到请求后进行签名的验证，如果签名验证不通过，平台将会拒绝处理该请求，并返回 401 Unauthorized

准备

1. 获取分配的appid和appsecret

构造签名串

非空参数按照ascii码从小到大排序，使用URL键值对的格式，拼接成签名串

非空参数组成部分：

1. 请求Body
2. Method
3. X-ES-SAAS-APPID
4. URL

比如请求json为：

{
  "Key1": "value1",
  "Key3": "value3",
  "Key2": "value2"
}

请求方法为：POST
请求地址：https://saas.excelsecu.com/openapi/v2/speakers/669600010002/receipts
则签名串为Key1=value1&Key2=value2&Key3=value3&Method=POST&URL=/openapi/v2/speakers/669600010002/receipts&X-ES-SAAS-APPID=123456

示例代码

public static String buildOrderSignStr(Map<String, String> params) {
    Set<String> keySet = params.keySet();
    String[] keyArray = keySet.toArray(new String[0]);
    Arrays.sort(keyArray);
    StringBuilder sb = new StringBuilder();
    for (String k : keyArray) {
        if ("sign".equals(k)) {
            continue;
        }
        if (StringsUtil.isEmpty(params.get(k))) {
            params.remove(k);
            continue;
        }
        String value = params.get(k);
        if (String.valueOf(value).trim().length() > 0) {
            sb.append(k).append("=").append(String.valueOf(value).trim()).append("&");
        }
    }
    return sb.substring(0, sb.length() - 1);
}

计算签名值

使用密钥，对待签名字符串进行SHA256WithHMAC签名，并进行 Base64 得到签名字符串

Base64(SHA256WithHMAC(signData, key));

示例代码

// data:  待签名字符串 String -> byte[], UTF-8
// key: appSecret，String -> byte[], UTF-8
// algorithm：固定值：HmacSHA256
public static String sign(byte[] data, byte[] key, String algorithm) throws Exception {
        SecretKeySpec secretKeySpec = new SecretKeySpec(key, algorithm);
        Mac mac = Mac.getInstance(algorithm);
        mac.init(secretKeySpec);
        return Base64.getEncoder().encodeToString(mac.doFinal(data));
}

设置 HTTP 头

API请求通过HTTP Authorization头来传递签名。 Authorization由认证类型，签名信息两个个部分组成，同时通过X-ES-SAAS-APPID请求头标识调用方

Authorization: 认证类型 签名值
X-ES-SAAS-APPID: APPID

认证类型目前为：ESIOT-HMAC-SHA256

回调通知

提供回调地址，联系技术支持人员进行应用的回调地址设置

回调响应需在3s内完成{"Message": "OK"}响应。如未完成响应将每隔3秒重试3次请求。

为了安全起见，强烈建议对回调请求进行验签处理，签名值通过Authorization请求头传递，签名规则参考上文。如需设置IP白名单，可将106.52.136.52添加到白名单列表

Content参数值可能会比较复杂，在参与签名时直接当字符串处理，无需做JSON反序列化。即：待签名字符串为Content={\"Code\":\"abcd\"}&Method=POST&NotifyTime=1703820611151&Type=SCAN&URL=YOUR_CALLBACK_PATH&X-ES-SAAS-APPID=YOUR_APP_ID

参考值

APPID: 12345678

APP_SECRET: 83abf5ed6dd27f77dc80874b394ea3049e86b4ccd17f5bb6154c31f240450b66

待签名字符串：Content={\"Code\":\"abcd\"}&Method=POST&NotifyTime=1703820611151&SN=abcd&Type=SCAN&URL=/test&X-ES-SAAS-APPID=12345678

签名值：Lbrd5X69lx2Z2UFKttkhj0E338C8ySM3VFyhUqdp6d4=

扫码通知

回调请求参数

{
  "Content":"{\"Code\":\"abcd\"}",
  "SN": "abcd",
  "Type":"SCAN",
  "NotifyTime": 1703820611151
}

参数含义

云音箱

1. 推送云音箱收款消息

请求地址

https://saas.excelsecu.com/openapi/v2/speakers/:speaker/receipts

:speaker 填入要播报的设备SN

请求参数

发起请求时，需携带公共参数

参数说明

• 当播报类型为语音模版时，Money 和 BroadcastType 不能为空
• 当播报类型为 TTS 类型时，VoiceMsg 不能为空
• 语音模版和 TTS 同时存在时，只播报 TTS 语音
• 最小播报金额为1分，最大播报金额不超过1千万

请求头

返回参数