物联网中台系统-智能门锁

接入接口说明书

文档版本号： V1.9.3 文档编号：

文档密级： 秘密 归属部门/项目：

产品名： 子系统名：

编写人： 郑文土 编写日期： 2019.12.11

国民科技 版权所有

内部资料 注意保密

修订历史记录
1
版本号 修订人 修订日期 修订描述 审核人 发布日期

V1.0 郑文土 20191211 初版

V1.1 黄权柳 20200318 补充协议，增加记录和操作等协议

V1.2 熊胡松 20200414 补充协议，增加联网状态回调推送

V1.3 熊胡松 20200423 补充协议，增加注册回调地址

V1.4 熊胡松 20200907 补充协议，增加恢复出厂设置

补充协议，增加月末激活控制和获取
V1.5 熊胡松 20210223
动态密码
补充协议，门锁信息增加指纹厂商和
V1.6 熊胡松 20210301
添加权限增加身份证识别码

V1.7 王国庆 20211018 补充协议，新增权限延期接口

补充协议，权限添加新增人脸，开门
V1.8 王国庆 20220928 记录新增机械钥匙、动态密码、人脸
特征值开门

V1.9 王国庆 20221021 补充协议，新增查询管理员密码接口

V1.9.1 王国庆 20230131 补充协议，更新用户权限列表说明

V1.9.2 王国庆 20230317 补充协议，新设备调度推送设备信息

补充协议，新增 3.7、3.8 接口、3.4

V1.9.3 王国庆 20230329 获取用户权限类别新增权限使用人字
段、4.1 新增权限添加权限使用人

V1.9.4 王国庆 20230814 补充协议新增商汤人脸

本文档中所包含的信息属于机密信息，如无国民科技的书面许可，任何人都无权复制或利用。

2
目录
目录 .............................................................................................................................................................................. 3
1 总体说明 .................................................................................................................................................................. 4
2 登陆授权 .................................................................................................................................................................. 5
2.1 应用安全接入 ................................................................................................................................................... 5
2.1.1 鉴权 ............................................................................................................................................................ 5
3 设备管理接口 .......................................................................................................................................................... 6
3.1 查询设备列表 ................................................................................................................................................... 6
3.1.1 请求数据 .................................................................................................................................................... 6
3.1.2 响应数据 .................................................................................................................................................... 7
3.2 获取设备详情 .................................................................................................................................................... 8
3.2.1 请求数据 .................................................................................................................................................... 8
3.2.2 响应数据 .................................................................................................................................................... 8
3.3 开锁和报警记录 ................................................................................................................................................ 9
3.3.1 请求数据 .................................................................................................................................................... 9
3.3.2 响应数据 .................................................................................................................................................... 9
3.4 用户权限列表 ..................................................................................................................................................11
3.4.1 请求数据 ..................................................................................................................................................11
3.4.2 响应数据 ..................................................................................................................................................11
3.5 操作记录 ..........................................................................................................................................................12
3.5.1 请求数据 ..................................................................................................................................................12
3.5.2 响应数据 ..................................................................................................................................................13
3.6 获取动态密码 ..................................................................................................................................................14
3.6.1 请求数据 ..................................................................................................................................................14
3.6.2 响应数据 ..................................................................................................................................................14
3.7 获取管理员密码 ..............................................................................................................................................15
3.7.1 请求数据 ..................................................................................................................................................15
3.7.2 响应数据 ..................................................................................................................................................15
3.8 获取设备自检信息 ..........................................................................................................................................16
3.8.1 请求数据 ..................................................................................................................................................16
3.8.2 响应数据 ..................................................................................................................................................16

3
4 设备控制接口 ........................................................................................................................................................17
4.1 添加用户 .....................................................................................................................................................17
4.2 删除用户 .....................................................................................................................................................19
4.3 清空用户 .....................................................................................................................................................20
4.4 启用用户 .....................................................................................................................................................20
4.5 禁用用户 .....................................................................................................................................................21
4.6 修改密码 .....................................................................................................................................................22
4.7 生成激活码 .................................................................................................................................................22
4.8 操作管理员 .................................................................................................................................................24
4.9 恢复出厂设置 .............................................................................................................................................25
4.10 月末激活设置 ...........................................................................................................................................25
4.11 权限延期 ...................................................................................................................................................26
5 消息推送 ................................................................................................................................................................27
5.1 通用协议部分 .............................................................................................................................................28
5.2 设备变化协议 .............................................................................................................................................28
5.3 返回码 ..........................................................................................................................................................30
5.4 注册回调地址 ..............................................................................................................................................30

1 总体说明
1: 首先请参考父文档《国民智联设备管理系统对外接口》

类目 说明
操作类型 * USER_ADD 添加用户
* USER_DEL 删除用户
* USER_CLEAN 清空用户
* USER_ENABLE 启用用户
* USER_DISABLE 禁用用户
* LOCK_CONFIG 配置门锁信息
* LOCK_VERIFY 验证门锁设备
* LOCK_REMOTE_OPEN 远程开锁
* LOCK_RESET 重置门锁
* USER_CHANGE_PWD 修改密码

4
用户类型 * FINGERPRINT 指纹
* PASSWORD 密码
* CARD_ID 卡片物理ID（身份证物理ID）
* APP APP用户
* CTID 身份证副本
* RCC_ID RCC卡片物理ID
* CARD_AID 卡片应用ID
* RCC_AID RCC卡片应用ID
* PUC_IDEN_CODE 身份证号
* CPU_CARDID 普通物理卡ID
* MECHANICS_KEY 机械钥匙
* DYNAMIC_PWD 动态密码
*WALLET_ID 数币钱包Id
*FACE 人脸特征值
*SHANG_TANG 商汤图片

2 登陆授权

2.1 应用安全接入

业务应用平台获取鉴权信息，接入设备管理平台，随后携带鉴权信息调用其他 API 接口。

2.1.1 鉴权

2.1.1.1 应用场景

鉴权接口是调用 API 接口的前提，除了调用鉴权接口，其他接口的调用都需要在 Header 中携带 appID 和

accessToken，认证有效期为 24 小时，认证过期后需要重新调用此接口进行认证。

2.1.1.2 接口描述

2.1.1.2.1 接口请求

URL https://server:port/api/v1/oauth/login
Method POST
HEADER
元素 取值 取值说明
Content-Type application/json 数据格式
PARAM
序号 元素名称 约束 类型 位置 取值说明
5
 1 appId 必选 string body 应用身份标识
2 appSecret 必选 string body 应用密码

2.1.1.2.1 接口响应

Status Code: 200 OK

URL 无
Method 无
HEADER
元素 取值 取值说明
Content-Type application/json 数据格式
PARAM
序号 元素名称 约束 类型 位置 取值说明
1 score 必选 string - 申请权限范围，当前固定为default
2 tokenType 必选 string - accessToken的类型，当前固定为bearer
3 expiresIn 必选 string - accessToken的有效时间
4 accessToken 必选 string - 鉴权参数，访问设备管理平台API接口的凭证
5 refreshToken 必选 string - 鉴权参数，用来刷新accessToken，有效期为1个月

2.1.1.3 接口实例

3 设备管理接口

3.1 查询设备列表

3.1.1 请求数据

URL https://server:port/api/v1/smartlock/devices?pageNo={1}&pageSize={10}
Method GET
HEADER
元素 取值 取值说明
appId 应用身份标识
accessToken 鉴权参数，访问设备管理平台API接口的凭证
PARAM
序号 元素名称 约束 类型 位置 取值说明
1 pageNo 必选 Integer query 查询的页码
2 pageSize 必选 Integer query 查询每页信息的数量
3 serialNumber 可选 String query 模糊查询门锁的序列号

6
 4 status 可选 Integer query 联网状态-0：联机；1：脱机；2：异常

3.1.2 响应数据

URL 无
Method 无
HEADER
元素 取值 取值说明
Content-Type application/json 数据格式

PARAM
序号 元素名称 约束 类型 位置 取值说明
1 code 必选 Integer 1 0-成功
2 message 必选 String 1
3 desc 必选 String 1
4 data 必选 Json 1
5 pageNo 必选 Integer data 查询的页码
6 pageSize 必选 Integer data 查询每页信息的数量
7 totalSize 必选 Integer data 记录总数
8 list 必选 List<DeviceInfo> - data 设备信息列表,详情参考【DeviceInfo数据结构】
DeviceInfo 数据结构
参数 约束 类型 描述
deviceId 必选 string 设备 ID，用于唯一标识一个设备
createTime 必选 string 创建时间
时间格式：yyyy-MM-dd HH:mm:ss，如 2015-12-12
12:12:12
modifyTime 必选 string 修改时间
时间格式：yyyy-MM-dd HH:mm:ss，如 2015-12-12
12:12:12
heartTime 必选 string 心跳时间
时间格式：yyyy-MM-dd HH:mm:ss，如 2015-12-12
12:12:12
earfcn 可选 int 频点
iccid 必选 string iccid
imei 必选 string imei
name 可选 string 设备名称
isBle 必选 int 是否带蓝牙：0-否；1-是
bleMac 可选 string 蓝牙的 mac 地址
wifiMac 可选 string wifi 的 mac 地址
wifiRssi 可选 string wifi 的信号强度
intModel 必选 string 对内型号
model 必选 string 对外型号
fpModel 可选 string 指纹传感器型号

7
fpVendor 可选 string 指纹传感器版本
fwVersion 必选 string 设备的固件版本
hwVersion 必选 string 设备的硬件版本
hwInfo 必选 string 设备的硬件信息
status 必选 int 联网状态-0：联机；1：脱机；2：异常
nbCsq 可选 int nb 信号强度
nbFwVersion 可选 string nb 模块固件厂商版本
nbSnr 可选 int nb 的信噪比
netType 可选 int 联网类型-0：wifi；1：nb；2：zigbee；3:
433mhz；4：非联网；5：lan
pci 可选 int 基站号
serialNumber 可选 string 设备的序列号
batteryLevel 可选 string 设备的电池电量
activeKey 必选 string 随机激活码
fingerprintFactory 可选 int 指纹厂商：0-未知类型；1-指安；2-比亚迪；

3.2 获取设备详情

3.2.1 请求数据

URL https://server:port/api/v1/smartlock/devices/{deviceId}
Method GET
HEADER
元素 取值 取值说明
appId 应用身份标识
accessToken 鉴权参数，访问设备管理平台API接口的凭证
PARAM
序号 元素名称 约束 类型 位置 取值说明

3.2.2 响应数据

URL 无
Method 无
HEADER
元素 取值 取值说明

8
 Content-Type application/json 数据格式

PARAM
序号 元素名称 约束 类型 位置 取值说明
1 code 必选 Integer 1 0-成功
2 message 必选 String 1
3 desc 必选 String 1
4 data 必选 Json 1 详情参考【DeviceInfo数据结构】

3.3 开锁和报警记录

3.3.1 请求数据

URL https://server:port/api/v1/smartlock/devlogs?pageNo={1}&pageSize={10}
Method GET
HEADER
元素 取值 取值说明
appId 应用身份标识
accessToken 鉴权参数，访问设备管理平台API接口的凭证
PARAM
序号 元素名称 约束 类型 位置 取值说明
1 pageNo 必选 Integer 查询的页码
2 pageSize 必选 Integer 查询每页信息的数量
设备ID
3 deviceId 可选 string
未填时获取所有锁的记录
type值 1: 开锁记录 2:报警记录
4 type 可选 string
未填时获取所有类型记录
筛选开始时间
5 startTime 可选 string
时间格式：yyyy-MM-dd hh:mm:ss
筛选结束时间
6 endTime 可选 string
时间格式：yyyy-MM-dd hh:mm:ss

3.3.2 响应数据

URL 无
Method 无
HEADER
元素 取值 取值说明
Content-Type application/json 数据格式

PARAM
序号 元素名称 约束 类型 位置 取值说明
9
 1 code 必选 Integer 1 0-成功
2 message 必选 String 1
3 desc 必选 String 1
4 data 必选 Json 1
4-1 pageNo 必选 Integer data 查询的页码
4-2 pageSize 必选 Integer data 查询每页信息的数量
4-3 totalSize 必选 Integer data 记录总数
4-4 list 必选 List<NtLocklog> data 记录信息列表 详情查看【NtLocklog数据结构】

NtLocklog 数据结构
NtLocklog 结构说明
参数 约束 类型 描述
deviceId 必选 string 设备 ID，用于唯一标识一个设备
createTime 必选 string 创建时间
eventType 必选 string 事件类型
0：超过 5 次异常
1：撬锁异常
2：低电异常
3：胁迫异常
eventTime 必选 string 发生时间
eventTypeDesc 必选 string 事件描述
eventTypeName 必选 string 事件类型名
logType 必选 string 记录类型 1: 开锁记录 2:报警记录
logTypeDesc 必选 string 记录类型描述
logTypeName 必选 string 记录类型名称
modifyTime 可选 string 修改时间
openType 可选 string 开门类型,
-14：动态密码
-13：机械钥匙
0：指纹；
1：密码；
2：身份证；
3：应用；
4：CTID；
5：RCC 卡 ID；
6：国民工卡；
7：国民 RCC 工卡；
8：身份证号；
9：卡片
10：数币卡
11：人脸特征值
openTypeDesc 可选 string 开门类型描述
openTypeName 可选 string 开门类型名称
openUserId 可选 int 开门用户 ID
userId 可选 String 用户-权限 ID

10
userIdDev 可选 int 锁用户-权限 ID

3.4 用户权限列表

3.4.1 请求数据

URL https://server:port/api/v1/smartlock/{deviceId}/userToken?pageNo={1}&pageSize={10}
Method GET
HEADER
元素 取值 取值说明
appId 应用身份标识
accessToken 鉴权参数，访问设备管理平台API接口的凭证
PARAM
序号 元素名称 约束 类型 位置 取值说明
1 pageNo 必选 Integer 查询的页码
2 pageSize 必选 Integer 查询每页信息的数量
3 userId 可选 Integer 锁中的用户编号

3.4.2 响应数据

URL 无
Method 无
HEADER
元素 取值 取值说明
Content-Type application/json 数据格式

PARAM
序号 元素名称 约束 类型 位置 取值说明
1 code 必选 Integer 1 0-成功
2 message 必选 String 1
3 desc 必选 String 1
4 data 必选 Json 1
4-1 pageNo 必选 Integer data 查询的页码
4-2 pageSize 必选 Integer data 查询每页信息的数量
4-3 totalSize 必选 Integer data 记录总数
4-4 list 必选 List<NtLocktoken> data 用户权限列表 详情参考【NtLocktoken数据结构】

NtLocktoken 数据结构
参数 约束 类型 描述
tokenId 必选 Id
deviceId 必选 string 设备 ID，用于唯一标识一个设备
11
deviceSn 必选 string 设备序列号
tokenType 必选 string 权限类型
0：指纹；1：密码；2：身份证；3：应用；4：CTID；
5：RCC 卡 ID；6：国民工卡；7：国民 RCC 工卡；
8：身份证号；9：卡片，10：数币钱包，11：人脸；
tokenName 必选 string token 名称
tokenData 必选 string 权限值
userId 必选 string 锁中的用户编号
userType 必选 string 用户类型
0：长期用户；1：管理员用户；2：临时（totp）用
户；3：时效用户；4：长期员工；5：时效员工;6:一
次性用户；7：清空用户
state 必选 string 状态：
激活码注册类型(loginType)为空时：
0-下发中,1-下发成功,2-下发失败,3-删除中,4-删除
成功,5-取消下发,6-禁用中,7-已禁用,8-启用中,9-已
启用,10-延期中,11-延期成功,12-延期失败
激活码注册类型(loginType）不为空时：
0-未使用，1-已使用
effectiveStart 可选 string 有效起始日期
effectiveEnd 可选 string 有效结束日期
deliveryTime 可选 string 下发门锁成功时间
loginType 可选 string 激活码注册类型：NULL-不是激活码；0-直接使用；
1-注册后使用
userName 可选 string 权限使用人

3.5 操作记录

3.5.1 请求数据

URL https://server:port/api/v1/smartlock/operlogs
Method GET
HEADER
元素 取值 取值说明
appId 应用身份标识
accessToken 鉴权参数，访问设备管理平台API接口的凭证
PARAM
序号 元素名称 约束 类型 位置 取值说明
1 pageNo 必选 Integer 查询的页码
2 pageSize 必选 Integer 查询每页信息的数量
3 deviceId 必选 String 设备ID

12
3.5.2 响应数据

URL 无
Method 无
HEADER
元素 取值 取值说明
Content-Type application/json 数据格式

PARAM
序号 元素名称 约束 类型 位置 取值说明
1 code 必选 Integer 1 0-成功
2 message 必选 String 1
3 desc 必选 String 1
4 data 必选 Json 1
4-1 pageNo 必选 Integer data 查询的页码
4-2 pageSize 必选 Integer data 查询每页信息的数量
4-3 totalSize 必选 Integer data 记录总数
List<NtOperLocklog 用户权限列表 详情参考【NtOperLocklog数据结构
4-4 list 必选 data
> 说明】

NtOperLocklog 数据结构说明
参数 约束 类型 描述
id 必选 string Id
deviceId 必选 string 设备 ID，用于唯一标识一个设备
operType 必选 int 操作类型：0：增加权限；1：删除权限；2：恢复出
厂设置；3：新增管理员密码；4：修改密码；
operTypeDesc 必选 string 操作类型描述
operTypeDescName 必选 string 操作类型名称
operStatus 必选 string 操作状态：0：失败；1：成功；2：待获取
operLockAdmin 必选 string 门锁管理员类型：
0：指纹；1：密码；2：身份证；3：应用；4：CTID；
5：RCC 卡 ID；6：国民工卡；7：国民 RCC 工卡；
8：身份证号；9：卡片；
operAdminId 非必选 int 操作管理员 ID
userIdDev 必选 string 锁用户 Id
tokenType 必选 string 权限类型：
0：指纹；1：密码；2：身份证；3：应用；4：CTID；
5：RCC 卡 ID；6：国民工卡；7：国民 RCC 工卡；
8：身份证号；9：卡片；
tokenTypeDesc 必选 string 权限类型描述
tokenTypeName 可选 string 权限类型名称
userType 可选 string 用户类型
0：长期用户；1：管理员用户；2：临时（totp）用
户；3：时效用户；

13
userTypeDesc 可选 string 用户类型描述
userTypeName 可选 string 用户类型名称
deleteType 可选 string 删除类型：0：单个权限；1：RCC 普通权限；2：人
脸普通权限；3：卡片普通权限；4：密码普通权限；
5：指纹普通权限；6：所有租客权限;7:所有权限（除
管理员）;8:所有员工权限
deleteTypeDesc 可选 string 删除类型描述
deleteTypeName 可选 string 删除类型名称
createTime 可选 string 创建时间
eventTime 可选 string 发生时间
modifyTime 可选 string 修改时间

3.6 获取动态密码

动态密码可在自然时间半小时内开锁。例如 12:55 生成的动态密码，有效使用时间是 12:30~13：00，实际还有 5

分钟的使用时间。

3.6.1 请求数据

URL https://server:port/api/v1/smartlock/dynamic
Method GET
HEADER
元素 取值 取值说明
appId 应用身份标识
accessToken 鉴权参数，访问设备管理平台API接口的凭证
PARAM
序号 元素名称 约束 类型 位置 取值说明
1 pwd 必选 Integer 门锁管理员密码
2 serialNumber 必选 Integer 门锁序列号

3.6.2 响应数据

URL 无
Method 无
HEADER
元素 取值 取值说明
Content-Type application/json 数据格式

PARAM
序号 元素名称 约束 类型 位置 取值说明
1 code 必选 Integer 1 0-成功
2 message 必选 String 1
3 desc 必选 String 1

14
 4 data 必选 String 1 门锁动密码

3.7 获取管理员密码

只有门锁上添加成功的管理员密码才能被查询，其他下发状态无法查询。

3.7.1 请求数据

URL https://server:port/api/v1/smartlock/{deviceId}/getAdminPwd
Method GET
HEADER
元素 取值 取值说明
appId 应用身份标识
accessToken 鉴权参数，访问设备管理平台API接口的凭证
PARAM
序号 元素名称 约束 类型 位置 取值说明

3.7.2 响应数据

URL 无
Method 无
HEADER
元素 取值 取值说明
Content-Type application/json 数据格式

PARAM
序号 元素名称 约束 类型 位置 取值说明
1 code 必选 Integer 1 0-成功
2 message 必选 String 1
3 desc 必选 String 1
4 data 必选 String 1 用户权限 详情参考【NtLocktoken数据结构】
NtLocktoken 数据结构
参数 约束 类型 描述
tokenId 必选 Id
deviceId 必选 string 设备 ID，用于唯一标识一个设备
deviceSn 必选 string 设备序列号
tokenType 必选 string 权限类型
1：密码；
tokenName 必选 string token 名称
tokenData 必选 string 权限值
userId 必选 string 锁中的用户编号
userType 必选 string 用户类型
1：管理员用户

15
state 必选 string 状态：
0-下发中,1-下发成功,2-下发失败,3-删除中,4-删除
成功,5-取消下发,6-禁用中,7-已禁用,8-启用中,9-已
启用
effectiveStart 可选 string 有效起始日期
effectiveEnd 可选 string 有效结束日期
deliveryTime 可选 string 下发门锁成功时间

3.8 获取设备自检信息

3.8.1 请求数据

URL https://server:port/api/v1/smartlock/checkRecord
Method GET
HEADER
元素 取值 取值说明
appId 应用身份标识
accessToken 鉴权参数，访问设备管理平台API接口的凭证
PARAM
序号 元素名称 约束 类型 位置 取值说明
1 pageNo 必选 Integer query 查询的页码
2 pageSize 必选 Integer query 查询每页信息的数量
3 deviceId 必选 String query 设备ID，用于唯一标识一个设备
4 startTime 可选 String query 开始时间
4 endTime 可选 String query 结束时间

3.8.2 响应数据

URL 无
Method 无
HEADER
元素 取值 取值说明
Content-Type application/json 数据格式

PARAM
序号 元素名称 约束 类型 位置 取值说明
1 code 必选 Integer 1 0-成功
2 message 必选 String 1
3 desc 必选 String 1
4 data 必选 String 1 用户权限 详情参考【NtLockcheck数据结构】
NtLockcheck 数据结构
参数 约束 类型 描述
id 必选 Id
16
deviceId 必选 string 设备 ID，用于唯一标识一个设备
seSn 必选 string 设备序列号
hub 必选 Integer HUB：0-正常，1-异常
touchIc 必选 Integer 触摸 IC：0-正常，1-异常
nfc 必选 Integer NFC：0-正常，1-异常
fingerprint 必选 Integer 指纹：0-正常，1-异常
network 必选 Integer 联网：0-正常，1-异常
bluetooth 必选 Integer 蓝牙：0-正常，1-异常
rcc 必选 Integer RCC：0-正常，1-异常
spiFlash 必选 Integer spi flash：0-正常，1-异常
createTime 必选 string 自检时间

4 设备控制接口
设备控制通用协议部分
URL https://server:port/api/v1/smartlock/devices/{deviceId}
Method POST
HEADER
元素 取值 取值说明
appId 应用身份标识
accessToken 鉴权参数，访问设备管理平台API接口的凭证
PARAM（Json字符串）
序号 元素名称 约束 类型 位置 取值说明
设备操作类型
1 type 必选 string body
COMMAND
设备的业务数据， json字符串，具体操作参见设
2 data 必选 string body
备接口定义文档
具体设备操作定义 data 格式如下定义：

4.1 添加用户

4.1.1 请求数据

说明 取值 取值说明
data格式 json 业务数据通过json格式传输
数据
层次 元素名称 约束 类型 位置 取值说明
门锁操作类型
1 type 必须 string -
* USER_ADD 添加用户
1 data 必须 json - 跟操作类型相对应的数据
data 与不同类型门锁操作相对应的数据

17
 权限类型：
PASSWORD 权限类型为 密码
FINGERPRINT 权限类型为指纹
CPU_CARDID 权限类型为IC卡
2 userType 必须 string -
CARD_ID 权限类型为身份证ID、卡片ID等
PUC_IDEN_CODE 权限类型为身份证识别码
FACE 人脸特征值
SHANGTANG_FACE 商汤人脸
2 validType 必须 string - * VALIDTYPE_VALID_PERIOD 时间有效用户
当用户类型为时间有效用户
(VALIDTYPE_VALID_PERIOD)
validPeriodStart
2 必选 string - 时需要通过这个参数提供有效期开始时间,时间格
Time
式为”yyyy-MM-dd hh:mm:ss”
注：建议使用当前日期及当前小时
当用户类型为时间有效用户
validPeriodEnd (VALIDTYPE_VALID_PERIOD)
2 必选 string -
Time 时需要通过这个参数提供有效期结束时间,时间格
式为”yyyy-MM-dd hh:mm:ss”
ASCII字符串
* PASSWORD 密码
HEX字符串
* FINGERPRINT 指纹
* CARD_ID 卡片物理ID
* APP APP用户
* CTID 身份证副本
2 userData 必选 string - * RCC_ID RCC卡片物理ID
* CARD_AID 卡片应用ID
* RCC_AID RCC卡片应用ID
* CPU_CARDID CPU卡ID
* PUC_IDEN_CODE 身份证号码
* FACE 人脸特征值
*SHANGTANG_FACE 商汤人脸 (传网络图片地
址，大小要求50K以内)
2 userName 可选 String - 权限使用人名字，客户根据自己需求填写

4.1.2 响应数据

说明 取值 取值说明
格式 json 业务数据通过json格式传输
结果返回方式 异步回调 通过回调,将调用结果返回给业务平台
数据
层次 元素名称 约束 类型 位置 取值说明
门锁操作类型
1 type 必须 string body
*: USER_ADD 添加用户

18
 *: 00 添加用户成功
*: 01 内部错误
1 code 必须 integer body *: 02 用户已满
*: 03 用户已存在
*: 04 未设置管理员,不允许下发权限
1 msg 必须 string body *: 结果返回描述
1 data 必须 json - 跟操作类型相对应的数据
data 与不同类型门锁操作相对应的数据
2 userId 必须 string - 用户ID

4.2 删除用户

4.2.1 请求数据

说明 取值 取值说明
data格式 json 业务数据通过json格式传输
数据
层次 元素名称 约束 类型 位置 取值说明
门锁操作类型
1 type 必须 string -
* USER_DEL 删除用户
1 data 必须 json - 跟操作类型相对应的数据
data 与不同类型门锁操作相对应的数据
2 userId 必须 string - 用户ID

4.2.2 响应数据

说明 取值 取值说明
格式 json 业务数据通过json格式传输
结果返回方式 异步回调 通过回调,将调用结果返回给业务平台
数据
层次 元素名称 约束 类型 位置 取值说明
门锁操作类型
1 type 必须 string json
* USER_DEL 删除用户
*: 00 删除用户成功
1 code 必须 integer body
*: 01 内部错误
1 msg 必须 string body *: 结果返回描述
1 data 必须 json - 跟操作类型相对应的数据
data 与不同类型门锁操作相对应的数据
2 userId 必须 string - 用户ID

19
4.3 清空用户

4.3.1 请求数据

说明 取值 取值说明
data格式 json 业务数据通过json格式传输
数据
层次 元素名称 约束 类型 位置 取值说明
门锁操作类型
1 type 必须 string -
* USER_CLEAN 清空用户
1 data 必须 json - 跟操作类型相对应的数据
data 与不同类型门锁操作相对应的数据
2 userType 必须 integer data 65535-清空权限

4.3.2 响应数据

说明 取值 取值说明
格式 json 业务数据通过json格式传输
数据
层次 元素名称 约束 类型 位置 取值说明
门锁操作类型
1 type 必须 string -
* USER_CLEAN 清空用户
*: 00 清空用户成功
1 code 必须 integer body
*: 01 内部错误
1 msg 必须 string body *: 结果返回描述

4.4 启用用户

4.4.1 请求数据

说明 取值 取值说明
data格式 json 业务数据通过json格式传输
数据
层次 元素名称 约束 类型 位置 取值说明
门锁操作类型
1 type 必须 string -
* USER_ENABLE 启用用户
1 data 必须 json - 跟操作类型相对应的数据
data 与不同类型门锁操作相对应的数据
2 userList 必须 List<string> - 用户ID列表

20
4.4.2 响应数据

说明 取值 取值说明
格式 json 业务数据通过json格式传输
数据
层次 元素名称 约束 类型 位置 取值说明
门锁操作类型
1 type 必须 string -
* USER_ENABLE 启用用户
*: 00 启用用户成功
1 code 必须 integer body
*: 01 内部错误
1 msg 必须 string body *: 结果返回描述
1 data 必须 json - 跟操作类型相对应的数据
data 与不同类型门锁操作相对应的数据
2 userList 必须 List<string> - 用户ID

4.5 禁用用户

4.5.1 请求数据

说明 取值 取值说明
data格式 json 业务数据通过json格式传输
数据
层次 元素名称 约束 类型 位置 取值说明
门锁操作类型
1 type 必须 string -
* USER_DISABLE 禁用用户
1 data 必须 json - 跟操作类型相对应的数据
data 与不同类型门锁操作相对应的数据
2 userList 必须 List<string> - 用户ID

4.5.2 响应数据

说明 取值 取值说明
格式 json 业务数据通过json格式传输
数据
层次 元素名称 约束 类型 位置 取值说明
门锁操作类型
1 type 必须 string -
* USER_DISABLE 禁用用户
*: 00 禁用用户成功
1 code 必须 integer body
*: 01 内部错误
1 msg 必须 string body *: 结果返回描述
21
 1 data 必须 json - 跟操作类型相对应的数据
data 与不同类型门锁操作相对应的数据
2 userList 必须 List<string> - 用户ID

4.6 修改密码

4.6.1 请求数据

说明 取值 取值说明
data格式 json 业务数据通过json格式传输
数据
层次 元素名称 约束 类型 位置 取值说明
门锁操作类型
1 type 必须 string -
* USER_CHANGE_PWD
1 data 必须 json - 跟操作类型相对应的数据
data 与不同类型门锁操作相对应的数据
2 userId 必须 string - 用户ID
2 newPwd 必须 string - ASCII数据格式
权限类型：
PASSWORD 权限类型为 密码
2 userType 可选 String - FINGERPRINT 权限类型为指纹
CPU_CARDID 权限类型为IC卡
CARD_ID 权限类型为身份证

4.6.2 响应数据

说明 取值 取值说明
格式 json 业务数据通过json格式传输
数据
层次 元素名称 约束 类型 位置 取值说明
门锁操作类型
1 type 必须 string -
* USER_CHANGE_PWD
*: 00 修改密码成功
*: 01 内部错误
1 code 必须 integer body
*: 02 旧密码不存在
*: 03 新密码重复
1 msg 必须 string body *: 结果返回描述

4.7 生成激活码

激活码是中台系统通过加密规则加密后生成的操作门锁的操作码。目前支持循环权限激活码、限时权限激活码、
永久权限激活码、一次性权限激活码、清空权限激活码这五大激活码。循环权限激活码是用于添加一个在权限有

22
效期开始时间至有效期结束时间内且满足循环规则才可以开锁的权限的激活码。限时权限激活码是用于添加一
个在权限有效期开始时间至有效期结束时间内才可以开锁的权限的激活码。永久权限激活码是用于添加一个任
意时间都可以开锁的权限的激活码。一次性权限激活码输入即可开锁且只能开锁一次的激活码。清空权限激活码
是按规则删除锁内的权限的激活码。
激活码类型 激活码使用方式 激活码功能
循环激活码 有效期开始时间起 24 小时内可使用 添加一个循环用户权限
限时激活码 有效期开始时间起 24 小时内可使用 添加一个限时用户权限
永久激活码 生成激活码起 24 小时内可使用 添加一个永久用户权限
一次性激活码 生成激活码起 2 小时内只能使用一次 仅开一次门
清空激活码 生成激活码起 2 小时内可多次使用 按规则删除锁内权限

4.7.1 请求数据

说明 取值 取值说明
data格式 json 业务数据通过json格式传输
数据
层次 元素名称 约束 类型 位置 取值说明
1 type 必须 string - 门锁操作类型 ACTIVE_CODE
1 data 必须 json - 跟操作类型相对应的数据
data 与不同类型门锁操作相对应的数据
用户类型：1=租客，2=员工
2 userType 必选 string -
循环权限、限时权限、永久权限必选项
权限类型：1=循环权限，2=限时权限，3=永久权
2 validType 必选 string -
限，4=一次性权限，5=清空权限
注册类型：0=直接激活码开锁，1=在门锁面板上
2 loginType 可选 string - 注册后使用
循环权限、限时权限、永久权限必选项
循环方式：周一循环=1，周二循环=2，周三循环
=3，周四循环=4，周五循环=5，周六循环=6，周
recycleFlag
2 可选 string - 日循环=7；每日循环=8，工作日循环=9，周末循
环=10
循环权限必选项
有效期开始时间格式：yyyy-MM-dd HH:mm:ss，
validPeriodStart
如 2019-09-20 15:33:01
2 Time 可选 string
循环权限、限时权限必选项
注：建议使用当前日期及当前小时
validPeriodEnd 有效期结束时间格式：yyyy-MM-dd HH:mm:ss，
2 Time 可选 string 如 2019-09-20 15:33:01
循环权限、限时权限必选项
清空激活码清空类型：清空租客=0，仅保留管理
deleteType
2 可选 string 员=1，清空员工=2，恢复出厂设置=3
清空权限必选项

23
 timeLose 时间挂失：关闭时间挂失=0，开启时间挂失=1
2 可选 string
循环权限、限时权限、永久权限必选项

4.7.2 响应数据

说明 取值 取值说明
格式 json 业务数据通过json格式传输
数据
层次 元素名称 约束 类型 位置 取值说明
1 type 必须 string - 门锁操作类型ACTIVE_CODE
*: 00 配置成功
1 code 必须 integer body
*: 01 内部错误
1 msg 必须 string body *: 结果返回描述
1 data 必须 json body 激活码信息
2 userId 必须 integer data 激活码用户ID
2 acticeCode 必须 string data 激活码

4.8 操作管理员

无管理员时添加管理员，有管理员时修改管理员。

4.8.1 请求数据

说明 取值 取值说明
data格式 json 业务数据通过json格式传输
数据
层次 元素名称 约束 类型 位置 取值说明
门锁操作类型
1 type 必须 string -
* USER_CHANGE_PWD
1 data 必须 json - 跟操作类型相对应的数据
data 与不同类型门锁操作相对应的数据
2 userId 必须 string - 固定值：1
2 newPwd 必须 string - ASCII数据格式

4.8.2 响应数据

说明 取值 取值说明

24
 格式 json 业务数据通过json格式传输
数据
层次 元素名称 约束 类型 位置 取值说明
门锁操作类型
1 type 必须 string -
* USER_CHANGE_PWD
*: 00 修改密码成功
*: 01 内部错误
1 code 必须 integer body
*: 02 旧密码不存在
*: 03 新密码重复
1 msg 必须 string body *: 结果返回描述

4.9 恢复出厂设置

4.9.1 请求数据

说明 取值 取值说明
data格式 json 业务数据通过json格式传输
数据
层次 元素名称 约束 类型 位置 取值说明
门锁操作类型
1 type 必须 string -
* LOCK_RESET 恢复出厂设置

4.9.2 响应数据

说明 取值 取值说明
格式 json 业务数据通过json格式传输
数据
层次 元素名称 约束 类型 位置 取值说明
1 code 必须 integer body *: 0 恢复出厂设置成功
1 desc 必须 string body *: 结果返回描述

4.10 月末激活设置

4.10.1 请求数据

说明 取值 取值说明

25
 data格式 json 业务数据通过json格式传输
数据
层次 元素名称 约束 类型 位置 取值说明
门锁操作类型
1 type 必须 string -
* MONTH_END_REACTIVATION
1 data 必须 json -
monthendReacti
2 必须 integer data 2-打开月末激活；3关闭月末激活
vation

4.10.2 响应数据

说明 取值 取值说明
格式 json 业务数据通过json格式传输
数据
层次 元素名称 约束 类型 位置 取值说明
1 code 必须 integer body *: 0 月末激活指令生成成功
1 desc 必须 string body *: 结果返回描述

4.11 权限延期

4.11.1 请求数据

说明 取值 取值说明
data格式 json 业务数据通过json格式传输
数据
层次 元素名称 约束 类型 位置 取值说明
门锁操作类型
1 type 必须 string -
* USER_DELAY 权限延期
1 data 必须 json - 跟操作类型相对应的数据
data 与不同类型门锁操作相对应的数据
2 userType 必须 string - 与添加用户时的权限类型相同
2 validType 必须 string - * VALIDTYPE_VALID_PERIOD 时间有效用户
当用户类型为时间有效用户
(VALIDTYPE_VALID_PERIOD)
validPeriodStart
2 必选 string - 时需要通过这个参数提供有效期开始时间,时间格
Time
式为”yyyy-MM-dd hh:mm:ss”
注：建议使用当前日期及当前小时
当用户类型为时间有效用户
validPeriodEnd (VALIDTYPE_VALID_PERIOD)
2 必选 string -
Time 时需要通过这个参数提供有效期结束时间,时间格
式为”yyyy-MM-dd hh:mm:ss”

26
 2 userId 必选 string - 添加用户返回的用户userId编号、HEX字符串

4.11.2 响应数据

说明 取值 取值说明
格式 json 业务数据通过json格式传输
结果返回方式 异步回调 通过回调,将调用结果返回给业务平台
数据
层次 元素名称 约束 类型 位置 取值说明
门锁操作类型
1 type 必须 string body
*: USER_ADD 添加用户
*: 00 添加用户成功
*: 01 内部错误
1 code 必须 integer body *: 02 用户已满
*: 03 用户已存在
*: 04 未设置管理员,不允许下发权限
1 msg 必须 string body *: 结果返回描述
1 data 必须 json - 跟操作类型相对应的数据
data 与不同类型门锁操作相对应的数据
2 userId 必须 string - 用户ID

5 消息推送
1、需要提供对接推送的 URL 地址
2、协议分通用协议部分，和设备变化协议部分，通用协议不会变动，设备变化协议根据类型定义格式和内容，
参考完整协议格式，红色部分即设备变化协议部分，具体协议参加 5.2 节协议内容。

27
5.1 通用协议部分

参数 约束 类型 位置 描述
notifyType 必选 string body 通知类型，取值
deviceDataChanged
requestId 必选 string body 消息的序列号，唯一标识该消息
deviceId 必选 string body 设备 ID，用于唯一标识一个设备
gatewayId 可选 string body 网关 ID，用于唯一标识一个网关设备，直连设备此字段为
空
service 必选 ServiceData body 设备的通知数据

ServiceData
参数 约束 类型 位置 描述
serviceId 必选 string body 服务 ID
serviceType 必选 string body 服务类型
当前只支持类型 LOCK_DEVICE_DATA_CHANGED
data 必选 Object body 服务数据，根据不同的服务类型产生不同的通知数据，具
体请查看具体设备的推送数据
eventTime 必选 string body 时间格式：yyyyMMdd'T'HHmmss'Z'，如
20151212T121212Z。

5.2 设备变化协议

Object-->LOCK_DEVICE_DATA_CHANGED
参数 约束 类型 位置 描述
dataType 必选 string body 数据类型
LOCK_OPEN_DOOR 门锁开门事件
LOCK_ABNORMAL_ALARM 门锁报警事件
LOCK_SYNC_USER 门锁同步用户
LOCK_HEART_BEAT 门锁心跳记录
LOCK_OPERATION_RESP 门锁操作返回
LOCK_NETWORK_STATUE 门锁联网状态
LOCK_DISPATCH_INFO_RESP 调度设备信息
data 必选 Object body 消息数据

Object-->LOCK_DEVICE_DATA_CHANGED-->LOCK_OPEN_DOOR
参数 约束 类型 位置 描述
userID 必须 string body 用户 ID
openType 必须 string body 同用户类型
time 必须 string body 时间格式：yyyy-MM-dd HH:mm:ss，
如 2019-09-20 15:33:01
remainTimes 可选 integer body 剩余次数

28
Object-->LOCK_DEVICE_DATA_CHANGED-->LOCK_ABNORMAL_ALARM
参数 约束 类型 位置 描述
eventType 必须 string body 异常报警类型
ALARM_FREQUENCY_ANORMALY 超过 5 次
ALARM_PRY_LOCK 撬锁
ALARM_LOW_POWER 低电
ALARM_FORCED 胁迫
eventTypeDesc 可选 string body 异常描述
time 必须 string body 时间格式：yyyy-MM-dd HH:mm:ss，
如 2019-09-20 15:33:01

Object-->LOCK_DEVICE_DATA_CHANGED-->LOCK_SYNC_USER
参数 约束 类型 位置 描述
type 必须 string body 操作类型
* USER_ADD 添加用户
* USER_DEL 删除用户
* LOCK_RESET 重置门锁
userID 必须 string body 用户 ID
* 若值为-10 则为删除所有普通用户
userType 必须 string body 同用户类型
time 必须 string body 时间格式：yyyy-MM-dd HH:mm:ss，
如 2019-09-20 15:33:01

Object-->LOCK_DEVICE_DATA_CHANGED-->LOCK_HEART_BEAT
参数 约束 类型 位置 描述
time 必须 string body 时间格式：yyyy-MM-dd HH:mm:ss，
如 2019-09-20 15:33:01

Object-->LOCK_DEVICE_DATA_CHANGED-->LOCK_OPERATION_RESP
参数 约束 类型 位置 描述
deviceId 必须 string body 设备 Id
type 必须 string body 操作类型
* USER_ADD 添加用户
* USER_DEL 删除用户
* USER_CLEAN 清空用户
* USER_ENABLE 启用用户
* USER_DISABLE 禁用用户
* LOCK_CONFIG 配置门锁信息
* LOCK_VERIFY 验证门锁设备
* LOCK_REMOTE_OPEN 远程开锁
* LOCK_RESET 重置门锁
* USER_CHANGE_PWD 修改密码
code 必须 Integer body 返回码
msg 必须 string body 返回码描述
data 必须 json body 根据不同的类型，返回不同的推送,详见每条命令的返回

29
Object-->LOCK_DEVICE_DATA_CHANGED--> LOCK_ NETWORK_STATUE
参数 约束 类型 位置 描述
必须 Integer body 联网状态
0：联机
networkStatue
1：脱机
2：异常

Object-->LOCK_DEVICE_DATA_CHANGED--> LOCK_DISPATCH_INFO_RESP
参数 约束 类型 描述
deviceId 必须 string body
type 必须 string *LOCK_DISPATCH_INFO
code 必须 Integer 返回码
msg 必须 string 返回码描述
data 必须 json 参考设备接口（3.1）查询设备列表,详情参考【DeviceInfo
数据结构】

5.3 返回码

Http 状态码 错误码 错误描述 错误说明

401 100002 Invalid access token. 错误的 token 信息
401 100006 Refresh access token failed. accessToken 刷新失败
400 100007 Bad request. 参数不合法
400 100022 The input is invalid. 输入参数无效
401 100025 AppId for auth not exist. 获取不到 appId 鉴权信息
500 100203 The application is not existed. 应用不存在
401 100208 AppId or secret is not right. appId 或 secret 错误
403 100217 The application hasn't been authorized. 应用未被授权
500 100412 The amount of device has reached the 当前应用下设备数量达到上限
limit.

5.4 注册回调地址

5.4.1 请求数据

URL https://server:port/api/v1/smartlock/subscribe
Method POST
HEADER
元素 取值 取值说明
30
 appId 应用身份标识
accessToken 鉴权参数，访问设备管理平台API接口的凭证
PARAM（Json字符串）
序号 元素名称 约束 类型 位置 取值说明
1 devType 必选 Integer body 设备类型：1-门锁
2 callbackUrl 必选 String Body 回调地址

5.4.2 响应数据

URL 无
Method 无
HEADER
元素 取值 取值说明
Content-Type application/json 数据格式

PARAM
序号 元素名称 约束 类型 位置 取值说明
1 code 必选 Integer 1 0-成功
2 message 必选 String 1
3 desc 必选 String 1
4 data 必选 1

31