智能门锁

状态码说明

状态码	说明
200	操作成功
-1	未知错误
10001	授权账号无效
10002	设备不存在
10003	设备已被注册
10004	设备已过有效使用期
10005	无此设备操作权限
10009	设备未激活或未初始化
10011	参数缺失
10012	参数无效
10021	数据不存在
10031	不支持此操作
10032	设备连接超时
10032	处理中，请稍候再试
10101	钥匙下发超过最大存储数量
10102	触发密码安全规则
10103	设备需要重新配置网络
10108	离线密码周期前后规则不匹配

INFO

注意：

1：基于「获取门锁列表」数据绑定到三方系统则可不进行「门锁注册」

2：非基于「获取门锁列表」数据绑定到三方系统，必须使用序列号进行「门锁注册」

3：「门锁取消注册」操作则会直接解绑删除星寓IoT平台数据，须谨慎操作

API列表

获取门锁列表

TIP

URI：/openapi/v2/lock/list_page
Method：POST
需要鉴权：是

请求参数

字段名	类型	是否必填	字段说明
name	String	否	门锁名称，支持模糊检索
sn	String	否	设备序列号，支持模糊检索
current	Integer	是	当前页，从1开始
size	Integer	是	每页记录数，最大100

响应参数

字段名	类型	字段说明
productGen	String	产品世代；Gen1：第一代，Gen2：第二代
lockId	String	门锁ID
type	Integer	类型；101：WiFi锁；102：NB锁；103：LoRa锁；104：蓝牙锁；105：网关锁
sn	String	设备序列号
name	String	门锁名称

外层分页结构示例

json

{
    "total": 200, //总记录数
    "current": 1, //当前页
    "size": 100, //每页条数
    "records": [
      
    ] //数组数据
}

获取门锁信息

TIP

URI：/openapi/v2/lock/get_lock_info
Method：POST
需要鉴权：是

请求参数

字段名	类型	是否必填	约束	字段说明
lockId	String	否		注册成功返回的门锁ID；与sn不能都为空
sn	String	否	8位长度字符串	设备序列号；与lockId不能都为空

响应参数

字段名	类型	字段说明
productGen	String	产品世代；Gen1：第一代，Gen2：第二代
isInitialized	Integer	是否已初始化；1：是；0：否
lockId	String	门锁ID
type	Integer	类型；101：WiFi锁；102：NB锁；103：LoRa锁；104：蓝牙锁；105：网关锁
sn	String	设备序列号
macAddr	String	联网网卡地址
bluetoothAddr	String	蓝牙地址
isNetworkConfigured	Integer	是否已配网；1：已配置；0：未配置
onlineStatus	Integer	在线状态；1：在线；2：离线
lastOnlineTime	String	最后在线时间；格式：yyyy-MM-dd HH:mm:ss
power	Integer	设备电量；百分比值
syncFrequency	Integer	设备同步频率；正整数，单位为小时，取值范围 1-24

门锁注册

TIP

URI：/openapi/v2/lock/registration
Method：POST
需要鉴权：是

请求参数

字段名	类型	是否必填	约束	字段说明
sn	String	是	8位长度字符串	设备序列号
name	String	否	1 到 20 个字符	设备自定义名称
installAddress	String	是	1 到 20 个字符	设备安装地址
adminPwd	String	否	6位长度数字组合	管理员密码

响应参数

字段名	类型	字段说明
productGen	String	产品世代；Gen1：第一代，Gen2：第二代
isInitialized	Integer	是否已初始化；1：是；0：否
lockId	String	门锁ID
type	Integer	类型；101：WiFi锁；102：NB锁；103：LoRa锁；104：蓝牙锁；105：网关锁
sn	String	设备序列号
macAddr	String	联网网卡地址
bluetoothAddr	String	蓝牙地址
isNetworkConfigured	Integer	是否已配网；1：已配置；0：未配置
onlineStatus	Integer	在线状态；1：在线；2：离线
lastOnlineTime	String	最后在线时间；格式：yyyy-MM-dd HH:mm:ss
power	Integer	设备电量；百分比值
syncFrequency	Integer	设备同步频率；正整数，单位为小时，取值范围 1-24

门锁取消注册

TIP

URI：/openapi/v2/lock/unregistration
Method：POST
需要鉴权：是

请求参数

字段名	类型	是否必填	约束	字段说明
lockId	String	是		注册成功返回的门锁ID

响应参数

无响应业务参数，请求执行成功即表示取消注册成功

更新同步频率

TIP

URI：/openapi/v2/lock/update_sync_frequency
Method：POST
需要鉴权：是

请求参数

仅WiFi门锁支持设置此项

字段名	类型	是否必填	约束	字段说明
lockId	String	是		注册成功返回的门锁ID
syncFrequency	Interger	是	正整数，单位为小时，取值范围 1-24	设置门锁自动定时上报数据

响应参数

无响应业务参数，请求执行成功即表示更新同步频率设置成功

数据同步

TIP

URI：/openapi/v2/lock/data_sync
Method：POST
需要鉴权：是

请求参数

字段名	类型	是否必填	约束	字段说明
lockId	String	是		注册成功返回的门锁ID

响应参数

无响应业务参数，请求执行成功即表示更数据同步调用成功

设置管理员密码

TIP

URI：/openapi/v2/lock/set_admin_pwd
Method：POST
需要鉴权：是

请求参数

字段名	类型	是否必填	约束	字段说明
lockId	String	是		注册成功返回的门锁ID
pwdContent	String	是	6位长度数字组合	管理员密码

响应参数

字段名	类型	字段说明
isNeedBleSync	Interger	是否需要蓝牙同步，1：需要 0：不需要（当密码无法实时下发至门锁内部时需要蓝牙同步）

添加密码

TIP

URI：/openapi/v2/lock/add_pwd
Method：POST
需要鉴权：是

请求参数

字段名	类型	是否必填	约束	字段说明
lockId	String	是		注册成功返回的门锁ID
type	Integer	是	1或2或3	密码类型；1：在线密码 2：离线密码 3：激活密码
isWithBleKey	Integer	否	1或0	是否同步下发蓝牙钥匙；1：是 0：否
startTime	String	是		密码周期开始时间；格式：yyyy-MM-dd HH:mm:ss 在线密码支持时间精度到秒离线/激活密码只能到小时
endTime	String	是		密码周期结束时间；格式：yyyy-MM-dd HH:mm:ss 在线密码支持时间精度到秒离线/激活密码只能到小时
ownerName	String	是	1 到 20 个字符	被授权人姓名
ownerPhone	String	是	手机号	被授权人手机号

响应参数

字段名	类型	字段说明
isNeedBleSync	Interger	是否需要蓝牙同步，1：需要 0：不需要（当密码无法实时下发至门锁内部时需要蓝牙同步）
pwdId	String	密码ID
pwdContent	String	密码内容
activationCode	String	激活码（仅下发激活密码有此项返回）
bleKeyId	String	仅当设置 isWithBleKey = 1 时，且门锁支持蓝牙解锁下会返回

获取动态码

激活码从获取成功开始5分钟内有效，仅能使用一次

TIP

URI：/openapi/v2/lock/get_dynamic_pwd
Method：POST
需要鉴权：是

请求参数

字段名	类型	是否必填	约束	字段说明
lockId	String	是		注册成功返回的门锁ID
ownerName	String	否	1 到 20 个字符	被授权人姓名
ownerPhone	String	否	手机号	被授权人手机号

响应参数

字段名	类型	字段说明
pwdId	String	激活码ID
pwdContent	String	激活码内容
startTime	String	激活码有效期开始时间；格式：yyyy-MM-dd HH:mm:ss
endTime	String	激活码有效期结束时间；格式：yyyy-MM-dd HH:mm:ss

更新开锁权限

支持修改的钥匙类别：密码、蓝牙钥匙、门卡、指纹、人脸；离线密码、动态码不支持修改；激活密码仅当激活后修改才会生效

TIP

URI：/openapi/v2/lock/update_unlock_auth
Method：POST
需要鉴权：是

请求参数

密码内容与有效期时间开始结束必传其一

字段名	类型	是否必填	约束	字段说明
lockId	String	是		注册成功返回的门锁ID
authId	String	是		权限ID(密码ID/蓝牙钥匙ID/门卡ID/指纹ID/人脸ID)
pwdContent	String	否	6位长度数字组合	密码内容；修改密码时此项有效
startTime	String	否		权限有效期开始时间；格式：yyyy-MM-dd HH:mm:ss
endTime	String	否		权限有效期结束时间；格式：yyyy-MM-dd HH:mm:ss

响应参数

字段名	类型	字段说明
isNeedBleSync	Interger	是否需要蓝牙同步，1：需要 0：不需要（当密码无法实时下发至门锁内部时需要蓝牙同步）

冻结开锁权限

TIP

URI：/openapi/v2/lock/freeze_unlock_auth
Method：POST
需要鉴权：是

请求参数

字段名	类型	是否必填	约束	字段说明
lockId	String	是		注册成功返回的门锁ID
authId	String	是		权限ID(密码ID/蓝牙钥匙ID/门卡ID/指纹ID/人脸ID)

响应参数

字段名	类型	字段说明
isNeedBleSync	Interger	是否需要蓝牙同步，1：需要 0：不需要（当密码无法实时下发至门锁内部时需要蓝牙同步）

解除冻结开锁权限

TIP

URI：/openapi/v2/lock/unfreeze_unlock_auth
Method：POST
需要鉴权：是

请求参数

字段名	类型	是否必填	约束	字段说明
lockId	String	是		注册成功返回的门锁ID
authId	String	是		权限ID(密码ID/蓝牙钥匙ID/门卡ID/指纹ID/人脸ID)

响应参数

字段名	类型	字段说明
isNeedBleSync	Interger	是否需要蓝牙同步，1：需要 0：不需要（当密码无法实时下发至门锁内部时需要蓝牙同步）

删除开锁权限

TIP

URI：/openapi/v2/lock/delete_unlock_auth
Method：POST
需要鉴权：是

请求参数

字段名	类型	是否必填	约束	字段说明
lockId	String	是		注册成功返回的门锁ID
authId	String	是		权限ID(密码ID/蓝牙钥匙ID/门卡ID/指纹ID/人脸ID)

响应参数

字段名	类型	字段说明
isNeedBleSync	Interger	是否需要蓝牙同步，1：需要 0：不需要（当密码无法实时下发至门锁内部时需要蓝牙同步）

事件通知

INFO

重要：须先在「星寓互联」微信小程序设置全局事件通知地址，接入方须使用POST application/json接收数据推送

事件通知类型包含：

DL01 -> 设备在线

DL02 -> 设备离线

DL03 -> 设备电量

DL04 -> 开锁记录

DL05 -> 告警记录

DL11 -> 钥匙操作已同步至设备

设备在线

json

{
    "data": {
        "lockIds": "56a9b75719054f30b4688b0c58810546,ec322decb5494b96bd6571f1f96ba460"
    },
    "eventType": "DL01"
}

设备离线

json

{
    "data": {
        "lockIds": "56a9b75719054f30b4688b0c58810546,ec322decb5494b96bd6571f1f96ba460"
    },
    "eventType": "DL02"
}

设备电量

json

{
    "data": {
        "lockId": "c6406233537141d79e38127751f6b9e3",
        "power": 99  //电量百分比值
    },
    "eventType": "DL03"
}

开锁记录

json

{
    "data": {
        "lockId": "868f6a5b33644c659dcbc93ea57223b2",
        "list": [
            {
                "unlockMethod": 2,  //开锁方式：1-管理员密码 2-普通密码 3-离线密码 4-指纹 5-蓝牙钥匙 6-门卡 7-人脸
                "unlockTime": "2023-12-13 18:30:35", //开锁时间
                "operatorName": "张三",  //开锁人
                "operatorPhone": "18987654321"  //开锁人手机号
            }
        ]
    },
    "eventType": "DL04"
}

告警记录

json

{
    "data": {
        "lockId": "7eceb89c728c435eaab97323f90b4c41",
        "list": [
            {
                "alarmType": 2, //告警类型： 0-未知 1-指纹不匹配 2-密码错误 3-门卡不匹配 4-撬锁
                "alarmTime": "2023-12-01 09:49:56" //告警时间
            }
        ]
    },
    "eventType": "DL05"
}

钥匙操作已同步至设备

json

{
    "data": {
        "lockId": "7eceb89c728c435eaab97323f90b4c41",
        //钥匙ID，多个使用半角逗号隔开
        "keyIds": "6d6a106bf03440d7b17c8e06171587b5,f5883742c0c44f59852eed606e23067b"
    },
    "eventType": "DL11"
}

智能门锁 ​

状态码说明 ​

API列表 ​

获取门锁列表 ​

请求参数 ​

响应参数 ​

外层分页结构示例 ​

获取门锁信息 ​

请求参数 ​

响应参数 ​

门锁注册 ​

请求参数 ​

响应参数 ​

门锁取消注册 ​

请求参数 ​

响应参数 ​

更新同步频率 ​

请求参数 ​

响应参数 ​

数据同步 ​

请求参数 ​

响应参数 ​

设置管理员密码 ​

请求参数 ​

响应参数 ​

添加密码 ​

请求参数 ​

响应参数 ​

获取动态码 ​

请求参数 ​

响应参数 ​

更新开锁权限 ​

请求参数 ​

响应参数 ​

冻结开锁权限 ​

请求参数 ​

响应参数 ​

解除冻结开锁权限 ​

请求参数 ​

响应参数 ​

删除开锁权限 ​

请求参数 ​

响应参数 ​

事件通知 ​

设备在线 ​

设备离线 ​

设备电量 ​

开锁记录 ​

告警记录 ​

钥匙操作已同步至设备 ​

智能门锁

状态码说明

API列表

获取门锁列表

请求参数

响应参数

外层分页结构示例

获取门锁信息

请求参数

响应参数

门锁注册

请求参数

响应参数

门锁取消注册

请求参数

响应参数

更新同步频率

请求参数

响应参数

数据同步

请求参数

响应参数

设置管理员密码

请求参数

响应参数

添加密码

请求参数

响应参数

获取动态码

请求参数

响应参数

更新开锁权限

请求参数

响应参数

冻结开锁权限

请求参数

响应参数

解除冻结开锁权限

请求参数

响应参数

删除开锁权限

请求参数

响应参数

事件通知

设备在线

设备离线

设备电量

开锁记录

告警记录

钥匙操作已同步至设备