---
title: 概览与鉴权
description: iotLCM V3 接口概览与鉴权说明
outline: deep
---

# 概览与鉴权

## 服务地址

```text
https://apiv3.5iot.cn
```

HTTP（`http://apiv3.5iot.cn`）仅为存量兼容保留，不做自动跳转，新接入请使用 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 账号所属权限组关联。未配置资源时，按当前开放策略放行。