chore: 初始开源发布

2026-10-22 15:16:43 +08:00
commit 92f239fcc4
114 changed files with 8018 additions and 0 deletions
@@ -0,0 +1,79 @@
+---
+title: 概览与鉴权
+description: iotLCM V3 接口概览与鉴权说明
+outline: deep
+---
+
+# 概览与鉴权
+
+## 服务地址
+
+```text
+https://api.iotlcm.example.com
+```
+
+HTTP（`http://api.iotlcm.example.com`）仅为存量兼容保留，不做自动跳转，新接入请使用 HTTPS。
+
+## 统一返回结构
+
+V3 返回格式：
+
+```json
+{
+    "code": 0,
+    "message": "",
+    "data": {},
+    "error": null
+}
+```
+
+字段说明：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| code | number | 业务状态码，成功为 `0` |
+| message | string | 错误或提示信息 |
+| data | object | 业务数据 |
+| error | any | 错误信息字段 |
+
+## 公共字典
+
+卡状态编码
+
+| 编码 | 说明 |
+| :-: | :-: |
+| 0 | 未知 |
+| 1 | 待激活 |
+| 2 | 已激活 |
+| 4 | 停机 |
+| 6 | 可测试 |
+| 7 | 库存 |
+| 8 | 预销户 |
+| 9 | 已销户 |
+
+## V3 鉴权
+
+V3 路由前缀：
+
+```text
+/openapi/v3/query
+/openapi/v3/change
+```
+
+文档中的“请求示例”仅展示请求 body；调用 V3 POST 接口时，请设置 `Content-Type: application/json` 并将示例 JSON 作为请求体发送。请求路径和鉴权请求头见各接口说明。
+
+除获取 token 接口外，其他 V3 接口需要请求头：
+
+```http
+X-Access-Token: {accessToken}
+```
+
+也支持传入带 `Bearer ` 前缀的值，服务端会去掉前缀。
+
+::: info 重要：请求体中的 appId 必须正确
+先调用 `/openapi/v3/query/token` 获取 token，接口响应中会返回 `data.appId`（客户组织编码，格式如 `CUS-202601-0001`）。**后续调用所有 V3 接口时，请求体都必须传入这个 `appId` 值**，且要与 token 所属的客户组织匹配，否则返回 `code: 61 "登录已过期"`。
+
+⚠️ **不要把 `appKey`（API 账号标识）当成 `appId` 使用。** `appKey` 只用于获取 token。
+:::
+
+权限控制：调用接口需具备对应接口资源的访问权限，权限与 API 账号所属权限组关联。未配置资源时，按当前开放策略放行。