MiFaZhan
82 lines
2.2 KiB
Markdown
82 lines
2.2 KiB
Markdown
---
|
||
title: 概览与鉴权
|
||
description: iotLCM V3 接口概览与鉴权说明
|
||
outline: deep
|
||
---
|
||
|
||
# 概览与鉴权
|
||
|
||
## 服务地址
|
||
|
||
```text
|
||
https://api.example.com
|
||
```
|
||
|
||
HTTP（`http://api.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 账号所属权限组关联。未登记资源、资源停用、账号未授权均拒绝访问，返回 `10014`；权限数据查询异常返回 `10016`（系统侧故障，不是授权问题）。
|
||
|
||
原 `/openapi/v3/common/*` 前缀已停止提供，调用返回 `404`，请使用 `/openapi/v3/change/*` 下的对应接口。
|