Dai0814
1.9 KiB
1.9 KiB
title, description, outline
| title | description | outline |
|---|---|---|
| 概览与鉴权 | iotLCM V3 接口概览与鉴权说明 | deep |
概览与鉴权
服务地址
https://apiv3.5iot.cn
HTTP（http://apiv3.5iot.cn）仅为存量兼容保留，不做自动跳转，新接入请使用 HTTPS。
统一返回结构
V3 返回格式：
{
"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 路由前缀：
/openapi/v3/query
/openapi/v3/change
文档中的“请求示例”仅展示请求 body；调用 V3 POST 接口时，请设置 Content-Type: application/json 并将示例 JSON 作为请求体发送。请求路径和鉴权请求头见各接口说明。
除获取 token 接口外，其他 V3 接口需要请求头：
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 账号所属权限组关联。未配置资源时，按当前开放策略放行。