chore: 初始开源发布

2026-10-22 15:16:43 +08:00
commit 92f239fcc4
114 changed files with 8018 additions and 0 deletions
@@ -0,0 +1,133 @@
+---
+title: 概览与鉴权
+description: iotLCM 旧版兼容接口概览与鉴权说明
+outline: deep
+---
+
+# 概览与鉴权
+
+本文档收录历史 `/route/open/*` 路径下仍在维护的兼容接口。鉴权通过请求体 `verify` 中的 `appId`、`password` 和 `timeStamp` 完成；`sign` 为历史兼容字段，当前服务不校验。
+
+这些接口由 iotLCM OpenAPI 服务实现并提供，与 V3 接口同域（`api.iotlcm.example.com`），仅请求路径与鉴权方式不同。
+
+## 服务地址
+
+```text
+https://api.iotlcm.example.com
+```
+
+完整请求 URL：
+
+```text
+https://api.iotlcm.example.com/route/open/{接口名}
+```
+
+## 统一鉴权
+
+以下各接口的“请求示例”均为完整 JSON 请求体，调用时请设置 `Content-Type: application/json`；`verify.sign` 可传空字符串 `""`。
+
+所有接口通过请求体 `verify` 字段鉴权：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| appId | string | 用于唯一标识请求 |
+| password | string | 密码 |
+| timeStamp | string | 时间戳，`"" + System.currentTimeMillis()` |
+| sign | string | 当前服务不校验，可传空字符串 `""`。 |
+
+### 历史签名规则（仅供参考）
+
+当前服务不要求计算签名，也无需提供 `accessKey`。以下为历史客户端示例中的签名算法，仅供维护已有签名逻辑时参考。
+
+```text
+appId={appId}&password={password}&timeStamp={timeStamp}&key={accessKey}
+```
+
+对拼接后的字符串计算 MD5，并将结果转为大写，即为 `sign`。`sign` 不参与签名计算；`accessKey` 仅用于签名，不放入请求体的 `verify` 字段。
+
+## 统一返回结构
+
+```json
+{
+    "status": 0,
+    "message": "",
+    "result": {}
+}
+```
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| status | number | 业务状态码，成功为 `0` |
+| message | string | 错误或提示信息 |
+| result | any | 业务数据 |
+
+## 公共字典
+
+卡状态编码（适用于 `cardInfo`、`simStatus`、`queryCardInfoList` 响应中的 `statusId` / `statusCode` / `status`）：
+
+| 编码 | 说明 |
+| --- | --- |
+| 1 | 库存 |
+| 2 | 可测试 |
+| 3 | 待激活 |
+| 4 | 已激活 |
+| 5 | 已停机 |
+| 6 | 预销户 |
+| 7 | 已销户 |
+| 8 | 未知 |
+
+## 请求案例
+
+以下为历史 Java 示例，保留原有 `verify` 块与 `sign` 的生成方式供参考。调用当前服务时，可直接设置 `verify.sign` 为 `""`，省略签名计算。
+
+```java
+// 服务器请求地址
+protected static String server_Ip = "https://api.iotlcm.example.com/route/open";
+// appId
+public static String appId = null;
+// 密钥密码
+public static String password = null;
+
+/**
+ * Sign 加密类
+ */
+public static String getSign(Map<String, Object> map, String key) {
+    List<String> list = new ArrayList<>(map.keySet());
+    Collections.sort(list);
+    StringBuffer sb = new StringBuffer();
+    for (int i = 0; i < list.size(); i++) {
+        String k = list.get(i);
+        String v = (String) map.get(k);
+        sb.append(k).append("=").append(v).append("&");
+    }
+    String signstr = sb.append("key=").append(key).toString();
+    String sign = MD5Util.MD5Encode(signstr).toUpperCase();
+    return sign;
+}
+
+public static void main(String[] args) {
+    Map<String, Object> map = new HashMap<>();
+    Map<String, Object> parmap = new HashMap<>();
+    Map<String, Object> verify = new HashMap<>();
+
+    String appId = "test";
+    String password = "uhbhkh223123";
+    String accessKey = "1234567896132";
+    String timeStamp = "" + System.currentTimeMillis();
+
+    verify.put("password", password);
+    verify.put("appId", appId);
+    verify.put("timeStamp", timeStamp);
+    verify.put("sign", getSign(verify, accessKey));
+
+    parmap.put("type", "iccid");
+    parmap.put("cardno", "89860423123123132135");
+
+    map.put("verify", verify);
+    map.put("Param", parmap);
+
+    server_Ip += "/cardInfo";
+    String result = HttpUtil.post(server_Ip, JSON.toJSONString(map));
+    System.out.println(result);
+}
+```
@@ -0,0 +1,389 @@
+---
+title: 查询类
+description: iotLCM 旧版兼容查询类接口
+outline: deep
+---
+
+# 查询类
+
+## 查询 SIM 详情
+
+```http
+POST /route/open/cardInfo
+```
+
+简要描述：查询物联卡基础信息。
+
+请求体：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| type | string | 查询类型：`msisdn` / `iccid` / `imsi` / `vid` |
+| cardno | string | 对应的查询值 |
+
+请求示例：
+
+```json
+{
+    "Param": {
+        "type": "iccid",
+        "cardno": "898604F4152391115474"
+    },
+    "verify": {
+        "timeStamp": "1784097284347",
+        "password": "YOUR_APP_SECRETebdebae9763127943f097758e029a0fdbc",
+        "appId": "YOUR_APP_ID",
+        "sign": ""
+    }
+}
+```
+
+响应结构：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| vid | string | 本地卡记录 ID |
+| msisdn | string | MSISDN |
+| iccid | string | ICCID |
+| imsi | string | IMSI |
+| imei | string | IMEI |
+| deptName | string | 当前归属组织名称 |
+| statusId | number | 状态编码，参考公共字典 |
+| packageId | string | 当前套餐编码 |
+| packageName | string | 当前套餐名称 |
+| used | number | 当前周期已用流量，单位 MB |
+| remaining | number | 当前周期剩余流量，单位 MB |
+| type | string | 卡类型名称 |
+| packetArr | array | 资费计划，未配置时返回 `null` |
+| remark | string | 备注 |
+| grouping | string | 分组，未配置时为空字符串 |
+| deliverDate | string | 发货日期，未配置时为空字符串 |
+| activateDate | string | 激活日期 |
+| expireTime | string | 到期时间 |
+
+响应示例：
+
+```json
+{
+    "status": 0,
+    "message": "",
+    "result": {
+        "vid": "3933",
+        "msisdn": "1441543605474",
+        "iccid": "898604F4152391115474",
+        "imsi": "460087436015474",
+        "imei": "",
+        "deptName": "示例企业",
+        "statusId": 4,
+        "packageId": "yd-100m-3y",
+        "packageName": "每月100m3年",
+        "used": 0.875,
+        "remaining": 99.125,
+        "type": "",
+        "packetArr": null,
+        "remark": "测试卡",
+        "grouping": "",
+        "deliverDate": "",
+        "activateDate": "2026-06-01",
+        "expireTime": "2029-01-31 23:59:59"
+    }
+}
+```
+
+## 查询 SIM 账期用量
+
+```http
+POST /route/open/simDataUsage
+```
+
+请求体：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| iccid | string | ICCID |
+
+请求示例：
+
+```json
+{
+    "Param": {
+        "iccid": "898604F4152391115474"
+    },
+    "verify": {
+        "timeStamp": "1784097284347",
+        "password": "YOUR_APP_SECRETebdebae9763127943f097758e029a0fdbc",
+        "appId": "YOUR_APP_ID",
+        "sign": ""
+    }
+}
+```
+
+响应结构：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| useUnit | string | 单位，当前为 `MB` |
+| useAmount | number | 当前周期已用流量 |
+
+响应示例：
+
+```json
+{
+    "status": 0,
+    "message": "",
+    "result": {
+        "useUnit": "MB",
+        "useAmount": 0.875
+    }
+}
+```
+
+## 查询 SIM 历史月用量
+
+```http
+POST /route/open/simDataUsageMonthly
+```
+
+请求体：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| iccid | string | ICCID |
+| dateTime | string | 查询月份，格式 `yyyyMM`（示例：`202509`） |
+
+请求示例：
+
+```json
+{
+    "Param": {
+        "iccid": "898604F4152391115474",
+        "dateTime": "202509"
+    },
+    "verify": {
+        "timeStamp": "1784097284347",
+        "password": "YOUR_APP_SECRETebdebae9763127943f097758e029a0fdbc",
+        "appId": "YOUR_APP_ID",
+        "sign": ""
+    }
+}
+```
+
+响应结构：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| useUnit | string | 单位，当前为 `MB` |
+| useAmount | number | 指定月份用量 |
+
+响应示例：
+
+```json
+{
+    "status": 0,
+    "message": "",
+    "result": {
+        "useUnit": "MB",
+        "useAmount": 0
+    }
+}
+```
+
+## 查询 SIM 状态
+
+```http
+POST /route/open/simStatus
+```
+
+请求体：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| iccid | string | ICCID |
+
+请求示例：
+
+```json
+{
+    "Param": {
+        "iccid": "898604F4152391115474"
+    },
+    "verify": {
+        "timeStamp": "1784097284347",
+        "password": "YOUR_APP_SECRETebdebae9763127943f097758e029a0fdbc",
+        "appId": "YOUR_APP_ID",
+        "sign": ""
+    }
+}
+```
+
+响应结构：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| statusMessage | string | 状态描述 |
+| statusCode | number | 状态编码，参考公共字典 |
+
+响应示例：
+
+```json
+{
+    "status": 0,
+    "message": "",
+    "result": {
+        "statusMessage": "已激活",
+        "statusCode": 4
+    }
+}
+```
+
+## 查询 SIM 在线会话
+
+```http
+POST /route/open/simSession
+```
+
+请求体：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| iccid | string | ICCID |
+
+请求示例：
+
+```json
+{
+    "Param": {
+        "iccid": "898604F4152391115474"
+    },
+    "verify": {
+        "timeStamp": "1784097284347",
+        "password": "YOUR_APP_SECRETebdebae9763127943f097758e029a0fdbc",
+        "appId": "YOUR_APP_ID",
+        "sign": ""
+    }
+}
+```
+
+响应结构：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| typeName | string | 运营商系统类型，未上报时为空字符串 |
+| imei | string | IMEI，未上报时为空字符串 |
+| statusMessage | string | 状态描述，未上报时为空字符串 |
+| statusCode | number | 状态码，未上报时为 `0` |
+| data | object | 会话详情 |
+
+`data` 字段：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| apnId | string | APN ID |
+| rat | string | 接入方式 |
+| ipv6 | string | IPv6 地址 |
+| ip | string | IPv4 地址 |
+| ipv6Prefix | string | IPv6 前缀 |
+| status | string | 在线状态 |
+| createDate | string | 会话创建时间 |
+
+响应示例：
+
+```json
+{
+    "status": 0,
+    "message": "",
+    "result": {
+        "typeName": "",
+        "imei": "",
+        "statusMessage": "",
+        "statusCode": 0,
+        "data": {
+            "apnId": "",
+            "rat": "",
+            "ipv6": "",
+            "ip": "",
+            "ipv6Prefix": "",
+            "status": "",
+            "createDate": ""
+        }
+    }
+}
+```
+
+## 查询卡列表信息
+
+```http
+POST /route/open/queryCardInfoList
+```
+
+请求体：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| iccid | `array<string>` | ICCID 列表，最多支持 100 个 |
+
+请求示例：
+
+```json
+{
+    "Param": {
+        "iccid": [
+            "898604F4152391115473",
+            "898604F4152391115474"
+        ]
+    },
+    "verify": {
+        "timeStamp": "1784097284347",
+        "password": "YOUR_APP_SECRETebdebae9763127943f097758e029a0fdbc",
+        "appId": "YOUR_APP_ID",
+        "sign": ""
+    }
+}
+```
+
+响应结构：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| iccid | string | ICCID |
+| activateDate | string | 激活日期 |
+| dueExpireTime | string | 到期时间 |
+| imei | string | IMEI |
+| imsi | string | IMSI |
+| msisdn | string | MSISDN |
+| type | string | 卡类型 |
+| remarks | string | 备注 |
+| status | number | 状态编码，参考公共字典 |
+
+响应示例：
+
+```json
+{
+    "status": 0,
+    "message": "",
+    "result": [
+        {
+            "iccid": "898604F4152391115473",
+            "activateDate": "2023-05-11",
+            "dueExpireTime": "",
+            "imei": "",
+            "imsi": "460087436015473",
+            "msisdn": "1441543605473",
+            "type": "",
+            "remarks": "测试卡",
+            "status": 4
+        },
+        {
+            "iccid": "898604F4152391115474",
+            "activateDate": "2026-06-01",
+            "dueExpireTime": "2029-01-31 23:59:59",
+            "imei": "",
+            "imsi": "460087436015474",
+            "msisdn": "1441543605474",
+            "type": "",
+            "remarks": "测试卡",
+            "status": 4
+        }
+    ]
+}
+```