标准协议接入
HTTP · MQTT适合什么
- 已有后端，能直接调用 HTTP 接口
- 需要订阅门锁事件做实时联动
- 希望照接口文档自行对接
不适合什么
- 完全不想处理鉴权与重试逻辑
起点：GET /api/v1/devices
- GET /api/v1/devices
- POST /api/v1/locks/{id}/unlock
- MQTT zglock/{id}/event
- GET /api/v1/events
- POST /api/v1/leases
- GET /api/v1/meters/{id}/reading
01 / 接入方式
选择接入方式
四条路径覆盖从纯接口对接到内网私有化的不同条件，按现场情况选其一。
SDK 接入
Java · Python · Go适合什么
- 团队希望少写网络层代码
- 鉴权、重试与序列化已由封装包处理
- 按语言直接调用设备与事件接口
不适合什么
- 运行环境不在已提供的语言范围内
起点：sdk.devices.list()
私有化部署
Self-hosted适合什么
- 数据必须留在自有服务器
- 内网环境，不允许出公网
- 需要与内部账号体系打通
不适合什么
- 希望开箱即用、不维护服务器
起点：部署包 + 配置清单
插件与边缘网关
Gateway · Plugin适合什么
- 现场已有 RS485 等总线设备
- 需要把既有协议转成统一接口
- 断网时仍要本地可用
不适合什么
- 点位全部为原生联网门锁
起点：边缘网关 + 协议插件
02 / 选择接入方式
03 / 技术资料
技术资料
按左侧目录查阅资料，右侧是从选型到量产的一条主线。
-
01
了解平台
阅读平台概览，确认门锁能力边界与接口范围。
产出：能力清单 -
02
选接入方式
按现场条件，在四条路径中确定一条。
产出：接入方式确认 -
03
创建产品
在 DSLock 内建立产品与设备模型。
产出：产品与设备 -
04
功能定义
定义设备的属性、事件与服务。
产出：功能定义表 -
05
下载 SDK
按语言取用封装包，或直接对接标准协议。
产出：SDK 包 -
06
联调
在测试环境验证开门与事件上报。
产出：联调记录 -
07
量产
批量灌装与激活，纳入统一纳管。
产出：量产批次
04 / 设备能力
设备能力
设备的每个能力都用一种数据类型描述，接口与事件共用同一份定义。
布尔
只有开与关两种状态，例如门磁与锁舌。
数值
可用数字度量的量，例如电量与温度。
枚举
在有限取值内切换，例如门锁状态。
透传
原样转发字节，交给业务侧自行解析。
属性定义示例
# 用数据类型描述设备能力
power bool # 门磁：true / false
level int # 电量：0 ~ 100
state enum # 状态：closed / open
raw bytes # 透传：原始字节
05 / 接口速查
接口速查
设备、门锁、仪表、事件与租期的常用路径一览。
设备
- GET /api/v1/devices
- POST /api/v1/devices
- GET /api/v1/devices/{id}
- DELETE /api/v1/devices/{id}
门锁
- POST /api/v1/locks/{id}/unlock
- POST /api/v1/locks/{id}/passwords
- POST /api/v1/locks/{id}/cards
- GET /api/v1/locks/{id}/battery
- GET /api/v1/locks/{id}/records
电表水表
- GET /api/v1/meters
- GET /api/v1/meters/{id}/reading
- GET /api/v1/meters/{id}/usage
- POST /api/v1/meters/{id}/valve
事件
- GET /api/v1/events
- MQTT zglock/{id}/event
租期
- POST /api/v1/leases
- DELETE /api/v1/leases/{id}
06 / SDK 与工具
SDK 与工具
按语言或平台选择封装包，也可直接对接标准协议。
| 语言 / 平台 | 包名 | 适用接入方式 | 状态 |
|---|---|---|---|
| Java | zglock-sdk-java | 标准协议 / SDK | 可用 |
| Python | zglock-sdk-python | 标准协议 / SDK | 可用 |
| Go | zglock-sdk-go | 标准协议 / SDK | 可用 |
| JavaScript | zglock-sdk-js | 标准协议 / SDK | 可用 |
| 嵌入式 C | zglock-sdk-embedded | 边缘网关 | 按项目 |
07 / 安全与合规
安全与合规
从设备到数据的基本安全措施，逐项说明。
设备鉴权
每台设备独立凭证
传输加密
传输全程加密
密钥轮换
密钥定期轮换
权限分级
权限按角色分级
数据导出
记录可导出
日志留痕
操作与开门留痕