HTTP API 接入总览

了解业务流程、鉴权方式、签名算法、调用注意事项与 SDK 入口。

智巡平台 HTTP 接口是一个基于 HTTP 通信协议的对外开放接口 (以下简称 OpenAPI)，旨在为开发者提供第三方平台与智巡平台交互的能力，供第三方平台进行二次开发。

以下是 OpenAPI 的主要功能：

HTTP 通信：使用 HTTP 协议便于开发者和智巡平台进行交互。
认证和鉴权：智巡平台提供了认证和鉴权的机制，便于用户可以安全地调用 OpenAPI。
智巡平台核心功能：提供了智巡平台的核心功能，例如系统管理、监控管理、任务管理、设备管理、数据管理等功能。
详细的开发资料：提供了详细的开发文档、示例代码，满足客户端的业务需求。

智巡平台的 OpenAPI 和三方平台的交互架构如下：

业务流程

OpenAPI 的使用流程如下：

鉴权

签名进行鉴权

采用该鉴权方式，则所有的接口调用前必须先生成 签名参数，包含签名（sign）、时间戳（timestamp）、和随机字符串（nonce ）以及应用 key（appKey，用来标识用户身份）、应用密钥（secretKey）。

签名的生成逻辑如下：

将原始入参 (例如：dogCode, command, type, value)、当前时间的 时间戳（timestamp）， 随机字符串（nonce）、 应用key（appKey，标识客户身份）、 应用密钥（secretKey ）的键值对，键值对按照键的字母序从小到大排序，键值对以”键=值”的方式连接，键值对之间用“&”连接。并将该字符串做 MD5 摘要生成签名，并返回 16 进制字符串，再转成大写。注意：键值对中值为 null 或者为空的不要拼接进字符串。

#排序之后的字符串
sortStr=appKey=123&command=4&dogCode=001&nonce=kwnHHRwBTRqRaQpt9Krbp2vsjUN3aNvV&secretKey=kQwIOrYvnXmSDkwEiFngrKidMcdrgKor&timestamp=1770283714727&type=2&value=0.6
#生成的签名
sign=4B288C90527FF99B11D364E698744201

获取签名方法的示例代码如下（用户根据签名的生成逻辑自行开发）：

private static String getSign(Map<String, Object> params) {
    List<Map.Entry<String, Object>> entries = new ArrayList<Map.Entry<String, Object>>(params.entrySet());
    Collections.sort(entries, new Comparator<Map.Entry<String, Object>>() {
        public int compare(Map.Entry<String, Object> arg0, Map.Entry<String, Object> arg1) {
            return (arg0.getKey()).compareTo(arg1.getKey());
        }
    });
    StringBuilder sb = new StringBuilder();
    for (Map.Entry<String, Object> entry : entries) {
        String key = entry.getKey();
        Object value = entry.getValue();
        if (value == null || StrUtil.isBlankIfStr(value)) {
            continue;
        }
        if ("sign".equals(key)) {
            continue;
        }
        sb.append(key).append("=");
        sb.append(value);
        sb.append("&");
    }
    // 删除最后一个 &
    if (sb.length() > 0) {
        sb.deleteCharAt(sb.length() - 1);
    }
    String sortStr = sb.toString();
    //md5摘要生成签名，转成16进制，并转为大写即为sign
    String sign = DigestUtils.md5DigestAsHex(sortStr.getBytes()).toUpperCase();
    return sign;
}

原始入参：

{
  "dogCode": "001",
  "type": 2,
  "command": 4,
  "value": "0.6"
}

原始入参需要加上 时间戳（timestamp）， 随机字符串（nonce）、 应用key（appKey，标识客户身份）、 应用密钥（ secretKey），按 上述规则生成签名 sign，得到生成签名的入参如下：

{
  "dogCode": "001",
  "type": 2,
  "command": 4,
  "value": "0.6",
  "appKey": "123",
  "secretKey": "kQwIOrYvnXmSDkwEiFngrKidMcdrgKor",
  "timestamp": "1770355654092",
  "nonce": "g9undAg90K7xBCLUx2NXDDETwQbh9uQ1",
  "sign": "8700F12469316AF6382CE8664CC8C4B3"
}

appKey：标识第三方客户身份。
secretKey：参与签名生成，实际调用接口时可不传。
timestamp：当前时间戳，默认超过 15 分钟过期。
nonce：随机数，用于保证请求只能使用一次。
sign：按上述逻辑生成的签名。

然后使用带有签名参数的入参调用 OpenAPI 接口。流程图如下。

备注：智巡平台-系统管理-参数设置中可以配置签名的失效时间（http_sign_invalid_time，默认值 15 分钟）和是否允许重复 同一请求入参的请求（http_can_repeat）。如果不允许（值为false，默认值），所有的请求只能用一次，用多次会提示签名失效。

Token 进行鉴权

从 v1.3.1 版本开始，系统新增了基于 Token 的鉴权方式，提供更简洁的认证体验。

Token 模式下，客户端无需计算签名、时间戳和随机数，只需在请求头中携带有效的访问令牌即可。降低客户端集成复杂度。

在调用 OpenAPI 接口时，将 Token 放置在 HTTP 请求头中：

Header: X-Access-Token: <your_access_token>

注意事项

签名模式通过动态签名和 nonce 机制提供更强的防重放攻击能力，适合对安全性要求较高的场景。
Token 模式简化了集成流程，降低了客户端实现复杂度，适合快速开发和资源受限的设备。建议根据具体业务场景选择合适的鉴权方式
禁止同时使用两种模式：单个请求只能使用一种鉴权方式，不能同时提供 Token 和签名参数
鉴权相关的appkey，secretKey，accessToken需要通过授权码进行颁发，有效期受授权码整体有效期制约，过期后需要重新授权

二开需要信息

OpenAPI 二开接口地址：IP + 23288
RocketMQ NameServer: IP + 29876
鉴权需要的：Token 或者 appKey / secretKey

SDK

自智巡平台 v1.3.1 起，平台提供官方 Java SDK。

对于基于 JDK 17 和 Spring Boot 3 的二次开发，推荐使用官方 station-openapi-devkit。SDK 覆盖平台当前开放的 27 个 HTTP 接口，统一处理数据模型、分页、响应与异常，并支持签名和 Token 两种鉴权方式。

简化接入：封装 HTTP 调用、鉴权参数组装与响应解析，减少重复开发。
可靠调用：提供超时配置、受控重试、写入或控制结果未知提示和流式文件下载。
完整配套：提供双语文档、可运行的 Spring Boot Sample，以及可选的 RocketMQ 消息接入。

项目地址：station-openapi-devkit

Sample 地址：Spring Boot Sample

需要开始集成？进入 SDK 开发，查看项目资源、快速开始、鉴权配置及进阶指南。