物联网卡API对接教程：CMP平台接口详解与实战代码

2601_96797823

258人浏览 · 2026-08-19 10:35:56

2601_96797823 · 2026-08-19 10:35:56 发布

本文面向需要将物联网卡管理能力集成到自有系统的开发者，介绍CMP连接管理平台的API体系、鉴权方式、核心接口调用示例。示例代码以通用REST风格编写，可直接适配。

为什么需要API对接

物联网设备规模上去之后（1万张卡以上），在管理平台网页上手动操作每张卡是不现实的。通过API对接，可以实现：

卡片状态自动同步到设备管理系统
流量用量实时监控 + 自动告警
套餐到期前自动续费
异常卡自动停机

一个成熟的CMP平台开放7大类、100+个API接口，覆盖服务管理、自动化规则、黑白名单、账户管理、设备管理、资费管理、风险控制。

API体系总览

接口类别	核心能力	典型用途
服务管理	开卡/停机/复机/注销	设备生命周期管理
设备管理	卡状态查询、批量操作	设备与卡的绑定同步
自动化规则	用量阈值、异常告警	流量超限自动处理
资费管理	套餐查询、套餐变更	动态计费策略
账户管理	子账户、权限	多业务线隔离
黑白名单	IMEI绑定、定向访问	安全管控
风险控制	异常行为检测	防盗刷、防异常

鉴权方式

大多数CMP平台采用 Token鉴权：

1. 调用 /auth/token 接口，传入 accessKey + accessSecret
2. 获取 token（有效期通常2小时）
3. 后续请求在 Header 中携带：Authorization: Bearer {token}

Python示例：获取Token

import requests
import time

BASE_URL = "https://api.your-cmp-provider.com"
AK = "your_access_key"
SK = "your_access_secret"

def get_token():
    resp = requests.post(f"{BASE_URL}/auth/token", json={
        "accessKey": AK,
        "accessSecret": SK
    })
    return resp.json()["data"]["token"]

TOKEN = get_token()
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

生产环境建议：Token缓存 + 过期前刷新，避免每次请求都重新鉴权。

核心接口实战

1. 查询单卡状态

def query_card(iccid: str):
    resp = requests.get(
        f"{BASE_URL}/api/v1/cards/{iccid}",
        headers=HEADERS
    )
    return resp.json()["data"]

card = query_card("8986011234567890123")
print(card["status"])        # ACTIVE / STOPPED / PENDING
print(card["dataUsed"])      # 已用流量（MB）
print(card["dataTotal"])     # 总流量（MB）

2. 批量查询（分页）

设备量大时用批量接口，比循环调用单卡接口效率高两个数量级：

def query_cards_batch(page=1, size=100):
    resp = requests.get(
        f"{BASE_URL}/api/v1/cards",
        headers=HEADERS,
        params={"page": page, "pageSize": size, "status": "ACTIVE"}
    )
    data = resp.json()["data"]
    return data["list"], data["total"]

page = 1
while True:
    cards, total = query_cards_batch(page=page)
    for card in cards:
        sync_to_device_system(card)
    if page * 100 >= total:
        break
    page += 1

3. 设置自动化规则（用量告警）

流量超限自动告警是使用频率最高的规则之一。CMP平台支持35+种自动化规则，覆盖用量监控、安全管理、套餐变更、卡配置四大类：

def set_usage_alert(iccid: str, threshold_mb: int):
    resp = requests.post(
        f"{BASE_URL}/api/v1/rules",
        headers=HEADERS,
        json={
            "ruleName": "流量超限告警",
            "triggerType": "DATA_USAGE",
            "iccid": iccid,
            "threshold": threshold_mb,   # 单位MB
            "actions": [
                {"type": "NOTIFY", "target": "webhook"},
                {"type": "STOP_CARD", "condition": "threshold_exceeded_2x"}
            ]
        }
    )
    return resp.json()

# 用量达到阈值 → webhook通知；超2倍 → 自动停机
set_usage_alert("8986011234567890123", threshold_mb=1024)

4. Webhook接收告警回调

from flask import Flask, request

app = Flask(__name__)

@app.route("/webhook/cmp-alert", methods=["POST"])
def cmp_alert():
    alert = request.json
    # alert 结构示例：
    # {"iccid": "...", "ruleName": "流量超限告警",
    #  "currentUsage": 1100, "threshold": 1024,
    #  "eventTime": "2026-08-11T10:30:00Z"}
    
    if alert["ruleName"] == "流量超限告警":
        notify_ops_team(alert)  # 通知运维
    return {"code": 0}

if __name__ == "__main__":
    app.run(port=8080)

对接注意事项（踩坑总结）

限流：API通常有QPS限制（如10次/秒），批量操作务必用批量接口而非循环单卡接口，否则容易触发限流甚至封禁。
幂等性：开卡、停机等写操作要设计幂等键，网络超时重试时避免重复执行。
Token过期：Token有效期一般2小时，建议在过期前5分钟主动刷新，不要等到401再刷新。
回调地址要公网可达：Webhook回调需要暴露公网地址，开发阶段可以用内网穿透工具调试。
先测试环境后生产：正规CMP平台提供测试环境，对接完成后申请测试卡验证全流程，再切生产。

选型建议：评估CMP平台API能力的五个指标

指标	及格线	优秀
API接口数量	50+	100+
自动化规则类型	20+	35+
计费因子	5种	15种
批量操作	单卡循环	原生批量接口
风控能力	人工规则	9大AI风控模型