iotlcm/docs/openapi/v3/query.md

---
title: 查询类
description: iotLCM V3 查询类接口
outline: deep
---

# 查询类

## 单卡基本信息查询

```http
POST /openapi/v3/query/sim-info
```

请求头：

```http
X-Access-Token: {accessToken}
```

请求体：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| appId | string | 客户组织编码 |
| iccid | string | ICCID，`iccid`、`msisdn`、`imsi` 至少传一个 |
| msisdn | string | MSISDN |
| imsi | string | IMSI |

请求示例：

```json
{
    "appId": "CUS-202601-0001",
    "iccid": "898604F4152391115474"
}
```

响应结构：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `data.iccid` | string | ICCID |
| `data.msisdn` | string | MSISDN |
| `data.imsi` | string | IMSI |
| `data.imei` | string | IMEI |
| `data.username` | string | 当前归属客户/组织名称 |
| `data.location` | string | 归属地 |
| `data.planCategory` | string | 套餐分类 |
| `data.currentPlanName` | string | 当前套餐名称 |
| `data.plangroup` | string | 套餐分组，未配置时为空字符串 |
| `data.planid` | string | 当前套餐编码 |
| `data.appid` | string | 归属客户组织编码 |
| `data.allowPlanChange` | number | 是否允许改套餐，未启用时返回 `0` |
| `data.lastSyncTime` | string | 状态最后同步时间 |
| `data.accessType` | string | 接入方式 |
| `data.cardStatus` | string | 卡状态 |
| `data.cardType` | any | 卡类型 |
| `data.networkType` | any | 网络类型 |
| `data.activationDate` | string | 出库/激活相关日期 |
| `data.activeDate` | string | 当前套餐生效日期 |
| `data.validityPeriod` | number | 有效期，按月份计算 |
| `data.expiryDate` | string | 当前套餐到期日期 |
| `data.testPeriod` | number | 测试期，未启用时返回 `0` |
| `data.testPeriodExpiryDate` | any | 测试期到期时间，未启用时返回 `null` |
| `data.silentPeriod` | number | 沉默期，未启用时返回 `0` |
| `data.silentPeriodExpiryDate` | any | 沉默期到期时间，未启用时返回 `null` |
| `data.dataService` | number | 数据服务状态，`1` 启用，`0` 禁用 |
| `data.planData` | number | 套餐总流量，单位 MB |
| `data.usedData` | number | 已用流量，单位 MB |
| `data.remainingData` | string | 剩余流量，单位 MB |
| `data.smsService` | number | 短信服务状态 |
| `data.planSMS` | number | 套餐短信总量 |
| `data.usedSMS` | number | 已用短信数 |
| `data.remainingSMS` | string | 剩余短信数 |
| `data.voiceService` | number | 语音服务状态 |
| `data.planMinutes` | number | 套餐语音分钟数 |
| `data.usedMinutes` | number | 已用语音分钟数 |
| `data.remainingMinutes` | string | 剩余语音分钟数 |
| `data.internationalRoamingService` | number | 国际漫游服务状态 |
| `data.planInternationalData` | number | 国际漫游套餐流量 |
| `data.usedInternationalData` | number | 已用国际漫游流量 |
| `data.remainingInternationalData` | string | 剩余国际漫游流量 |
| `data.description` | any | 备注描述，未填写时返回 `null` |

响应示例：

```json
{
    "code": 0,
    "message": "",
    "data": {
        "iccid": "898604F4152391115474",
        "imei": "",
        "username": "示例企业",
        "location": "370100000000",
        "planCategory": "移动小流量",
        "currentPlanName": "每月100m3年",
        "plangroup": "",
        "planid": "yd-100m-3y",
        "appid": "CUS-202601-0001",
        "allowPlanChange": 0,
        "lastSyncTime": "2026-06-24 00:03:19",
        "accessType": "",
        "cardStatus": "已激活",
        "cardType": "",
        "networkType": "",
        "activationDate": "2026-06-01",
        "activeDate": "2026-06-01",
        "validityPeriod": 32,
        "expiryDate": "2029-01-31",
        "testPeriod": 0,
        "testPeriodExpiryDate": null,
        "silentPeriod": 0,
        "silentPeriodExpiryDate": null,
        "dataService": 1,
        "planData": 100,
        "usedData": 0.875,
        "remainingData": "99.1",
        "smsService": 1,
        "planSMS": 0,
        "usedSMS": 0,
        "remainingSMS": "0",
        "voiceService": 1,
        "planMinutes": 0,
        "usedMinutes": 0,
        "remainingMinutes": "0",
        "internationalRoamingService": 0,
        "planInternationalData": 0,
        "usedInternationalData": 0,
        "remainingInternationalData": "0.0",
        "description": null
    },
    "error": null
}
```


## 单卡状态信息查询

```http
POST /openapi/v3/query/sim-status
```

请求头：

```http
X-Access-Token: {accessToken}
```

请求体：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `appId` | string | token 返回的客户组织编码 |
| `iccid` | string | ICCID；与 `msisdn`、`imsi` 至少传一个 |
| `msisdn` | string | MSISDN |
| `imsi` | string | IMSI |

请求示例：

```json
{
    "appId": "CUS-202601-0001",
    "iccid": "898604F4152391115474"
}
```

响应结构：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | number | 业务状态码，成功为 `0` |
| `message` | string | 错误或提示信息 |
| `data.iccid` | string | ICCID，查询命中时返回 |
| `data.lifeCycle` | number | 卡生命周期状态编码 |
| `data.lifeCycleName` | string | 卡生命周期状态文字 |
| `error` | any | 错误信息字段 |

响应示例（查询命中）：

```json
{
    "code": 0,
    "message": "",
    "data": {
        "iccid": "898604F4152391115474",
        "lifeCycle": 2,
        "lifeCycleName": "已激活"
    },
    "error": null
}
```

响应示例（未命中）：

```json
{
    "code": 50,
    "message": "查询sim卡信息失败，请确认ICCID，MSISDN，IMSI是否正确",
    "data": {},
    "error": null
}
```

`lifeCycleName` 为状态文字；`lifeCycle` 是此接口的状态编码，不要与其他接口或字典中的状态编码混用。

## 单卡流量限额查询

```http
POST /openapi/v3/query/sim-limit
```

请求体：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `appId` | string | 客户组织编码 |
| `iccid` | string | ICCID |
| `msisdn` | string | MSISDN |
| `imsi` | string | IMSI |

请求示例：

```json
{
    "appId": "CUS-202601-0001",
    "iccid": "898604F4152391115474"
}
```

响应字段：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `data.trafficCutoffStatus` | integer | 达量断网状态：`0` 未配置、`1` 已开启、`2` 已关闭 |
| `data.trafficCutoffName` | string | 状态名称，返回 `未配置`、`已开启` 或 `已关闭` |
| `data.trafficCutoffThreshold` | number | 达量断网阈值，单位 MB |

响应示例：

```json
{
    "code": 0,
    "message": "",
    "data": {
        "trafficCutoffStatus": 1,
        "trafficCutoffName": "已开启",
        "trafficCutoffThreshold": 1024
    },
    "error": null
}
```

## 单卡实时终端 IMEI 查询

```http
POST /openapi/v3/query/sim-imei
```

请求体：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| appId | string | 客户组织编码 |
| iccid | string | ICCID |
| msisdn | string | MSISDN |
| imsi | string | IMSI |

请求示例：

```json
{
    "appId": "CUS-202601-0001",
    "iccid": "898604F4152391115474"
}
```

响应结构：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `data.imei` | string | IMEI |

响应示例：

```json
{
    "code": 0,
    "message": "",
    "data": {
        "imei": ""
    },
    "error": null
}
```

## 单卡本月流量使用量查询

```http
POST /openapi/v3/query/sim-usage
```

请求体：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| appId | string | 客户组织编码 |
| iccid | string | ICCID |
| msisdn | string | MSISDN |
| imsi | string | IMSI |

请求示例：

```json
{
    "appId": "CUS-202601-0001",
    "iccid": "898604F4152391115474"
}
```

响应结构：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `data.useUnit` | string | 流量单位，固定为 `MB` |
| `data.useAmount` | number | 当前周期已用流量 |

响应示例：

```json
{
    "code": 0,
    "message": "",
    "data": {
        "useUnit": "MB",
        "useAmount": 0.875
    },
    "error": null
}
```

## 物联网卡批量状态信息查询

```http
POST /openapi/v3/query/sim-status-batch
```

单次最多查询 1000 张卡。每张卡至少提供 `iccid`、`msisdn`、`imsi` 中的一个；同一条记录提供多个标识时，必须对应同一张卡。

请求头：

```http
X-Access-Token: {accessToken}
```

请求体：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `appId` | string | token 返回的客户组织编码，示例为 `CUS-202601-0001` |
| `cards` | array | 卡片标识列表；示例包含 3 张卡，单次最多 1000 项 |
| `cards[].iccid` | string | ICCID；示例中每项均使用 ICCID，实际调用时与 `msisdn`、`imsi` 至少传一个 |
| `cards[].msisdn` | string | MSISDN，可代替 ICCID 标识卡片 |
| `cards[].imsi` | string | IMSI，可代替 ICCID 标识卡片 |

请求示例：

```json
{
    "appId": "CUS-202601-0001",
    "cards": [
        {
            "iccid": "898604F4152391115473"
        },
        {
            "iccid": "898604F4152391115474"
        },
        {
            "iccid": "8986112223600594371"
        }
    ]
}
```

响应结构：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | number | 业务状态码，成功为 `0` |
| `message` | string | 错误或提示信息 |
| `data.total` | integer | 本次请求的卡片总数；示例为 `3` |
| `data.matchedCount` | integer | 匹配成功的卡片数量；示例为 `3` |
| `data.notFoundCount` | integer | 未匹配成功的卡片数量；示例为 `0` |
| `data.items` | array | 每张卡的查询结果；示例依次对应请求中的 3 张卡 |
| `data.items[].matched` | boolean | 是否匹配成功；示例中均为 `true` |
| `data.items[].iccid` | string | 匹配成功时返回的 ICCID |
| `data.items[].lifeCycle` | number | 匹配成功时返回的卡生命周期状态编码；示例中 `2` 为已激活 |
| `data.items[].lifeCycleName` | string | 匹配成功时返回的卡生命周期状态文字 |
| `data.items[].errorCode` | string | 匹配失败时返回的错误码；示例均匹配成功，因此未返回 |
| `data.items[].errorMessage` | string | 匹配失败时返回的错误说明；示例均匹配成功，因此未返回 |
| `error` | any | 错误信息字段 |

响应示例：

```json
{
    "code": 0,
    "message": "",
    "data": {
        "total": 3,
        "matchedCount": 3,
        "notFoundCount": 0,
        "items": [
            {
                "matched": true,
                "iccid": "898604F4152391115473",
                "lifeCycle": 2,
                "lifeCycleName": "已激活"
            },
            {
                "matched": true,
                "iccid": "898604F4152391115474",
                "lifeCycle": 2,
                "lifeCycleName": "已激活"
            },
            {
                "matched": true,
                "iccid": "8986112223600594371",
                "lifeCycle": 2,
                "lifeCycleName": "已激活"
            }
        ]
    },
    "error": null
}
```

## 物联网卡批量流量信息查询

```http
POST /openapi/v3/query/sim-usage-batch
```

单次最多查询 1000 张卡。请求体需传入 `appId` 和 `cards` 数组；数组中的每张卡至少提供 `iccid`、`msisdn`、`imsi` 中的一个。同一条记录提供多个标识时，必须对应同一张卡。

请求头：

```http
X-Access-Token: {accessToken}
```

请求体：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `appId` | string | token 返回的客户组织编码 |
| `cards` | array | 卡片标识列表，单次最多 1000 项 |
| `cards[].iccid` | string | ICCID；每项与 `msisdn`、`imsi` 至少传一个 |
| `cards[].msisdn` | string | MSISDN，可代替 ICCID 标识卡片 |
| `cards[].imsi` | string | IMSI，可代替 ICCID 标识卡片 |

请求示例：

```json
{
    "appId": "CUS-202601-0001",
    "cards": [
        {
            "iccid": "898604F4152391115474"
        },
        {
            "iccid": "898604F4152391115473"
        },
        {
            "iccid": "8986112223600594371"
        }
    ]
}
```

响应结构（流量单位为 MB）：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | number | 业务状态码，成功为 `0` |
| `message` | string | 错误或提示信息 |
| `data.total` | integer | 本次请求的卡片总数 |
| `data.matchedCount` | integer | 匹配成功的卡片数量 |
| `data.notFoundCount` | integer | 未匹配成功的卡片数量 |
| `data.items` | array | 每张卡的查询结果 |
| `data.items[].matched` | boolean | 是否匹配成功 |
| `data.items[].iccid` | string | 匹配成功时返回的 ICCID |
| `data.items[].useUnit` | string | 流量单位，示例为 `MB` |
| `data.items[].useAmount` | number | 流量使用量 |
| `data.items[].errorCode` | string | 匹配失败时返回的错误码；匹配成功时不返回 |
| `data.items[].errorMessage` | string | 匹配失败时返回的错误说明；匹配成功时不返回 |
| `error` | any | 错误信息字段 |

响应示例：

```json
{
    "code": 0,
    "message": "",
    "data": {
        "total": 3,
        "matchedCount": 3,
        "notFoundCount": 0,
        "items": [
            {
                "matched": true,
                "iccid": "898604F4152391115474",
                "useUnit": "MB",
                "useAmount": 0.875
            },
            {
                "matched": true,
                "iccid": "898604F4152391115473",
                "useUnit": "MB",
                "useAmount": 12.5
            },
            {
                "matched": true,
                "iccid": "8986112223600594371",
                "useUnit": "MB",
                "useAmount": 36.25
            }
        ]
    },
    "error": null
}
```

## 物联网卡批量 IMEI 查询

```http
POST /openapi/v3/query/sim-imei-batch
```

单次最多查询 1000 张卡。每张卡至少提供 `iccid`、`msisdn`、`imsi` 中的一个；同一条记录提供多个标识时，必须对应同一张卡。

请求头：

```http
X-Access-Token: {accessToken}
```

请求体：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `appId` | string | token 返回的客户组织编码 |
| `cards` | array | 卡片标识列表，单次最多 1000 项 |
| `cards[].iccid` | string | ICCID；每项与 `msisdn`、`imsi` 至少传一个 |
| `cards[].msisdn` | string | MSISDN，可代替 ICCID 标识卡片 |
| `cards[].imsi` | string | IMSI，可代替 ICCID 标识卡片 |

请求示例：

```json
{
    "appId": "CUS-202601-0001",
    "cards": [
        {
            "iccid": "898604F4152391115474"
        },
        {
            "iccid": "898604F4152391115473"
        },
        {
            "msisdn": "1441543605474"
        }
    ]
}
```

响应结构：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | number | 业务状态码，成功为 `0` |
| `message` | string | 错误或提示信息 |
| `data.total` | integer | 本次请求的卡片总数 |
| `data.matchedCount` | integer | 匹配成功的卡片数量 |
| `data.notFoundCount` | integer | 未匹配成功的卡片数量 |
| `data.items` | array | 每张卡的查询结果，顺序与请求中的 `cards` 一致 |
| `data.items[].matched` | boolean | 是否匹配成功 |
| `data.items[].iccid` | string | 匹配成功时返回的 ICCID |
| `data.items[].imei` | string | IMEI；尚未采集到该卡 IMEI 时为空字符串 |
| `data.items[].errorCode` | string | 匹配失败时返回的错误码；匹配成功时不返回 |
| `data.items[].errorMessage` | string | 匹配失败时返回的错误说明；匹配成功时不返回 |
| `error` | any | 错误信息字段 |

响应示例：

```json
{
    "code": 0,
    "message": "",
    "data": {
        "total": 3,
        "matchedCount": 2,
        "notFoundCount": 1,
        "items": [
            {
                "matched": true,
                "iccid": "898604F4152391115474",
                "imei": ""
            },
            {
                "matched": true,
                "iccid": "898604F4152391115473",
                "imei": "865466070817587"
            },
            {
                "matched": false,
                "imei": "",
                "errorCode": "CARD_NOT_FOUND",
                "errorMessage": "卡片不存在或无权限"
            }
        ]
    },
    "error": null
}
```

## 物联网卡批量限额信息查询

```http
POST /openapi/v3/query/traffic-cutoff-config
```

根据卡片标识批量查询当前达量断网配置。`cards[]` 中的 `iccid`、`msisdn`、`imsi` 三码至少传一个。

请求体：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `appId` | string | 客户组织编码 |
| `cards` | array | 卡片标识列表 |
| `cards[].iccid` | string | ICCID |
| `cards[].msisdn` | string | MSISDN |
| `cards[].imsi` | string | IMSI |
| `includeUsage` | boolean | 是否返回套餐和流量使用信息 |

请求示例：

```json
{
    "appId": "CUS-202601-0001",
    "cards": [
        {
            "iccid": "898604F4152391115474"
        },
        {
            "iccid": "898604F4152391115475"
        },
        {
            "iccid": "898604F4152391115476"
        }
    ],
    "includeUsage": true
}
```

响应结构：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `data.total` | integer | 请求中的卡片数量 |
| `data.matchedCount` | integer | 匹配成功的卡片数量 |
| `data.notFoundCount` | integer | 未匹配成功的卡片数量 |
| `data.items` | array | 每张卡的查询结果 |
| `data.items[].matched` | boolean | 是否匹配成功 |
| `data.items[].iccid` | string | 平台返回的 ICCID |
| `data.items[].trafficCutoffStatus` | integer | 达量断网状态：`0` 未配置、`1` 已开启、`2` 已关闭 |
| `data.items[].trafficCutoffStatusName` | string | 达量断网状态名称 |
| `data.items[].trafficCutoffThreshold` | number | 达量断网阈值，单位 MB |
| `data.items[].trafficCutoffThresholdUnit` | string | 阈值单位，固定为 `MB` |
| `data.items[].packageTotalFlowMb` | number | 套餐总流量;`includeUsage=true` 时返回 |
| `data.items[].usedFlowMb` | number | 已用流量;`includeUsage=true` 时返回 |
| `data.items[].remainingFlowMb` | number | 剩余流量;`includeUsage=true` 时返回 |
| `data.items[].errorCode` | string | 匹配失败时返回 |
| `data.items[].errorMessage` | string | 匹配失败时返回 |

响应示例：

以下状态、阈值和流量数值用于展示批量响应结构，实际结果以接口查询为准。

```json
{
    "code": 0,
    "message": "",
    "data": {
        "total": 3,
        "matchedCount": 3,
        "notFoundCount": 0,
        "items": [
            {
                "matched": true,
                "iccid": "898604F4152391115474",
                "trafficCutoffStatus": 0,
                "trafficCutoffStatusName": "未配置",
                "trafficCutoffThreshold": 0,
                "trafficCutoffThresholdUnit": "MB",
                "packageTotalFlowMb": 0,
                "usedFlowMb": 18,
                "remainingFlowMb": 0
            },
            {
                "matched": true,
                "iccid": "898604F4152391115475",
                "trafficCutoffStatus": 1,
                "trafficCutoffStatusName": "已开启",
                "trafficCutoffThreshold": 100,
                "trafficCutoffThresholdUnit": "MB",
                "packageTotalFlowMb": 200,
                "usedFlowMb": 80,
                "remainingFlowMb": 120
            },
            {
                "matched": true,
                "iccid": "898604F4152391115476",
                "trafficCutoffStatus": 2,
                "trafficCutoffStatusName": "已关闭",
                "trafficCutoffThreshold": 50,
                "trafficCutoffThresholdUnit": "MB",
                "packageTotalFlowMb": 100,
                "usedFlowMb": 30,
                "remainingFlowMb": 70
            }
        ]
    },
    "error": null
}
```

## 批次状态查询

```http
POST /openapi/v3/query/batch-status
```

根据指定批次号查询异步处理状态，支持续费、达量断网等异步批次。

请求参数：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `appId` | string | 客户组织编码 |
| `batchNo` | string | 异步 API 返回的批次号 |

请求示例：

```json
{
    "appId": "CUS-202601-0001",
    "batchNo": "REN20260910153546001000001"
}
```

响应结构：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `data.batchNo` | string | 请求中的批次号 |
| `data.batchAsyncStatus` | integer | 异步状态：`0` 已创建、`1` 待处理、`2` 处理中、`3` 成功、`4` 失败、`5` 部分成功 |

响应示例：

```json
{
    "code": 0,
    "message": "",
    "data": {
        "batchNo": "REN20260910153546001000001",
        "batchAsyncStatus": 3
    },
    "error": null
}
```