三种对接方式
按您的系统能力，挑一种最省事的
三种方式覆盖不同技术栈和实时性要求，可以只用一种，也可以组合使用。
REST API
主动拉取设备列表、实时快照与历史序列。适合做报表同步、定时任务和后台管理集成。
- OAuth2 客户端凭证鉴权
- JSON 输入输出，分页与游标齐全
- 按设备、按批次、按时间范围查询
MQTT 订阅
长连接订阅实时上报与告警事件，秒级到达。适合实时大屏、风控系统和自研告警引擎。
- TLS 双向认证，一机一密同样适用
- 按设备 / 按事件类型的主题过滤
- 支持 QoS1，断线重连自动补订阅
Webhook 回调
发生告警或状态变化时，我们主动 POST 到您的接口。您不需要开放任何公网入口。
- 签名校验，防伪造请求
- 失败自动重试，最多 5 次
- 支持钉钉 / 企业微信 / 飞书机器人直推
上手示例
三步拿到第一包数据
1 · 获取访问令牌
curl -X POST https://api.zhidiancloud.com/v1/oauth/token \
-H "Content-Type: application/json" \
-d '{
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"grant_type": "client_credentials"
}'
# 返回
{ "access_token": "eyJhbGciOi...", "expires_in": 7200 }2 · 查询设备实时快照
curl https://api.zhidiancloud.com/v1/devices/BT24080001/snapshot \
-H "Authorization: Bearer eyJhbGciOi..."
# 返回
{
"sn": "BT24080001",
"online": true,
"voltage": 52.14,
"current": -10.8,
"soc": 86,
"soh": 98.4,
"temp_max": 31.2,
"cell_delta_mv": 18,
"location": { "lng": 114.06, "lat": 22.54 },
"updated_at": "2026-09-23T11:12:04+08:00"
}3 · 订阅实时上报（MQTT）
# 主题：device/{sn}/telemetry
{
"msg_id": "9f2c1a",
"sn": "BT24080001",
"ts": 1758601924000,
"cells": [3.262, 3.261, 3.264, ...],
"voltage": 52.14,
"current": -10.8,
"soc": 86,
"temp": [30.4, 31.2, 29.8],
"mos": { "chg": true, "dsg": true },
"alarm": []
}3' · 接收告警回调（Webhook）
POST https://your-server.com/hook/bms
X-ZD-Signature: sha256=9a7c...
{
"event": "alarm.raised",
"sn": "BT24080001",
"level": "warning", // info|warning|critical
"code": "TEMP_HIGH",
"value": 62.4,
"threshold": 60,
"raised_at": "2026-09-23T11:12:04+08:00"
}
以上为接口形态示意，完整字段、错误码与限流规则请在开发者中心查阅；
申请测试密钥后可在沙箱环境直接联调。
接口清单（节选）
常用接口一览
完整清单与变更日志见开发者中心。
| 方法 | 路径 | 说明 | 限流 |
|---|---|---|---|
| GET | /v1/devices | 分页查询设备列表，支持按批次、状态、归属筛选 | 60 次/分 |
| GET | /v1/devices/{sn} | 查询单台设备档案与绑定关系 | 120 次/分 |
| GET | /v1/devices/{sn}/snapshot | 查询实时快照 | 300 次/分 |
| GET | /v1/devices/{sn}/history | 查询历史序列，支持字段选择与降采样 | 60 次/分 |
| POST | /v1/devices/{sn}/commands | 下发指令：锁电 / 解锁 / 限流 / 参数 / 重启 | 30 次/分 |
| POST | /v1/devices/batch/import | 批量建档，用于产线导入 | 10 次/分 |
| GET | /v1/alarms | 查询告警记录与处理状态 | 60 次/分 |
| POST | /v1/ota/tasks | 创建 OTA 升级任务，支持灰度分批 | 10 次/分 |
| GET | /v1/passport/{sn} | 导出电池护照所需数据集 | 30 次/分 |
嵌入式 SDK
如果您的板子想直接对接云端
不需要采购我们的模组也可以接入。SDK 提供连接管理、鉴权、数据打包与重传逻辑， 跑在您的 MCU 或网关上，直接和云平台通信。
- 轻量实现：C 语言实现，适合资源受限的 MCU
- 协议开放：报文格式公开，不依赖我们的固件
- 参考实现：提供主流芯片平台的移植示例
- 联调支持：对接期间有工程师陪跑，直到跑通
对接前需要确认的四件事
- 您的系统能主动调用 HTTP，还是需要我们用 Webhook 推
- 实时性要求：秒级订阅，还是分钟级定时拉取即可
- 需要哪些字段：只取 SOC 与告警，还是全量单体电压
- 网络边界：您的服务是否可直接访问公网
这四件事定下来，接口方案基本就能定。通常 1–2 个工作日可完成联调。
常见问题
关于开放能力，客户最常问的几件事
完全开放，接口与云端版一致。私有化部署只是运行环境变化，开放能力不做任何裁剪，也不会因此额外收费。
接口按版本号管理，v1 保持向后兼容。新增字段不影响既有解析，不兼容变更会走新版本号并提前至少 3 个月通知，旧版本继续保留不少于 12 个月。
已对接过多个地方监管与消防平台。各地接口规范不统一，我们会按目标平台要求做数据映射与上报适配，具体需要您提供对接规范文档后评估。
有默认限流以保证平台稳定性，上表列出了各接口的默认额度。如果您的业务需要更高额度，提交说明后我们可以为指定密钥单独提额。
有。正式客户的对接期会安排对接工程师，通过专属群响应问题。上线后转入常规技术支持通道，按合同约定时效处理。