快速开始
完成一次成功调用只需要三步。建议先在沙箱环境跑通，再切换到生产环境。
步骤 1 · 获取令牌
curl -X POST https://api.zhidiancloud.com/v1/oauth/token \
-H "Content-Type: application/json" \
-d '{"client_id":"YOUR_ID","client_secret":"YOUR_SECRET","grant_type":"client_credentials"}'步骤 2 · 查询设备列表
curl "https://api.zhidiancloud.com/v1/devices?page=1&page_size=20" \
-H "Authorization: Bearer $TOKEN"步骤 3 · 订阅实时数据（Python）
import paho.mqtt.client as mqtt
client = mqtt.Client(client_id="your-service-01")
client.username_pw_set("YOUR_ID", "YOUR_SECRET")
client.tls_set() # 强制 TLS
client.connect("mqtt.zhidiancloud.com", 8883, 60)
client.subscribe("device/+/telemetry", qos=1)
client.subscribe("device/+/alarm", qos=1)
def on_message(c, u, msg):
print(msg.topic, msg.payload.decode())
client.on_message = on_message
client.loop_forever()
沙箱环境与生产环境的密钥不通用。沙箱数据为模拟设备，可随意读写，适合自动化回归测试。
鉴权与密钥
REST API 采用 OAuth2 客户端凭证模式，MQTT 采用用户名 + 密码 + TLS 双向认证。
令牌说明
- 令牌有效期 7200 秒，请在服务端缓存并在过期前刷新
- 不要在前端代码或 App 中硬编码 client_secret
- 每个密钥可单独配置可访问的接口范围与限流额度
密钥轮换
支持同时存在两组密钥，便于无中断轮换。轮换时先启用新密钥，观察确认后再停用旧密钥。
请求头格式
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Content-Type: application/json
X-ZD-Request-Id: 3f1c9a2e-... // 可选，用于追踪REST API
基础地址：https://api.zhidiancloud.com/v1。所有请求与响应均使用 UTF-8 编码的 JSON。
主要接口
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /devices | 分页查询设备列表 |
| GET | /devices/{sn} | 设备档案与绑定关系 |
| GET | /devices/{sn}/snapshot | 实时快照 |
| GET | /devices/{sn}/history | 历史序列（支持降采样） |
| POST | /devices/{sn}/commands | 下发远程指令 |
| POST | /devices/batch/import | 批量建档 |
| GET | /alarms | 告警记录与处理状态 |
| POST | /ota/tasks | 创建 OTA 升级任务 |
| GET | /passport/{sn} | 电池护照数据集导出 |
指令下发示例
POST /v1/devices/{sn}/commands
{
"cmd": "LOCK_DISCHARGE", // 锁放电
"params": { "duration_min": 0 }, // 0 = 持续至手动解锁
"reason": "租金逾期",
"operator": "system"
}
// 响应
{ "cmd_id": "c-9f2c1a", "status": "accepted", "timeout_sec": 30 }MQTT 订阅
接入地址 mqtt.zhidiancloud.com:8883，强制 TLS。支持 QoS 0/1，建议实时类消息使用 QoS 1。
主题结构
| 主题 | 方向 | 说明 |
|---|---|---|
| device/{sn}/telemetry | 下行 | 周期上报的实时数据 |
| device/{sn}/alarm | 下行 | 告警产生与恢复事件 |
| device/{sn}/status | 下行 | 上下线、信号与固件状态 |
| device/{sn}/command/ack | 下行 | 指令执行回执 |
上报消息示例
device/{sn}/telemetry
{
"msg_id": "9f2c1a",
"sn": "BT24080001",
"ts": 1758601924000,
"cells": [3.262, 3.261, 3.264, 3.260],
"voltage": 52.14,
"current": -10.8,
"soc": 86,
"soh": 98.4,
"temp": [30.4, 31.2, 29.8],
"mos": { "chg": true, "dsg": true },
"alarm": []
}
断线重连后请重新订阅主题。设备离线期间的数据会通过 REST 历史接口补齐，不会丢失。
Webhook 回调
在控制台配置回调地址后，平台会在事件发生时 POST 到您的接口。您无需开放额外的公网入站规则以外的资源。
签名校验
校验示例（Node.js）
const crypto = require('crypto');
function verify(rawBody, signature, secret) {
const expect = 'sha256=' + crypto
.createHmac('sha256', secret)
.update(rawBody)
.digest('hex');
return crypto.timingSafeEqual(Buffer.from(expect), Buffer.from(signature));
}重试策略
- 2xx 视为成功，其他状态码触发重试
- 最多重试 5 次，间隔按 1 / 5 / 25 / 125 / 625 秒递增
- 连续失败超限后暂停推送，可在控制台手动恢复
- 请使用 msg_id 做幂等处理，网络抖动可能导致重复投递
错误码与限流
| 状态码 | 错误码 | 含义 | 处理建议 |
|---|---|---|---|
| 400 | INVALID_PARAM | 参数缺失或格式错误 | 检查字段类型与必填项 |
| 401 | UNAUTHORIZED | 令牌无效或已过期 | 重新获取令牌 |
| 403 | FORBIDDEN | 密钥无该接口权限 | 在控制台调整密钥范围 |
| 404 | NOT_FOUND | 设备或资源不存在 | 确认 SN 是否已建档 |
| 409 | DEVICE_OFFLINE | 设备离线，指令无法下发 | 指令会缓存，上线后自动执行 |
| 429 | RATE_LIMITED | 触发限流 | 按 Retry-After 退避重试 |
| 500 | INTERNAL_ERROR | 服务端异常 | 携带 X-ZD-Request-Id 联系我们 |
默认限流额度见开放能力页面。需要提额请提交业务说明，我们为指定密钥单独调整。
嵌入式 SDK
如果您希望板子或网关直接对接云端而不使用我们的模组，可以移植 SDK。SDK 负责连接管理、鉴权、数据打包与断网缓存重传。
- C 语言实现，适合资源受限的 MCU
- 提供主流芯片平台的移植示例
- 报文格式公开，不依赖我们的固件
- 对接期间有工程师陪跑，直到实板跑通
初始化示例
zd_config_t cfg = {
.product_key = "YOUR_PRODUCT_KEY",
.device_sn = "BT24080001",
.device_sec = "DEVICE_SECRET",
.cache_days = 7 // 断网缓存天数
};
zd_client_t *c = zd_init(&cfg);
zd_set_telemetry_cb(c, on_telemetry_ready);
zd_start(c);技术支持
文档没覆盖到的部分，直接找人问更快。以下是几种获取帮助的方式：
- 测试密钥：在演示账号申请时备注"需要 API 沙箱"，我们会一并开通
- 对接陪跑：正式客户在对接期有专属对接工程师
- 问题反馈：提供 X-ZD-Request-Id 可快速定位到具体请求