通用API开放文档

📘 通用API开放文档

📌 版本：v1.0📅 发布日期：2024-06-19🔐 国密SM3/SM4

🔌 一、接口基础规则

项目	说明
传输方式	HTTP
提交方式	POST
数据格式	表单提交，响应JSON
字符编码	UTF-8
签名算法	国密 SM3
加密算法	国密 SM4 (PKCS7填充 / ECB模式)
超时时间	6秒

📦 二、基础报文定义

🔹 请求公共参数

字段名	类型	必填	说明
requestId	String	Y	32位字母/数字，唯一请求标识
timestamp	String	Y	毫秒级时间戳
projectId	String	N	项目编号
sign	String	N	签名值（部分接口必填）

🔸 响应公共结构

字段名	类型	说明
msgCode	Integer	0=成功，其他=失败
requestId	String	原请求ID回传
timestamp	String	响应毫秒时间戳
data	Object/Array	业务数据主体

✍️ 三、签名流程（SM3）

🔄 签名生成5步骤：1️⃣ 参数名按字母顺序排序（不区分大小写）2️⃣ 拼接参数值（无间隔）3️⃣ 移除参数间空格4️⃣ 末尾追加appSecret5️⃣ 使用SM3算法计算哈希 → 获得sign

示例： 原始参数：projectId=00000678, requestId=ea0a3cef..., timestamp=1641523970076 排序后拼接：00000678ea0a3cef18c45e769f7136de7977db3f0000067823701641523970076 加上appSecret：... + 4F16D727D3DE6340 SM3签名结果：88af246cde85c3092913145c650d6100ea6b9aa8133592d411ec7a86badc8cb8

🔒 四、加密与解密说明（SM4）

🔐 国密SM4 (PKCS7Padding填充)请求时需将所有业务参数转为JSON字符串 → 使用appSecret作为密钥SM4加密 → 得到encryptScript字段提交。响应同理，需对encryptScript解密获得真实数据。

// 请求外层结构示例 {   "appId": "your_app_id",   "encryptVersion": "1",   "encryptScript": "332da172ce43871f43105908124ba4e8...",   "token": "xxx" }

📡 五、核心API接口

🔐 1. API开发者认证

地址：XXX/api/XXX/XXX/developerLoginMethod：POST说明：获取调用凭证 token，有效期7天。

{   "requestId": "ea0a3cef18c45e769f7136de7977db3f",   "sign": "70a21f42b4986da7f719fd1e697de97f",   "version": "1",   "timestamp": "1657878287222" }

{   "data": { "token": "T2JXAg7ChFyqlYjm0/Hi/MnyzAQ8FLWB9pylnR3D0KM=" },   "msgCode": 0,   "requestId": "ea0a3cef18c45e769f7136de7977db3f",   "timestamp": "1657878287987" }

📱 2. 获取设备信息

地址：/XXX/XXXX/XXX/getDeviceInfoMethod：POST说明：根据设备编码获取电梯/群控器列表。

请求字段	类型	必填	备注
requestId	String	Y	32位唯一ID
timestamp	String	Y	毫秒时间戳
deviceUnique	String	N	13位设备编码
appCode	String	Y	应用编码（开放平台获取）

// 请求示例 {   "requestId": "ea0a3cef18c45e769f7136de7977db3f",   "deviceUnique": "0000040210031",   "version": "1",   "timestamp": "1657878798514" }  // 响应示例 {   "data": [     {       "controllerDeviceName": "CLUSTER-32",       "controllerDeviceUnique": "0000040250032",       "deviceName": "测试1",       "deviceUnique": "0000040210031"     }   ],   "msgCode": 0,   "requestId": "ea0a3cef18c45e769f7136de7977db3f",   "timestamp": "1657878799405" }

⚠️ 六、错误码说明

错误码	含义
0	成功
1000	系统异常
2000	缺少必要参数
3000	参数错误
4017	token为空或无效，请重新认证
4018	开发者账号或密钥有误
401 (HTTP状态码)	token过期（业务外，需重新获取）

📌 七、注意事项

📌 业务须知• HTTP 401 表示token过期，需重新调用开发者认证接口。• 设备编码第9位含义：1= 云电梯，5= 群控器。• token有效期7天，过期后请求会返回HTTP 401。• 请求接口时，请务必在Header或表单中遵守加密规则。

💻 开发建议• 签名时如果没有现成排序函数，可以手动按参数名固定顺序（a-z）拼接。• 仅开发者认证接口需要传递appId，其他接口使用token认证。• 推荐使用SM4解密库（PKCS7Padding），注意key为appSecret的UTF-8字节。

🧩 八、代码片段（Java参考）

// SM3 签名 (使用Hutool) public static String getSDKV3Sign(Map<String, Object> params, String appsecret) {     // 1. 参数按key排序     List<String> keys = new ArrayList<>(params.keySet());     Collections.sort(keys, String.CASE_INSENSITIVE_ORDER);     StringBuilder sb = new StringBuilder();     for (String key : keys) {         sb.append(params.get(key) == null ? "" : params.get(key));     }     sb.append(appsecret);     return SmUtil.sm3(sb.toString()); }  // SM4 加密 (PKCS7Padding) public static String encryptHex(String data, String secretKey) {     SymmetricCrypto sm4 = new SM4(Mode.ECB, "PKCS7Padding", secretKey.getBytes(StandardCharsets.UTF_8));     return sm4.encryptHex(data); }  // SM4 解密 public static String decryptStr(String encryptHex, String secretKey) {     SymmetricCrypto sm4 = new SM4(Mode.ECB, "PKCS7Padding", secretKey.getBytes(StandardCharsets.UTF_8));     return sm4.decryptStr(encryptHex); }

📄 本文档基于开放平台通用API规范整理，完整版包含Postman示例及详细加密库。💡 如遇接入问题，请联系技术支持团队获取最新SDK。

通用API开放平台 | 国密标准 · 安全互联