智能门锁开放能力

更新时间：2024-06-25 02:14:34下载pdf

本文介绍了使用云开发进行智能门锁的开发的相关流程和 API。智能门锁云开发对接类型主要针对客户自建服务器实现门锁相关业务，包括但不限于 微信小程序、 Web 系统、H5 应用。

对接流程

在对接门锁垂直品类业务前，您需要注册成为涂鸦开发者，相关详情请参考云开发-快速入门。

涂鸦智能门锁云开发对接流程如下图所示：

智能门锁开放能力

适用品类

通讯协议	适用门锁品类
Wi-Fi	Wi-Fi 家庭门锁 Pro、Wi-Fi 家庭门锁、Wi-Fi 保险箱
BLE	蓝牙门锁（包括带网关功能的蓝牙门锁）
Zigbee	Zigbee 家庭门锁 Pro、Zigbee 家庭门锁

接口日志

涂鸦可提供以当前时间计，最近 7 天以内的接口调用日志查询。开发者可提供接口请求参数，在开发者平台以工单的形式提交，涂鸦工作人员会尽快处理。工单一般在两小时以内做出答复，如紧急问题，可通过线下渠道找项目经理加速处理。

API 列表

下表罗列了智能门锁使用的 API ：

请求方式	API	说明
POST	/v1.0/devices/{device_id}/door-lock/password-ticket	获取密码加密的临时秘钥
POST	/v1.0/devices/{device_id}/door-lock/temp-password	创建临时密码（支持周期性密码）
POST	/v2.0/devices/{device_id}/door-lock/temp-password	创建无名称的临时密码（支持周期性密码）
POST	/v1.0/devices/{device_id}/door-lock/issue-password	同步密码
GET	/v1.0/devices/{device_id}/door-lock/temp-password/{password_id}	获取临时密码信息
GET	/v1.0/devices/{device_id}/door-lock/temp-passwords	获取临时密码列表
GET	/v1.0/smart-lock/devices/{device_id}/stand-by-lock-temp-passwords	获取常保活的临时密码列表
PUT	/v1.0/devices/{device_id}/door-lock/temp-passwords/{password_id}/modify-password	修改临时密码
PUT	/v1.0/devices/{device_id}/door-lock/temp-passwords/{password_id}/freeze-password	冻结临时密码
PUT	/v1.0/devices/{device_id}/door-lock/temp-passwords/{password_id}/unfreeze-password	解冻临时密码
DELETE	/v1.0/devices/{device_id}/door-lock/temp-passwords/{password_id}	删除临时密码
POST	/v1.0/devices/{device_id}/door-lock/offline-temp-password	获取离线密码
POST	/v1.1/devices/{device_id}/door-lock/offline-temp-password	获取离线密码-v1.1
PUT	/v1.0/devices/{device_id}/door-lock/offline-temp-password/{password_id}	更新离线密码的名称
GET	/v1.0/devices/{device_id}/door-lock/dynamic-password	获取动态密码
POST	/v1.0/devices/{device_id}/user	新增设备成员（非家庭成员）
PUT	/v1.0/devices/{device_id}/users/{user_id}	修改设备成员（非家庭成员）
PUT	/v1.0/smart-lock/devices/{device_id}/users/{user_id}/actions/role	更新设备用户的角色
DELETE	/v1.0/devices/{device_id}/users/{user_id}	删除设备成员（非家庭成员）
GET	/v1.0/devices/{device_id}/users/{user_id}	查询设备成员信息（非家庭成员）
GET	/v1.1/devices/{device_id}/users/{user_id}	查询设备成员信息（v1.1），支持获取当前用户的信息
GET	/v1.0/devices/{device_id}/users	根据设备 ID查询成员信息列表（非家庭成员）
GET	/v1.1/devices/{device_id}/users	根据设备 ID查询成员信息列表（非家庭成员）-v1.1
POST	/v1.0/devices/{device_id}/device-lock/users/{user_id}/allocate	分配门锁密码给设备成员（非家庭成员）
POST	/v1.0/devices/{device_id}/door-lock/opmodes/actions/allocate	将未分配的解锁方式分配给用户（支持同时分配多个）
GET	/v1.0/smart-lock/users/{uid}/devices	获取用户帐号所关联的设备
GET	/v1.0/devices/{device_id}/door-lock/user-types/{user_type}/users/{user_id}/assigned-keys	获取门锁成员已绑定的解锁方式列表（家庭成员）
GET	/v1.0/devices/{device_id}/door-lock/unassigned-keys	获取门锁成员未绑定的解锁方式列表（家庭成员）
POST	/v1.0/smart-lock/devices/{device_id}/opmodes/actions/sync	云端发起解锁方式同步
PUT	/v1.0/devices/{device_id}/door-lock/actions/entry	门锁解锁方式录入（家庭成员）
DELETE	/v1.0/devices/{device_id}/door-lock/user-types/{user_type}/users/{user_id}/unlock-types/{unlock_type}/keys/{unlock_no}	门锁解锁方式删除（家庭成员）
PUT	/v1.0/devices/{device_id}/door-lock/unlock-types/{unlock_type}/actions/cancel	取消录入解锁方式（家庭成员）
PUT	/v1.0/devices/{device_id}/door-lock/opmodes/{unlock_sn}	更新解锁方式名称
PUT	/v1.0/devices/{device_id}/door-lock/unlock-types/{unlock_type}/keys/{unlock_no}/hijack	设置解锁方式为挟持解锁（家庭成员）
GET	/v1.0/devices/{device_id}/door-lock/open-logs	查询开门记录
^*GET	/v1.1/devices/{device_id}/door-lock/open-logs	查询开门记录
GET	/v1.0/devices/{device_id}/door-lock/alarm-logs	获取门锁告警记录
^*GET	/v1.1/devices/{device_id}/door-lock/alarm-logs	获取门锁告警记录
GET	/v1.0/devices/{device_id}/door-lock/records	获取门锁告警记录和开门记录
POST	/v1.0/devices/{device_id}/door-lock/records/{record_id}/actions/allocate	将历史记录关联给某个用户
POST	/v1.0/devices/{device_id}/door-lock/temp-passwords/rest-password	清空临时密码
GET	/v1.0/devices/{device_id}/door-lock/remote-unlocks	获取门锁支持的远程开门方式
POST	/v1.0/devices/{device_id}/door-lock/remote-unlock/config	设置门锁远程开门方式的开关
POST	/v1.0/devices/{device_id}/door-lock/open-door	门锁含密开门
POST	/v1.0/devices/{device_id}/door-lock/password-free/open-door	门锁免密开门
POST	/v1.1/devices/{device_id}/door-lock/password-free/open-door	门锁免密开门（v1.1），支持对特定通道执行开门动作
PUT	/v1.0/devices/{device_id}/door-lock/password-free/open-door/cancel	门锁免密开门撤销
GET	/v1.0/devices/{device_id}/door-lock/latest/media/url	获取最近一次的远程开门或告警封面图
POST	/v1.0/devices/{device_id}/door-lock/advanced-password	设置高级密码
GET	/v1.0/devices/{device_id}/door-lock/advanced-password	查询高级密码
GET	/v1.0/devices/{device_id}	获取设备信息（这里可以获取local key用于加解密密码）
GET	/v1.0/smart-lock/devices/{device_id}/users	获取家庭用户和解锁方式的信息列表
PUT	/v1.0/smart-lock/devices/{device_id}/users/{user_id}/schedule	更新家庭用户的时效
GET	/v1.0/smart-lock/devices/{device_id}/albums-media	获取相册列表
GET	/v1.0/devices/{device_id}/door-lock/absent-users	获取被移除的用户列表
POST	/v1.0/smart-lock/devices/{device_id}/users/{user_ids}/actions/delete-users-issue	控制门锁设备删除用户
GET	/v1.0/smart-lock/devices/{device_id}/opmodes/{user_id}	获取用户的解锁方式列表
DELETE	/v1.0/smart-lock/devices/{device_id}/unlock-types/{unlock_type}/keys/{unlock_sn}/hijack	删除解锁方式的挟持解锁
POST	/v1.0/smart-lock/devices/{device_id}/password-ticket	获取密码加密的临时秘钥
POST	/v1.0/smart-lock/devices/{device_id}/password-free/door-operate	远程免密开关门
GET	/v1.0/smart-lock/devices/{device_id}/media-view-times	查询当前设备已经观看视频次数
POST	/v1.0/smart-lock/devices/{device_id}/media-view-times	当前设备已经观看视频次数+1
POST	/v1.0/smart-lock/devices/{device_id}/opmodes/{opmode_id}/attribute/{attribute}/opmode-attr	解锁方式设置开启拍照属性

说明： 标注星号（*）的 API 仅支持老版本。

您还可以参考以下文档了解更多详情：

文档	适用功能
涂鸦开放平台-标准指令集	门锁设置，如音量调节、语言切换
涂鸦开放平台-设备控制	获取设备标准指令集
全局错误码	查看功能开发中会产生的全局错误码

密码创建流程

Wi-Fi 门锁处理流程：
Zigbee 门锁处理流程：
- Zigbee 门锁正常业务流程
  - 调用方调用API创建密码
  - 涂鸦云平台下发密码给网关
  - 网关下发密码给门锁
  - 门锁响应密码状态：配置成功
  - 网关上报密码状态：配置成功
  - 涂鸦云平台存储更新密码状态：配置成功
  - 调用方轮询密码状态，直至密码状态更新为：配置成功/配置失败，轮询超时间为 25 秒
- Zigbee 门锁异常业务流程
  - 调用方调用 API 获取门锁信息
  - 调用方调用 API 创建密码（使用门锁 localkey加密）
  - 涂鸦云平台下发密码给网关
  - 网关下发密码给门锁
  - 门锁未响应状态
  - 网关重试下发密码，重试 3 次结束
  - 网关上报密码状态：配置失败
  - 涂鸦云平台存储更新密码状态：配置失败
  - 调用方轮询密码状态，直至密码状态更新为：配置成功/配置失败，轮询超时时间为 25 秒

密码加密流程

智能门锁开放能力

Wi-Fi门禁的一些说明

用户体系介绍

设备配网者属于家庭用户体系
其他用户属于非家庭用户体系

角色跟权限介绍

Wi-Fi 门禁的角色类型

超级管理员（设备拥有者）
管理员
普通成员

各角色的权限定义(建议)

建议向下管理，平级不能查看/操作，具体如下:

设备拥有者，可以添加/更新/删除任意成员的数据 (不能删除自己)。
管理员可以管理自己的数据和普通成员的数据；不能查看/管理其他管理员的数据。
普通成员只能查看/操作自己的数据。

门锁 API

获取密码加密的临时秘钥

支持的门锁类型

Wi-Fi 门锁
Zigbee 门锁
蓝牙门锁
酒店 Zigbee 门锁
可视对讲 Wi-Fi

接口地址

POST /v1.0/devices/{device_id}/door-lock/password-ticket

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是

请求示例

POST /v1.0/devices/vdevo153459260090544/door-lock/password-ticket

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	临时密码信息

result

参数名	类型	说明
ticket_id	String	临时秘钥 ID
ticket_key	String	临时秘钥 Key，需要根据云开发者 accessKey 通过 AES 解密后方可使用
expire_time	Long	剩余有效时间

请求成功返回示例

{
    "result": {
        "expire_time": 360,
        "ticket_id": "9wxxoLM",
        "ticket_key": "901CC35A67DA3429C38E9622xxxxx3EAE1CE333462356D257FD1D3E5C"
    },
    "success": true,
    "t": 1592899848757
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error,please contact the admin"
}

创建临时密码

支持的门锁类型

Wi-Fi 门锁
Zigbee 门锁
蓝牙门锁
酒店 Zigbee 门锁
常保活门锁
可视对讲 Wi-Fi
Wi-Fi 门禁

接口地址

POST /v1.0/devices/{device_id}/door-lock/temp-password

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是
name	String	BODY	临时密码名称	是
password	String	BODY	Wi-Fi 锁密码原文长度为 7位数字，Zigbee 锁/蓝牙锁原文密码为 6位数字，密码传输使用AES加密算法，模式：ECB pkcs7padding 数据块 128 位，秘钥为通过接口获取的临时 ticket_key 使用开发者 accessKey AES 解密后的原始秘钥，输出是格式是hex	是
effective_time	Long	BODY	生效时间，10 位时间戳，单位s	是
invalid_time	Long	BODY	过期时间，10 位时间戳，单位s	是
password_type	String	BODY	密码加密类型：ticket	是
ticket_id	String	BODY	临时秘钥 ID	是
phone	String	BODY	手机号码	否
type	Integer	BODY	门锁密码有效类型，1：一次性有效，0：有效范时间围内一直有效	Zigbee 时必填
time_zone	String	BODY	时区，需要周期性功能，则填入此项	否
schedule_list	List	BODY	周期性功能设置参数列表	否

schedule_list

参数名	类型	参数类型	说明	是否必填
effective_time	Long	BODY	当天开始时间，单位分钟	是
invalid_time	Long	BODY	当天过期时间，单位分钟	是
working_day	Int	BODY	星期, 每个值累加： 1：星期天 2：星期一 4：星期二 8：星期三 16：星期四 32：星期五 64：星期六	是

请求示例

POST /v1.0/devices/vdevo153459260090544/door-lock/temp-password

{
    "password": "956FAD7xxxxxx09C68E168B77",
    "password_type": "ticket",
    "ticket_id": "xxxxxx",
    "effective_time": 1579156726,
    "invalid_time": 1579243126,
    "name":"test",
    "phone": 11233213,
    "time_zone":"",
    "schedule_list":[{
        "effective_time": 720,
        "invalid_time": 1080,
        "working_day":  0
    }]
}

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	临时密码信息

result

参数名	类型	说明
id	Long	临时密码的编号

请求成功返回示例

{
    "success": true,
    "t": 1542626129429,
    "result": {
        "id": 124367346
    }
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error,please contact the admin"
}

创建无名称的临时密码

支持的门锁类型

Wi-Fi 门锁
Zigbee 门锁
蓝牙门锁
酒店Zigbee 门锁
可视对讲 Wi-Fi

接口地址

POST /v2.0/devices/{device_id}/door-lock/temp-password

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是
password	String	BODY	Wi-Fi 锁密码原文长度为 7，Zigbee 锁/蓝牙锁原文密码为 6，密码，传输使用加密算法使用 AES，模式：ECB pkcs7padding 数据块 128 位，秘钥为通过接口获取的临时 ticket_key 使用开发者 accessKey AES 解密后的原始秘钥	是
effective_time	Long	BODY	生效时间，10 位时间戳，单位s	是
invalid_time	Long	BODY	过期时间，10 位时间戳，单位s	是
password_type	String	BODY	密码加密类型：ticket	是
ticket_id	String	BODY	临时秘钥ID	是
phone	String	BODY	手机号码	否
type	Integer	BODY	门锁密码有效类型，1：一次性有效，0：有效范时间围内一直有效	Zigbee 时必填
time_zone	String	BODY	时区，需要周期性功能，则填入此项	否
schedule_list	List	BODY	周期性功能设置参数列表	否

schedule_list

参数名	类型	参数类型	说明	是否必填
effective_time	Long	BODY	当天开始时间，单位分钟	是
invalid_time	Long	BODY	当天过期时间，单位分钟	是
working_day	Int	BODY	星期, 每个值累加： 1：星期天 2：星期一 4：星期二 8：星期三 16：星期四 32：星期五 64：星期六	是

请求示例

POST /v2.0/devices/vdevo153459260090544/door-lock/temp-password

{
    "password": "956FAD7xxxxxx09C68E168B77",
    "password_type": "ticket",
    "ticket_id": "xxxxxx",
    "effective_time": 1579156726,
    "invalid_time": 1579243126,
    "phone": 11233213,
    "time_zone":"",
    "schedule_list":[{
        "effective_time": 720,
        "invalid_time": 1080,
        "working_day":  0
    }]
}

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	临时密码信息

result

参数名	类型	说明
id	Long	临时密码的编号

请求成功返回示例

{
    "success": true,
    "t": 1542626129429,
    "result": {
        "id": 124367346
    }
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error,please contact the admin"
}

同步密码

支持的门锁类型

Zigbee 门锁

说明： Zigbee 门锁创建密码后，密码状态仍处于"配置中"，可调用该接口将服务器中处于“配置中”的密码同步给门锁，该接口同一个设备 60 秒内只允许下发一次。

接口地址

POST /v1.0/devices/{device_id}/door-lock/issue-password

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是
password_id	Long	BODY	密码 ID，不填则下发门锁当前所有处于配置中的密码给门锁	否

请求示例

POST /v1.0/devices/vdevo153459260090544/door-lock/issue-password

{
   "password_id":""
}

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Boolean	返回结果

请求成功返回示例

{
    "success": true,
    "t": 1542626129429,
    "result": true
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error,please contact the admin"
}

获取临时密码信息

支持的门锁类型

Wi-Fi 门锁
Zigbee 门锁
蓝牙门锁
酒店Zigbee 门锁

接口地址

GET /v1.0/devices/{device_id}/door-lock/temp-password/{password_id}

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是
password_id	Long	URI	密码编号	是

请求示例

GET /v1.0/devices/vdevo153459260090544/door-lock/temp-password/xxxx

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	临时密码信息

result

参数名	类型	说明
id	Long	临时密码的编号
name	String	临时密码名称
phase	Integer	密码状态
effective_time	Long	生效时间，10 位时间戳
invalid_time	Long	过期时间，10 位时间戳
phone	String	手机号码
time_zone	String	时区
delivery_status	Integer	操作确认状态，1.配置中, 2.配置成功, 3.配置失败, 4.重复密码, 5.密码已满, 6.有效期重叠, Zigbee 时返回
schedule_list	List	周期性功能参数列表

schedule_list

参数名	类型	说明
effective_time	Long	当天开始时间，单位分钟
invalid_time	Long	当天过期时间，单位分钟
working_day	Int	星期, 每个值累加： 1：星期天 2：星期一 4：星期二 8：星期三 16：星期四 32：星期五 64：星期六

phase

Zigbee:
- 1：待创建
- 2：正常
- 3：已冻结
- 4：已删除
- 5：创建失败
Wi-Fi:
- 0：已删除
- 1：待下发
- 2：已下发
- 3：待删除
蓝牙:
- 0：已删除
- 1：待下发
- 2：已下发
- 3：待删除
- 7：下发失败

请求成功返回示例

{
    "success": true,
    "t": 1542626129429,
    "result": {
        "id": 1001, //临时密码主键
        "effective_time": 1530841779, //生效时间，10位
        "invalid_time": 1530881779, //失效时间，10位
        "name": "租客A的密码", //临时密码名称
        "phase": 1, //密码状态  
        "phone": "123547127362",
        "time_zone":"Asia/Shanghai",
        "delivery_status": 1
    }
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error, please contact the admin"
}

获取临时密码列表

支持的门锁类型

Wi-Fi 门锁
Zigbee 门锁
酒店 Zigbee 门锁
蓝牙门锁
可视对讲 Wi-Fi

接口地址

GET /v1.0/devices/{device_id}/door-lock/temp-passwords

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是
valid	Boolean	URL	是否有效	否

请求示例

GET /v1.0/devices/vdevo153459260090544/door-lock/temp-passwords?valid=true

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	已删除密码信息

result

参数名	类型	说明
id	Long	临时密码的编号
name	String	临时密码名称
phase	Integer	密码状态
effective_time	Long	生效时间，10 位时间戳
invalid_time	Long	过期时间，10 位时间戳
phone	String	手机号码
time_zone	String	时区
delivery_status	Integer	操作确认状态，1.配置中,2.配置成功,3.配置失败,4.重复密码,5.密码已满,6.有效期重叠，Zigbee 时返回
schedule_list	List	周期性功能参数列表

schedule_list

参数名	类型	说明
effective_time	Long	当天开始时间，单位分钟
invalid_time	Long	当天过期时间，单位分钟
working_day	Int	星期, 每个值累加： 1：星期天 2：星期一 4：星期二 8：星期三 16：星期四 32：星期五 64：星期六

phase

Zigbee:
- 1：待创建
- 2：正常
- 3：已冻结
- 4：已删除
- 5：创建失败
Wi-Fi:
- 0：已删除
- 1：待下发
- 2：已下发
- 3：待删除
蓝牙:
- 0：已删除
- 1：待下发
- 2：已下发
- 3：待删除
- 7：下发失败

请求成功返回示例

{
    "success": true,
    "t": 1542626129429,
    "result": [
        {
            "password_id": 1001, //临时密码主键
            "effective_time": 1530841779, //生效时间，10位
            "invalid_time": 1530881779, //失效时间，10位
            "name": "租客A的密码", //临时密码名称
            "phase": 1, //密码状态  
            "phone": "123547127362",
            "time_zone":"Asia/Shanghai",
            "delivery_status": 1
        }
    ]
}

获取保活门锁的临时密码列表

支持的门锁类型

常保活 Wi-Fi 门锁
Wi-Fi 门禁

接口地址

GET /v1.0/smart-lock/devices/{device_id}/stand-by-lock-temp-passwords

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是
valid	Boolean	URL	是否有效	否
lastRowKey	String	URL	查询分页记录时的行号（来自于返回结果的last_row_key，没有时传空）	否
pageSize	int	URL	每页记录数	否

请求示例

GET /v1.0/smart-lock/devices/vdevo12454656****/stand-by-lock-temp-passwords?valid=true&last_row_key=&page_size=10

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	删除密码信息

result

参数名	类型	说明
password_id	Long	临时密码的编号
name	String	临时密码名称
gmt_create	Long	临时密码的创建时间，单位为秒，长度 10 位
effective_time	Long	生效时间，10 位时间戳
expired_time	Long	过期时间，10 位时间戳
operate	String	操作: ADD：新增 MODIFY：修改 DELETE：删除
delivery_status	String	投递状态 ONGOING：下发中 SUCCESS：下发成功 FAILED：下发失败
effective_flag	int	生效状态： 0：无效 1：生效中 2：待生效（时间未到的情况）
schedule_details	List	周期性功能参数列表

schedule_list

参数名	类型	说明
start_minute	int	当天开始时间，单位分钟，最大值 1440
end_minute	int	当天过期时间，单位分钟, 最大值 1440
working_day	Int	星期, 每个值累加： 1：星期天 2：星期一 4：星期二 8：星期三 16：星期四 32：星期五 64：星期六
time_zone_id	String	时区

请求成功返回示例

{
  "has_more": false,
  "last_row_key": "ABCDEFG",
  "records": [
    {
      "delivery_status": "SUCCESS",
      "effective_flag": 1,
      "effective_time": 1628006400,
      "expired_time": 1628265540,
      "gmt_create": 1628088594,
      "name": "369369",
      "operate": "CREATE",
      "password_id": 3351004,
      "phone": "",
      "pwd_type_code": "temp",
      "schedule_details": [
        {
          "all_day": false,
          "start_minute": 0,
          "end_minute": 2359,
          "working_day": 101
        }
      ],
      "sn": 0
    }
  ]
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "系统异常,请联系管理员"
}

修改临时密码

支持的门锁类型

公版 Wi-Fi 门锁
公版 Zigbee 门锁
蓝牙门锁（不支持密码修改）
酒店 Zigbee 门锁
常保活 Wi-Fi 门锁
可视对讲 Wi-Fi
Wi-Fi 门禁

接口地址

PUT /v1.0/devices/{device_id}/door-lock/temp-passwords/{password_id}/modify-password

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是
password_id	Long	URI	密码 ID	是
password	String	BODY	Wi-Fi 锁密码原文长度为 7，Zigbee 锁原文密码为 6，蓝牙锁不支持密码修改，密码传输使用加密算法使用 AES，模式：ECB pkcs7padding 数据块128位，秘钥为通过接口获取的临时 ticket_key 使用开发者 accessKey AES解密后的原始秘钥	是
effective_time	Long	BODY	生效时间，10 位时间戳，单位s	是
invalid_time	Long	BODY	过期时间，10 位时间戳，单位s	是
password_type	String	BODY	密码加密类型：ticket	是
ticket_id	String	BODY	临时秘钥ID	是
phone	String	BODY	手机号码	否
type	Integer	BODY	门锁密码有效类型，1：一次性有效，0：有效范时间围内一直有效	Zigbee 时必填
time_zone	String	BODY	时区，需要周期性功能，则填入此项	否
schedule_list	List	BODY	周期性功能设置参数列表	否

schedule_list

参数名	类型	参数类型	说明	是否必填
effective_time	Long	BODY	当天开始时间，单位分钟	是
invalid_time	Long	BODY	当天过期时间，单位分钟	是
working_day	Int	BODY	星期, 每个值累加： 1：星期天 2：星期一 4：星期二 8：星期三 16：星期四 32：星期五 64：星期六	是

请求示例

PUT /v1.0/devices/vdevo153459260090544/door-lock/temp-passwords/{password_id}/modify-password

{
   "phone":"",
   "effective_time":"",
   "invalid_time":"",
   "password":"",
   "password_type":"ticket",
   "ticket_id":"xxx"
}

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	删除密码信息

请求成功返回示例

{
    "success": true,
    "t": 1542626129429,
    "result":true
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error,please contact the admin"
}

冻结临时密码

支持的门锁类型

Zigbee 门锁

接口地址

PUT /v1.0/devices/{device_id}/door-lock/temp-passwords/{password_id}/freeze-password

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是
password_id	String	URI	密码 ID	是

请求示例

PUT /v1.0/devices/vdevo153459260090544/door-lock/temp-passwords/xxx/freeze-password

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	删除密码信息

请求成功返回示例

{
    "success": true,
    "t": 1542626129429,
    "result":true
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error, please contact the admin"
}

解冻临时密码

支持的门锁类型

Zigbee 门锁

接口地址

PUT /v1.0/devices/{device_id}/door-lock/temp-passwords/{password_id}/unfreeze-password

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是
password_id	String	URI	密码 ID	是

请求示例

PUT /v1.0/devices/vdevo153459260090544/door-lock/temp-passwords/xxx/unfreeze-password

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	删除密码信息

请求成功返回示例

{
    "success": true,
    "t": 1542626129429,
    "result":true
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error, please contact the admin"
}

删除临时密码

支持的门锁类型

公版 Wi-Fi 门锁
公版 Zigbee 门锁
酒店 Zigbee 门锁
蓝牙门锁
常保活 Wi-Fi 门锁
可视对讲 Wi-Fi
Wi-Fi 门禁

接口地址

DELETE /v1.0/devices/{device_id}/door-lock/temp-passwords/{password_id}

请求参数

参数名	类型	参数类型	说明	是
device_id	String	URI	设备 ID	是
password_id	String	URI	密码 ID	是

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Boolean	结果

请求成功返回示例

{
    "success": true,
    "t": 1542626129429,
    "result": true
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error, please contact the admin"
}

获取动态密码

支持的门锁类型

Wi-Fi 门锁
Zigbee 门锁
蓝牙门锁

接口地址

GET /v1.0/devices/{device_id}/door-lock/dynamic-password

请求参数

参数名	类型	参数类型	说明	是
device_id	String	URI	设备 ID	是

请求示例

GET /v1.0/devices/vdevo153459260090544/door-lock/dynamic-password

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	动态密码信息

result

参数名	类型	说明
dynamic_password	String	动态密码

请求成功返回示例

{
    "success": true,
    "t": 1542626129429,
    "result": {
        "dynamic_password": "" 
    }
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error, please contact the admin"
}

获取离线临时密码

支持的门锁类型

公版 Wi-Fi 门锁
蓝牙门锁

接口地址

POST /v1.0/devices/{device_id}/door-lock/offline-temp-password

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是
effective_time	Long	BODY	生效时间，10 位时间戳	是
invalid_time	Long	BODY	失效时间，10 位时间戳	是
name	String	BODY	离线临时密码名称	否
type	Int	BODY	密码类型 0. 多次使用 1. 单次使用的密码 9. 清空所有密码（返回单次使用的密码）	是
lang	String	BODY	语言类型，中国区默认zh，其他区默认en	是

请求示例

POST /v1.0/devices/vdevo153459260090544/door-lock/offline-temp-password

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	动态密码信息

result

参数名	类型	说明
offline_temp_password	String	离线临时密码

请求成功返回示例

{
    "success": true,
    "t": 1542626129429,
    "result": {
        "offline_temp_password": ""
    }
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error, please contact the admin"
}

获取离线临时密码-v1.1

说明： 相比1.0 增加了对获取清空单个离线密码的支持

支持的门锁类型

公版 Wi-Fi 门锁
公版 Zigbee 门锁
公版蓝牙门锁
常保活 Wi-Fi 门锁
Wi-Fi 门禁

接口地址

POST: /v1.1/devices/{device_id}/door-lock/offline-temp-password

请求参数

参数名	类型	参数类型	是否必填	说明
device_id	String	uri	true	设备 ID
offline_pwd_add_request	OfflinePwdAddRequest	body	true	离线密码信息

offline_pwd_add_request 说明

参数名	类型	参数位置	是否必填	说明
effective_time	Long	时间戳	false	生效时间（秒） 1. MULTIPLE(0)时, 必填 2. ONCE(1)/CLEAR_ALL(9), 取当前时间的整点。例如当前时间=‘2021-01-23 22:11:12’, 则该字段的值=‘2021-01-23 22:00:00’ 3. MULTIPLE(0)/CLEAR_ONE(8)，如果该字段有值，取时间的整点。比如传的时间是=‘2021-01-27 15:11:12’, 则该字段的最终值=‘2021-01-27 15:00:00’
invalid_time	Long	时间戳	false	过期时间（秒） 1. MULTIPLE(0)时, 必填 2. ONCE(1), 该时间取当前时间的整点+6小时。例如，当前时间=‘2021-01-23 22:11:12’, 则该字段的值= ‘2021-01-24 04:00:00’ 3. CLEAR_ALL(9), 该时间是当前时间的整点+24小时。例如，当前时间=‘2021-01-23 22:11:12’, 则该字段的值= ‘2021-01-24 22:00:00’ 4. MULTIPLE(0)/CLEAR_ONE(8)，, 取时间的整点。例如，传的时间是=‘2021-01-27 15:11:12’, 则该字段的最终值=‘2021-01-27 15:00:00’
name	String		false	密码名称
type	String		false	类型，multiple, 可以重复使用的离线密码；once, 仅限一次使用的离线密码；clear_one, 清除单个离线密码；clear_all, 清除所有离线密码
password_id	String		false	密码 ID，只有type=clear_one 时才需要传该值

返回示例

参数名	类型	说明
result	OfflinePwdAddResponse	离线密码结果

result说明

参数名	类型	说明
offline_temp_password_id	String	密码 ID
offline_temp_password	String	密码内容
offline_temp_password_name	String	密码名称
effective_time	Long	生效时间（秒）
invalid_time	Long	过期时间（秒）

请求示例

POST: /v1.1/devices/6cdb36b2e489885fa57lzm/door-lock/offline-temp-password

返回示例

{
    "result": {
        "effective_time": 1623747600,
        "offline_temp_password_id": "2345011",
        "offline_temp_password": "0282554135",
        "invalid_time": 1623769200,
        "offline_temp_password_name": "name267"
    },
    "t": 1623748396631,
    "success": true
}

更新离线密码的名称

支持的门锁类型

公版蓝牙门锁
常保活 Wi-Fi 门锁
Wi-Fi 门禁

接口地址

PUT /v1.0/devices/{device_id}/door-lock/offline-temp-password/{password_id}

请求参数

参数名	类型	参数类型	是否必填	说明
device_id	String	URI	true	设备 ID
password_id	Long	URI	true	密码 ID
password_name	String	BODY	true	密码名称

请求示例

PUT /v1.1/devices/6cdb36b2e489885fa5****/door-lock/offline-temp-password

{
  "passwordName": "new0ne"
}

响应参数

参数	类型	说明
result	boolean	操作结果

响应成功示例

{
    "success": true,
    "t": 1571898808491,
    "result": true
}

查询开门记录

说明： 本 API 仅支持老版本。

支持的门锁类型

Wi-Fi 门锁
酒店 Zigbee 门锁
蓝牙门锁

接口地址

GET /v1.0/devices/{device_id}/door-lock/open-logs

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是
page_no	Integer	URL	页号	是
page_size	Integer	URL	分页大小	是
start_time	Long	URL	开始时间	是
end_time	Long	URL	结束时间	是

请求示例

GET /v1.0/devices/vdevo153459260090544/door-lock/open-logs?page_no=1&page_size=20&start_time=1543213146&end_time=1543213546

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	返回结果

result

参数名	类型	说明
total	Integer	记录数量
logs	List	开门记录列表

logs说明

参数名	类型	说明
status	List	门锁状态列表
update_time	Long	状态变更时间
unlock_name	String	解锁方式名称
user_id	String	成员 ID
nick_name	String	成员名称

status说明

参数名	类型	说明
code	String	状态码
value	Object	状态值

状态码说明

参数名	类型	说明
unlock_fingerprint	Long	指纹解锁，门锁本地分配的编号
unlock_password	Long	密码解锁，门锁本地分配的编号
unlock_temporary	Long	临时密码解锁，值为密码 ID
unlock_dynamic	Long	动态密码解锁，值为密码 ID
unlock_card	Long	卡片解锁，门锁本地分配的编号
unlock_face	Long	人脸解锁，门锁本地分配的编号
unlock_key	Long	机械钥匙解锁，门锁本地分配的编号
unlock_identity_card	Long	身份证解锁，门锁本地分配的编号
unlock_emergency	Long	应急密码解锁，门锁本地分配的编号

请求成功返回示例

{
    "success":true,
    "t":1542626129429,
    "result":{
        "total":1,
        "logs":[
            {
                "status":{
                    "code":"unlock_finger",
                    "value":"123456"
                },
		"nick_name":"",
                "unlock_name":"",
                "update_time":1612098422000,
                "user_id":"0"
            }
        ]
    }
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error, please contact the admin"
}

查询开门记录

支持的门锁类型

Wi-Fi 门锁
酒店 Zigbee 门锁
蓝牙门锁
可视对讲 Wi-Fi

接口地址

GET /v1.1/devices/{device_id}/door-lock/open-logs

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是
page_no	Integer	URL	页号	是
page_size	Integer	URL	分页大小	是
start_time	Long	URL	开始时间	是
end_time	Long	URL	结束时间	是
showMediaInfo	Boolean	URL	是否显示图片信息	否

请求示例

GET /v1.1/devices/6cdb36b2e489885fa57lzm/door-lock/open-logs?page_no=1&page_size=3&start_time=1553053133000&end_time=1614008938000&show_media_info=true

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	返回结果

result

参数名	类型	说明
total	Integer	记录数量
logs	List	开门记录列表

logs说明

参数名	类型	说明
status	List	门锁状态列表
update_time	Long	状态变更时间
unlock_name	String	解锁方式名称
user_id	String	成员 ID
nick_name	String	成员名称
media_infos	List	媒体信息

media_infos说明

参数名	类型	说明
file_url	String	封面图全路径
file_key	String	文件密钥
media_url	String	视频全路径
media_key	String	视频密钥

status说明

参数名	类型	说明
code	String	状态码
value	Object	状态值

状态码说明

参数名	类型	说明
unlock_fingerprint	Long	指纹解锁，门锁本地分配的编号
unlock_password	Long	密码解锁，门锁本地分配的编号
unlock_temporary	Long	临时密码解锁，值为密码 ID
unlock_dynamic	Long	动态密码解锁，值为密码 ID
unlock_card	Long	卡片解锁，门锁本地分配的编号
unlock_face	Long	人脸解锁，门锁本地分配的编号
unlock_key	Long	机械钥匙解锁，门锁本地分配的编号
unlock_identity_card	Long	身份证解锁，门锁本地分配的编号
unlock_emergency	Long	应急密码解锁，门锁本地分配的编号

请求成功返回示例

{
  "result": {
    "logs": [
      {
         "media_infos": [
          {
            "file_key": "uwu5m7kvj45av47g",
            "file_url": "https://..."
          }
        ],
        "nick_name": "",
        "status": {
          "code": "unlock_app",
          "value": "0"
        },
        "unlock_name": "",
        "update_time": 1613978384000,
        "user_id": "0"
      }
    ],
    "total": 1
  },
  "success": true,
  "t": 1614063791358
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error, please contact the admin"
}

获取门锁告警记录

说明： 本 API 仅支持老版本。

支持的门锁类型

Wi-Fi 门锁
Zigbee 门锁
酒店 Zigbee 门锁
蓝牙门锁

接口地址

GET /v1.0/devices/{device_id}/door-lock/alarm-logs

请求参数

参数名	类型	参数类型	说明	是否必须
device_id	String	URI	设备 ID	是
page_no	Integer	URL	页号	是
page_size	Integer	URL	分页大小	是
dp_codes	String	URL	告警功能标准功能 code，用半角逗号（,）隔开，默认查询通用告警	否

请求示例

GET /v1.0/devices/vdevo153459260090544/door-lock/alarm-logs?page_no=1&page_size=20&dp_codes=hijack

返回参数

参数名	类型	说明
code	Integer	错误响应码，成功时为空（详情⻅见错误码）
success	Boolean	是否成功：（true：成功，false：失败）
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	返回结果

result

参数名	类型	说明
total	Integer	记录数量
records	List	告警记录列表

records说明

参数名	类型	说明
status	List	门锁告警列表
update_time	Long	状态变更时间
nickName	String	用户名

status说明

参数名	类型	说明
code	String	告警标准码
value	Object	状态值（劫持告警的 value为：触发劫持的标准状态码-对应的状态 value）

请求成功返回示例

{
    "success":true,
    "t":1542626129429,
    "result":{
        "total":1,
        "records":[
            {
                "status":{
                    "code":"hijack",
                    "value":"unlock_fingerprint-02"
                },
                "update_time":1543297979
            }
        ]
    }
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error,please contact the admin"
}

获取门锁告警记录

支持的门锁类型

Wi-Fi 门锁
Zigbee 门锁
酒店 Zigbee 门锁
蓝牙门锁
可视对讲 Wi-Fi

接口地址

GET /v1.1/devices/{device_id}/door-lock/alarm-logs

请求参数

参数名	类型	参数类型	说明	是否必须
device_id	String	URI	设备 ID	是
page_no	Integer	URL	页号	是
page_size	Integer	URL	分页大小	是
codes	String	URL	告警功能标准功能 code，用半角逗号（,）隔开，默认查询通用告警	否
show_media_info	Boolean	URL	是否显示图片信息	否

请求示例

GET /v1.1/devices/6ca87475b5bfbaa716felz/door-lock/alarm-logs?page_size=20&codes=doorbell&showMediaInfo=true&page_no=1

返回参数

参数名	类型	说明
code	Integer	错误响应码，成功时为空（详情⻅见错误码）
success	Boolean	是否成功：（true：成功，false：失败）
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	返回结果

result

参数名	类型	说明
total	Integer	记录数量
records	List	告警记录列表

records说明

参数名	类型	说明
status	List	门锁告警列表
update_time	Long	状态变更时间
nickName	String	用户名
media_infos	List	媒体信息

media_infos说明

参数名	类型	说明
file_url	String	封面图全路径
file_key	String	文件密钥
media_url	String	视频全路径
media_key	String	视频密钥

status说明

参数名	类型	说明
code	String	告警标准码
value	Object	状态值（劫持告警的 value 为：触发劫持的标准状态码-对应的状态 value）

请求成功返回示例

{
    "result": {
        "records": [
            {
                "media_infos": [
                    {
                        "file_key": "jxmgqs59gfr899qe",
                        "file_url": "https://ty-cn-storage60-1254153901.cos.tuyacn.com/"
                    }
                ],
                "nick_name": "",
                "status": [
                    {
                        "code": "alarm_lock",
                        "value": "wrong_password"
                    }
                ],
                "update_time": 1613979671000
            }
        ],
        "total": 1
    },
    "success": true,
    "t": 1614152402757
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error,please contact the admin"
}

获取门锁告警记录和开门记录

支持的门锁类型

Wi-Fi 门禁

接口地址

GET /v1.0/devices/{device_id}/door-lock/records

请求参数

参数名	类型	参数类型	说明	是否必须
device_id	String	URI	设备 ID	是
target_standard_dp_codes	String	QUERY	需要查询的目标 dpCode (多个时以逗号分割)	是
start_time	Long	QUERY	时间范围的开始时间，不需要时间范围时传 0	是
end_time	Long	QUERY	时间范围的结束时间，不需要时间范围时传 0	是
page_no	Integer	QUERY	当前页数（从 1 开始计数）	是
page_size	Integer	QUERY	每页展示的条数	是

请求示例

GET /v1.0/devices/vdevo1623226445*****/door-lock/records?targetStandardDpCodes=unlock_password,unlock_card&startTime=0&endTime=0&pageNo=1&pageSize=10

返回参数

参数名	类型	说明
code	Integer	错误响应码，成功时为空（详情⻅见错误码）
success	Boolean	是否成功。（true：成功，false：失败）
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	返回结果

result

参数名	类型	说明
has_more	Integer	是否还有更多数据
total_pages	Integer	总页数
total	Integer	数据总条数
records	List	分页数据

records说明

参数名	类型	说明
record_id	String	记录 ID
media_info_list	List	多媒体信息，比如视频或者图片信息
union_unlock_info	List	组合解锁信息集合
unlock_name	String	解锁方式名称
gmt_create	Long	创建时间
dps	List	DP 信息
avatar	String	用户头像
member_bindable_flag	Integer	当前记录是否可以关联人。 1：可关联 0：不能关联（可能已经关联过了）
user_id	String	用户 ID
user_name	String	用户名
record_type	String	记录类型。 alarm：告警类型的记录 normal：普通开门记录

media_info_list说明

参数名	类型	说明
file_url	String	封面图全路径
file_key	String	文件密钥
media_url	String	视频全路径
media_key	String	视频密钥

union_unlock_info说明

参数名	类型	说明
user_name	String	用户名
opmode	String	解锁类型
unlock_name	String	解锁方式名称

dps说明

dps 是一个数组，其中每个数据是一个 JSON 数据。key 为 dpCode，value 为 dpCode 对应的值。

请求成功返回示例

{
  "result": {
    "has_more": false,
    "records": [
      {
        "avatar": "https://images.tuyacn.com/smart/user_avatar/ay1565317415087U6QVp/F062FD1C-CA44-440A-9AE5-E270BE4826DD.png?sign=q-sign-algorithm%3Dsha1%26q-ak%3DAKIDopcCYgw0qRoyV5qfKjvg2pPkqESnb5zI%26q-sign-time%3D1624606578%3B1624610178%26q-key-time%3D1624606578%3B1624610178%26q-header-list%3Dhost%26q-url-param-list%3D%26q-signature%3D467422052c41744943fa1c734ed9a44ad2ad7fe1",
        "dps": [
          {
            "unlock_password": "*"
          }
        ],
        "gmt_create": 1624604728299,
        "member_bindable_flag": 0,
        "record_id": "162460b8cfcbb6-d583-11eb-adea-0242878ef26647****",
        "record_type": "alarm",
        "unlock_name": "密码1",
        "user_id": "3066****",
        "user_name": "古树"
      }
    ],
    "total": 1,
    "total_pages": 1
  },
  "success": true,
  "t": 1624606578846
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error,please contact the admin"
}

将历史记录关联给某个用户

支持的门锁类型

Wi-Fi 门禁

接口地址

POST /v1.0/devices/{device_id}/door-lock/records/{record_id}/actions/allocate

请求参数

参数名	类型	参数类型	说明	是否必须
device_id	String	URI	设备 ID	是
record_id	String	URI	历史记录 ID	是
user_id	String	BODY	用户 ID	是

请求示例

POST /v1.0/devices/vdevo16232264458****/door-lock/records/162315AAXEQDzL*****CRCxYNIADC506****/actions/allocate

{
  "userId": 1980012
}

响应参数

参数	类型	说明
result	boolean	操作结果

响应成功示例

{
    "success": true,
    "t": 1571898808491,
    "result": true
}

相应失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error,please contact the admin"
}

清空临时密码

支持的门锁类型

酒店 Zigbee 门锁

接口地址

POST /v1.0/devices/{device_id}/door-lock/temp-passwords/rest-password

请求参数

参数名	类型	参数类型	说明	是否必传
device_id	String	URI	设备 ID	是

请求示例

POST /v1.0/devices/vdevo153459260090544/door-lock/temp-passwords/reset-password

返回参数

参数名	类型	说明
code	Integer	错误响应码，成功时为空（详情⻅见错误码）
success	Boolean	是否成功：（true：成功，false：失败）
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Boolean	是否成功

请求成功返回示例

{
    "success": true,
    "t": 1542626129429,
    "result": true
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error,please contact the admin"
}

获取门锁支持的远程开门方式

支持的门锁类型

Zigbee 门锁
蓝牙门锁

接口地址

GET /v1.0/devices/{device_id}/door-lock/remote-unlocks

请求参数

参数名	类型	参数类型	说明	必填
device_id	String	URI	设备 ID	是

请求示例

GET /v1.0/devices/vdevo153459260090544/door-lock/remote-unlocks

返回参数

参数名	类型	说明
code	Integer	错误响应码，成功时为空（详情⻅见错误码）
success	Boolean	是否成功：（true：成功，false：失败）
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	开门指令信息

result

参数名	类型	说明
remote_unlock_type	String	开门方式(remoteUnlockWithoutPwd: 免密开门, remoteUnlockWithPwd: 含密开门)
open	Boolean	功能是否开启

请求成功返回示例

{
    "result": {
        "remote_unlock_type": "remoteUnlockWithPwd",
        "open": true
    },
    "success": true,
    "t": 1592899848757
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error,please contact the admin"
}

设置门锁远程开门方式的开关

支持的门锁类型

Wi-Fi 门锁
Zigbee 门锁
蓝牙门锁

接口地址

POST /v1.0/devices/{device_id}/door-lock/remote-unlock/config

请求参数

参数名	类型	参数类型	说明	必填
device_id	String	URI	设备 ID	是
remote_unlock_type	String	BODY	开门方式(remoteUnlockWithoutPwd: 免密开门, remoteUnlockWithPwd: 含密开门)	是
open	Boolean	BODY	功能是否开启	是

请求示例

POST /v1.0/devices/vdevo153459260090544/door-lock/remote-unlock/config

{
    "remote_unlock_type": "remoteUnlockWithPwd",
    "open": true
}

返回参数

参数名	类型	说明
code	Integer	错误响应码，成功时为空（详情⻅见错误码）
success	Boolean	是否成功：（true：成功，false：失败）
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Boolean	是否成功

请求成功返回示例

{
    "result": true,
    "success": true,
    "t": 1592899848757
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error,please contact the admin"
}

门锁含密开门

支持的门锁类型

Zigbee 门锁

接口地址

POST /v1.0/devices/{device_id}/door-lock/open-door

请求参数

参数名	类型	参数类型	说明	必填
device_id	String	URI	设备 ID	是
password	String	Body	密码原文长度为 6，密码传输加密算法使用 AES，模式：ECB pkcs7padding，数据块 128为位，秘钥为通过接口获取的临时 ticket_key 使用开发者accessKey AES解密后的原始秘钥	是
password_type	String	BODY	密码加密类型：ticket	是
ticket_id	String	BODY	临时秘钥ID	是

请求示例

POST /v1.0/devices/6c362ac3c53fbd6f3ewqfa/door-lock/open-door

返回信息

参数名	类型	说明
code	Integer	响应码（详情见错误码章节）
success	Boolean	是否成功：（true：成功，false：失败）
msg	String	请求失败的信息，成功为空
result	Boolean	返回结果

返回示例

{
    "success": true,
    "t": 1542626129429,
    "result": true
}

设置高级密码

支持的门锁类型

酒店 Zigbee 门锁

接口地址

POST /v1.0/devices/{device_id}/door-lock/advanced-password

请求参数

参数名	类型	参数类型	说明	是否必传
device_id	String	URI	设备 ID	是
password	String	Body	密码原文长度为6，密码，传输使用加密算法使用AES，模式：ECB pkcs7padding 数据块128位，秘钥为通过接口获取的临时ticket_key使用开发者accessKey AES解密后的原始秘钥	是
password_type	String	BODY	密码加密类型：ticket	是
ticket_id	String	BODY	临时秘钥ID	是
advanced_type	String	BODY	高级密码类型：admin(管理员密码), emergency(应急密码)	是

请求示例

POST /v1.0/devices/vdevo153459260090544/door-lock/advanced-password

{
    "password_type":"ticket",
    "password":"7A8F9B6197xxxx7C1D66",
    "ticket_id":"fJeqZd45",
    "advanced_type":"emergency"
}

返回参数

参数名	类型	说明
code	Integer	错误响应码，成功时为空（详情⻅见错误码）
success	Boolean	是否成功：（true：成功，false：失败）
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Boolean	是否成功

请求成功返回示例

{
    "success": true,
    "t": 1542626129429,
    "result": true
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error,please contact the admin"
}

查询高级密码

支持的门锁类型

类型	支持
门锁类型	酒店Zigbee 门锁

接口地址

GET /v1.0/devices/{device_id}/door-lock/advanced-password

请求参数

参数名	类型	参数类型	说明	是否必传
device_id	String	URI	设备 ID	是
advanced_type	String	URL	高级密码类型：admin(管理员密码), emergency(应急密码)	是

请求示例

GET /v1.0/devices/vdevo153459260090544/door-lock/advanced-password?advanced_type=admin

返回参数

参数名	类型	说明
code	Integer	错误响应码，成功时为空（详情⻅见错误码）
success	Boolean	是否成功：（true：成功，false：失败）
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	高级密码状态

result

参数名	类型	说明
advanced_type	String	高级密码类型：admin(管理员密码), emergency(应急密码)
phase	Integer	密码配置状态：1(配置中), 2(配置成功), 3(配置失败)

请求成功返回示例

{
    "success": true,
    "t": 1542626129429,
    "result": {
        "advanced_type":"admin",
        "phase":2
    }
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error,please contact the admin"
}

查询当前设备已经观看视频次数

支持的门锁类型

Wi-Fi 门锁

接口地址

GET /v1.0/smart-lock/devices/{device_id}/media-view-times

请求参数

参数名	类型	参数类型	说明	是否必传
device_id	String	URI	设备 ID	是

请求示例

GET /v1.0/smart-lock/devices/vdevo124546565765/media-view-times

返回参数

参数名	类型	说明
code	Integer	错误响应码，成功时为空（详情⻅见错误码）
success	Boolean	是否成功：（true：成功，false：失败）
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Integer	次数

请求成功返回示例

{
  "result": 1,
  "success": true,
  "t": 1634712882506
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error,please contact the admin"
}

当前设备已经观看视频次数+1

支持的门锁类型

Wi-Fi 门锁

接口地址

POST /v1.0/smart-lock/devices/{device_id}/media-view-times

请求参数

参数名	类型	参数类型	说明	是否必传
device_id	String	URI	设备 ID	是

请求示例

POST /v1.0/smart-lock/devices/vdevo124546565765/media-view-times

返回参数

参数名	类型	说明
code	Integer	错误响应码，成功时为空（详情⻅见错误码）
success	Boolean	是否成功：（true：成功，false：失败）
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Integer	次数

请求成功返回示例

{
  "result": 2,
  "success": true,
  "t": 1634713143910
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error,please contact the admin"
}

远程开门带抓拍图片

远程开门带抓拍图片流程：
远程开门带抓拍图片-实时场景
- 用户触发拍照锁开门操作，门锁抓拍图片并上报云服务
- 云服务存储影像数据，并推送相对存储位置信息到用户端
- 用户端调用云服务，获得影像存储全路径
- 用户端获得加密影像数据并解密
- 用户根据得到影像信息，判断是开门\撤销，并调用相应接口
- 云服务下发到拍照锁，执行开门\撤销操作
远程开门带抓拍图片-非实时场景
- 用户端调用云服务查询最近一次90s内的开门\预警影像信息
- 用户端获得加密影像数据并解密
- 用户根据得到影像信息，判断是开门\撤销，并调用相应接口
- 云服务下发到拍照锁，执行开门\撤销操作

影像信息通过AES/CBC/PKCS5Padding加密，规则如下所示：

4	16	44	视频内容
占位	iv	占位	视频内容

解密demo如下所示：

package xxxxxxx;
 
import java.io.File;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.security.InvalidAlgorithmParameterException;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.security.SecureRandom;
import java.util.Random;
 
import javax.crypto.Cipher;
import javax.crypto.CipherInputStream;
import javax.crypto.CipherOutputStream;
import javax.crypto.NoSuchPaddingException;
import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;
 
public class EncryptUtils {
 
    private static final String DEFAULT_ALGORITHM = "AES";
    private static final String DEFAULT_FULL_ALGORITHM = "AES/CBC/PKCS5Padding";
 
    //加密
    public static File encryptFile(String key, File originFile, String destPath) {
        FileInputStream in = null;
        FileOutputStream out = null;
        File destFile = null;
        try {
            destFile = new File(destPath);
            if (originFile.exists() && originFile.isFile()) {
                if (!destFile.getParentFile().exists()) {
                    destFile.getParentFile().mkdirs();
                }
                destFile.createNewFile();
                in = new FileInputStream(originFile);
                out = new FileOutputStream(destFile, true);
                byte[] iv = getIv();
                Cipher cipher = initAESCipher(iv, key, Cipher.ENCRYPT_MODE);
                CipherInputStream cipherInputStream = new CipherInputStream(in, cipher);
                byte[] cache = new byte[1024];
                int nRead;
                out.write(new byte[4]);
                out.write(iv);
                out.write(new byte[4]);
                out.write(new byte[40]);
                out.flush();
                while ((nRead = cipherInputStream.read(cache)) != -1) {
                    out.write(cache, 0, nRead);
                    out.flush();
                }
                cipherInputStream.close();
            }
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            try {
                if (out != null) {
                    out.close();
                }
                if (in != null) {
                    in.close();
                }
            } catch (IOException e) {
                e.printStackTrace();
            }
        }
        return destFile;
    }
 
    //解密
    public static File decryptFile(String key, InputStream in, File destFile) {
        FileOutputStream out = null;
        try {
            if (!destFile.getParentFile().exists()) {
                destFile.getParentFile().mkdirs();
            }
            destFile.createNewFile();
            out = new FileOutputStream(destFile);
 
            byte[] iv = new byte[16];
            in.skip(4);
            int read = in.read(iv);
            if (read != 16) {
                throw new IOException("iv length error");
            }
            in.skip(44);
            Cipher cipher = initAESCipher(iv, key, Cipher.DECRYPT_MODE);
            CipherOutputStream cipherOutputStream = new CipherOutputStream(out, cipher);
            byte[] buffer = new byte[1024];
            int r;
            while ((r = in.read(buffer)) >= 0) {
                cipherOutputStream.write(buffer, 0, r);
            }
            cipherOutputStream.close();
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            try {
                if (in != null) {
                    in.close();
                }
            } catch (IOException e) {
                e.printStackTrace();
            }
            try {
                if (out != null) {
                    out.close();
                }
            } catch (IOException e) {
                e.printStackTrace();
            }
        }
        return destFile;
    }
 
    private static Cipher initAESCipher(byte[] iv, String sKey, int cipherMode) {
        try {
            IvParameterSpec zeroIv = new IvParameterSpec(iv);
            SecretKeySpec key = new SecretKeySpec(sKey.getBytes(), DEFAULT_ALGORITHM);
            Cipher cipher = Cipher.getInstance(DEFAULT_FULL_ALGORITHM);
            cipher.init(cipherMode, key, zeroIv);
            return cipher;
        } catch (NoSuchAlgorithmException e) {
            e.printStackTrace();
        } catch (NoSuchPaddingException e) {
            e.printStackTrace();
        } catch (InvalidKeyException e) {
            e.printStackTrace();
        } catch (InvalidAlgorithmParameterException e) {
            e.printStackTrace();
        }
        return null;
    }
 
    public static byte[] getIv() {
        StringBuilder uid = new StringBuilder();
        //产生16位的强随机数
        Random rd = new SecureRandom();
        for (int i = 0; i < 16; i++) {
            //产生0-2的3位随机数
            int type = rd.nextInt(3);
            switch (type) {
                case 0:
                    //0-9的随机数
                    uid.append(rd.nextInt(10));
                    break;
                case 1:
                    //ASCII在65-90之间为大写,获取大写随机
                    uid.append((char) (rd.nextInt(25) + 65));
                    break;
                case 2:
                    //ASCII在97-122之间为小写，获取小写随机
                    uid.append((char) (rd.nextInt(25) + 97));
                    break;
                default:
                    break;
            }
        }
        return uid.toString().getBytes();
    }
 
}

门锁免密开门

支持的门锁类型

公版 Wi-Fi 门锁
公版 Zigbee 门锁
酒店 Zigbee 门锁
蓝牙门锁
常保活 Wi-Fi 门锁
可视对讲 Wi-Fi

接口地址

POST /v1.0/devices/{device_id}/door-lock/password-free/open-door

请求参数

参数名	类型	参数类型	说明	必填
device_id	String	URI	设备 ID	是
ticket_id	String	Body	临时秘钥ID	是

请求示例

POST /v1.0/devices/vdevo153459260090544/door-lock/password-free/open-door

{
    "ticket_id":"xxxxx"
}

返回参数

参数名	类型	说明
code	Integer	错误响应码，成功时为空（详情⻅见错误码）
success	Boolean	是否成功：（true：成功，false：失败）
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Boolean	请求结果

请求成功返回示例

{
    "result": true,
    "success": true,
    "t": 1592899848757
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error,please contact the admin"
}

门锁免密开门（v1.1）

该接口支持对特定通道执行开门动作。

支持的门锁类型

Wi-Fi 门禁

接口地址

POST /v1.1/devices/{device_id}/door-lock/password-free/open-door

请求参数

参数名	类型	参数类型	说明	必填
device_id	String	URI	设备 ID	是
ticket_id	String	Body	临时秘钥 ID。该值通过接口 `POST:/v1.0/devices/{device_id}/door-lock/password-ticket` 获取	是
channel_id	Integer	Body	通道 ID	是

请求示例

POST /v1.1/devices/vdevo15345926009****/door-lock/password-free/open-door

{
    "ticket_id":"WHmutLIq",
    "channel_id":1
}

返回参数

参数名	类型	说明
code	Integer	错误响应码，成功时为空（详情⻅见错误码）
success	Boolean	是否成功（true：成功，false：失败）
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Boolean	请求结果

请求成功返回示例

{
    "result": true,
    "success": true,
    "t": 1592899848757
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error,please contact the admin"
}

门锁免密开门撤销

支持的门锁类型

类型	支持
门锁类型	Wi-Fi 门锁

接口地址

PUT /v1.0/devices/{device_id}/door-lock/password-free/open-door/cancel

请求参数

参数名	类型	参数类型	说明	必填
device_id	String	URI	设备 ID	是
type	Integer	BODY	撤销远程开门的原因 1. 拒绝 2.取消	是

请求示例

PUT /v1.0/devices/vdevo153459260090544/door-lock/password-free/open-door/cancel

{
    "type":1
}

返回参数

参数名	类型	说明
code	Integer	错误响应码，成功时为空（详情⻅见错误码）
success	Boolean	是否成功：（true：成功，false：失败）
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Boolean	是否成功

请求成功返回示例

{
    "result": true,
    "success": true,
    "t": 1592899848757
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error,please contact the admin"
}

门锁免密开关门

支持的门锁类型

公版 Wi-Fi 门锁
公版 Zigbee 门锁
酒店 Zigbee 门锁
蓝牙门锁
常保活 Wi-Fi 门锁
可视对讲 Wi-Fi

注意：远程开门必须有remote_no_dp_key 或者 remote_no_dp_setkey 这两个DP，且只有公版wifi门锁支持远程关门。

接口地址

POST /v1.0/smart-lock/devices/{device_id}/password-free/door-operate

请求参数

参数名	类型	参数类型	说明	必填
device_id	String	URI	设备 ID	是
ticket_id	String	Body	临时秘钥ID	是
open	Boolean	Body	操作(默认开门) true：开门 false：关门	否

请求示例

POST /v1.0/smart-lock/devices/vdevo153459260090544/password-free/door-operate

{
    "ticket_id":"xxxxx",
    "open":false
}

返回参数

参数名	类型	说明
code	Integer	错误响应码，成功时为空（详情⻅见错误码）
success	Boolean	是否成功：（true：成功，false：失败）
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Boolean	请求结果

请求成功返回示例

{
    "result": true,
    "success": true,
    "t": 1592899848757
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error,please contact the admin"
}

获取密码加密的临时秘钥（门锁免密开关门接口调用）

支持的门锁类型

Wi-Fi 门锁
Zigbee 门锁
蓝牙门锁
酒店 Zigbee 门锁
可视对讲 Wi-Fi

接口地址

POST /v1.0/smart-lock/devices/{device_id}/password-ticket

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是

请求示例

POST /v1.0/smart-lock/devices/vdevo15345926009****/password-ticket

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	临时密码信息

result

参数名	类型	说明
ticket_id	String	临时秘钥 ID
ticket_key	String	临时秘钥 Key，需要根据云开发者 accessKey 通过 AES 解密后方可使用
expire_time	Long	剩余有效时间

请求成功返回示例

{
    "result": {
        "expire_time": 360,
        "ticket_id": "9wxxoLM",
        "ticket_key": "901CC35A67DA3429C38E9622xxxxx3EAE1CE333462356D257FD1D3E5C"
    },
    "success": true,
    "t": 1592899848757
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error,please contact the admin"
}

获取最近一次的远程开门或告警封面图

支持的门锁类型

Wi-Fi 门锁
酒店 Zigbee 门锁
蓝牙门锁

接口地址

GET /v1.0/devices/{device_id}/door-lock/latest/media/url

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是
file_type	Integer	URL	文件类型 1. 远程开门， 2. 告警	是

请求示例

GET /v1.0/devices/6cdb36b2e489885fa57lzm/door-lock/latest/media/url?file_type=1

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	返回结果

result

参数名	类型	说明
file_url	String	封面图完整路径
file_key	String	文件解密密钥
bucket	String	封面图完整路径
file_path	String	文件的相对路径

请求成功返回示例

{
    "result": {
        "bucket": "ty-cn-storage60-1254153901",
        "file_key": "u8kstrtjm7qun83q",
        "file_path": "/3039e1-30532026.jpg",
        "file_url": "https://ty-cn-storage60-1254153901.cos.tuyacn.com6"
    },
    "success": true,
    "t": 1614147303662
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error, please contact the admin"
}

获取相册列表

支持的门锁类型

可视对讲 Wi-Fi

接口地址

GET /v1.0/smart-lock/devices/{device_id}/albums-media

请求参数

参数名	类型	参数类型	说明	是否必传
device_id	String	URI	设备 ID	是

请求示例

GET /v1.0/smart-lock/devices/vdevo153459260090544/albums-media

返回参数

参数名	类型	说明
code	Integer	错误响应码，成功时为空（详情⻅见错误码）
success	Boolean	是否成功：（true：成功，false：失败）
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	返回结果

result

参数名	类型	说明
eventTypes	array[int]	相册里封面图和视频的类型
albumList	List	相册数据列表
orderCode	Integer	当前相册查询所使用的套餐 doorlock_cloud_storage_7day 七天不限次数云存储 doorlock_cloud_storage_30day 30天不限次数云存储 cloud_free_storage_3day 3天免费云存储

albumList

参数名	类型	说明
eventType	int	文件类型
fileUrl	String	封面图地址
fileKey	String	封面图密钥
mediaPath	String	视频地址
mediaKey	String	视频密钥
mediaBucket	String	视频所在的仓库
uploadTime	long	上报时间(秒)

eventType文件类型说明

类型值	类型	说明
0	int	防撬告警
1	int	远程开门请求
2	int	指纹开门试错
3	int	密码开门试错
4	int	卡片开门试错
5	int	人脸开门试错
6	int	掌纹开门试错
7	int	指静脉开门试错
8	int	指纹开门
9	int	密码开门
10	int	卡片开门
11	int	人脸开门
12	int	掌纹开门
13	int	指静脉开门
14	int	临时密码解锁
15	int	动态密码解锁
16	int	远程解锁
17	int	临时密码解锁上报
18	int	门铃解锁上报
19	int	劫持告警
20	int	低电报警
21	int	钥匙插入报警
22	int	高温报警
23	int	门铃+远程开门
24	int	有人停留(逗留)
25	int	门锁被破坏
26	int	特殊指纹开锁
27	int	布防模式下开锁
28	int	遥控开门

请求成功返回示例

{
    "success": true,
    "t": 1542626129429,
    "result": {
        "album_list": [
      {
        "event_type": 0,
        "file_id": 109167468,
        "file_key": "76679d2579c74eb7",
        "file_url": "https://ty-cn-storage30-1254153901.cos.tuyacn.com/d76182-35779292-dc706aecd4469145/unify/1630051338.jpeg?sign=q-sign-algorithm%3Dsha1%26q-ak%3DAKIDopcCYgw0qRoyV5qfKjvg2pPkqESnb5zI%26q-sign-time%3D1630137629%3B1630141229%26q-key-time%3D1630137629%3B1630141229%26q-header-list%3Dhost%26q-url-param-list%3D%26q-signature%3D29b40dd6ed4281b78321ec978ce1e56361fd7b57",
        "upload_time": 1630051337
      }
    ],
    "event_types": [
      0
    ],
    "order_code": "cloud_free_storage_3day"
    }
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error,please contact the admin"
}

设备成员管理

获取家庭用户和解锁方式的信息列表

支持的门锁类型

常保活 Wi-Fi
可视对讲 Wi-Fi

接口地址

GET /v1.0/smart-lock/devices/{device_id}/users

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是
codes	String	URL	解锁方式, 多个的话以逗号分隔 unlock_fingerprint：指纹 unlock_card：门卡 unlock_password：密码 unlock_face：人脸 unlock_hand：掌纹 unlock_finger_vein：指静脉	是
page_no	int	URI	当前页数(从1开始计数)	是
page_size	int	URI	每页数据量	是

请求示例

GET /v1.0/smart-lock/devices/vdevo12454656****/users

{
    "codes":"unlock_fingerprint,unlock_password",
    "page_no":1,
    "page_size":100
}

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	用户数据列表

result

参数名	类型	说明
user_id	Long	用户在家庭里的编号
avatar_url	String	家庭用户头像地址
user_contact	String	联系方式
unlock_detail	json array	解锁方式详情
user_type	int	用户类型 10：管理员 20：普通成员 50：家庭主人
nick_name	String	用户昵称
lock_user_id	int	用户在锁上的编号
back_home_notify_attr	int	家人到家提醒开关是否打开 1：是 0：否
effective_flag	int	当前用户是否在有效期内 1：是 0：否
time_schedule_info	json array	用户时效信息
uid	String	用户uid

unlock_detail

参数名	类型	说明
dp_code	String	解锁方式 unlock_fingerprint：指纹 unlock_card：门卡 unlock_password：密码 unlock_face：人脸 unlock_hand：掌纹 unlock_finger_vein：指静脉
count	int	当前解锁方式的数量
unlock_list	json array	解锁方式信息列表

unlock_list

参数名	类型	说明
unlock_id	String	解锁方式云端编号
unlock_sn	int	解锁方式在门锁上的编号
unlock_name	String	解锁方式名称
unlock_attr	int	解锁方式属性， 1：带劫持
op_mode_id	int	解锁方式云端序号
photo_unlock	bool	是否带开门抓拍功能(仅带抓拍功能的 Wi-Fi 门锁支持)
admin	bool	是否是门锁上的管理员解锁方式（通过解锁方式同步或者管理员解锁方式上报功能通知云端）

time_schedule_info

参数名	类型	说明
permanent	bool	是否永久，true 为永久
effective_time	String	生效时间. 单位是秒
expired_time	String	失效时间. 单位是秒
operate	String	最近的操作 ADD：新增 MODIFY：修改 DELETE：删除
schedule_details	json array	时效周期性信息

schedule_details

参数名	类型	说明
start_minute	int	当天开始时间，单位分钟，最大值 1440
end_minute	int	当天过期时间，单位分钟, 最大值 1440
working_day	Int	星期, 每个值累加： 1：星期天 2：星期一 4：星期二 8：星期三 16：星期四 32：星期五 64：星期六
time_zone_id	String	时区

请求成功返回示例

{
  "result": {
    "has_more": false,
    "records": [
      {
        "avatar_url": "https://****",
        "back_home_notify_attr": 0,
        "effective_flag": 1,
        "lock_user_id": 5,
        "nick_name": "测试1",
        "time_schedule_info": {
          "delivery_status": "SUCCESS",
          "effective_time": 1628179200,
          "expired_time": 1638806399,
          "operate": "MODIFY",
          "permanent": false,
          "schedule_details": [
            {
              "all_day": false,
              "start_minute": 60,
              "end_minute": 480,
              "working_day": 97
            }
          ]
        },
        "uid": "ay1541490670142A1Dti",
        "unlock_detail": [],
        "user_contact": "86-13757150532",
        "user_id": "38823920",
        "user_type": 10
      }
    ],
    "total": 18,
    "total_pages": 1
  },
  "success": true,
  "t": 1628241725953
}

请求失败返回示例

{
    "success":false,
    "code":500, // 错误码，详细请见错误码文档
    "msg":"system error,please contact the admin"
}

更新用户时效

支持的门锁类型

常保活 Wi-Fi
Wi-Fi 门禁

接口地址

PUT /v1.0/smart-lock/devices/{device_id}/users/{user_id}/schedule

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是
user_id	String	URI	用户 ID	是
schedule	json	BODY	用户时效信息	是

schedule

参数名	类型	说明
permanent	bool	是否永久，true 为永久
effective_time	String	生效时间. 单位是秒
expired_time	String	失效时间. 单位是秒
schedule_details	json array	时效周期性信息

schedule_details

参数名	类型	说明
start_minute	int	当天开始时间，单位分钟，最大值 1440
end_minute	int	当天过期时间，单位分钟, 最大值 1440
working_day	Int	星期, 每个值累加： 1：星期天 2：星期一 4：星期二 8：星期三 16：星期四 32：星期五 64：星期六
time_zone_id	String	时区

请求示例

PUT /v1.0/smart-lock/devices/vdevo12454656****/users/130**/schedule

{
  "scheduleDetails": [
    {
      "allDay": false,
      "start_minute": "420",
      "end_minute": "1438",
      "workingDay": 99
    }
  ],
  "effectiveTime": 1628179200,
  "expiredTime": 1640015999,
  "permanent": false
}

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Boolean	返回结果

请求成功返回示例

{
  "result": true,
  "success": true,
  "t": 1628241725953
}

请求失败返回示例

{
    "success":false,
    "code":500, // 错误码，详细请见错误码文档
    "msg":"system error,please contact the admin"
}

获取用户的解锁方式列表

支持的门锁类型

可视对讲 Wi-Fi
Wi-Fi 门禁

接口地址

GET /v1.0/smart-lock/devices/{device_id}/opmodes/{user_id}

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是
user_id	String	URI	用户 ID	是
codes	String	URL	目标的解锁方式的 Code, 多个以逗号隔开(可为空) unlock_fingerprint：指纹 unlock_password：密码 unlock_card：门卡 unlock_face：人脸 unlock_hand：掌纹 unlock_finger_vein：指静脉 unlock_telecontrol_kit：遥控器	是
unlock_name	String	URL	目标解锁方式名称(可为空)	是
page_no	Integer	URL	当前页数(从1开始计数)	是
page_size	Integer	URL	每页数据量	是

请求示例

GET /v1.0/smart-lock/devices/6c982a30639b8f6338d3ox/opmodes/33970143?page_size=20&page_no=1&codes=unlock_fingerprint,unlock_password,unlock_card&unlock_name=

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Boolean	返回结果

result

参数名	类型	说明
user_name	String	用户名称
user_id	String	用户ID
user_type	Integer	用户类型 0-未知人员类型 10-管理员 20-普通家人 40-分享用户 50-超级管理员
lock_user_id	Integer	用户在锁上的ID
unlock_name	String	解锁方式名称
opmode_id	String	当前解锁方式的主键ID
dp_code	String	解锁方式的dpCode
unlock_sn	String	解锁方式编号
phase	Integer	状态 1-已确认 2- 待确认 3-已冻结 4- 待冻结 5-待解冻 6-待重置 7-创建失败 8-已删除 9-待删除 10-待创建
unlock_attr	Integer	解锁方式属性 (1代表劫持属性)
notify_info	String	通知方式，一个JSON格式字符串
allocate_flag	Boolean	是否是从未分配的解锁方式分配给用户的(如果是的话是可以解绑的). 1-是, 0-否

notify_info

参数名	类型	说明
app_send	Integer	是否app 通知. 0: 否；1:是 (微信公众号的话, 这里也是1)
msg_phone	String	接受短信的手机号码
voice_phone	String	接受语音电话的手机号码

请求成功返回示例

{
  "result":[
    {
        "phase":3,
        "dp_code":"unlock_password",
        "unlock_attr":0,
        "unlock_name":"lin",
        "user_name":"小苗",
        "user_id":"28873683",
        "unlock_sn":3,
        "uid":"ay1562298621752U9R5d",
        "unlock_id":"12-3",
        "operate":"CREATE",
        "lock_user_id":2,
        "opmode_id":"729548",
        "voice_attr":0,
        "user_time_set":"386cd30072bc9b7f000000000000000000",
        "user_type":20,
        "delivery_status":"SUCCESS",
      	"allocate_flag":0,
      	"notify_info":{
            "app_send":1
        }
    },
    {
        "phase":3,
        "dp_code":"unlock_password",
        "unlock_attr":0,
        "unlock_name":"lin-1",
        "user_name":"小苗",
        "user_id":"28873683",
        "unlock_sn":4,
        "uid":"ay1562298621752U9R5d",
        "unlock_id":"12-4",
        "operate":"CREATE",
        "lock_user_id":2,
        "opmode_id":"729549",
        "voice_attr":0,
        "user_time_set":"386cd30072bc9b7f000000000000000000",
        "user_type":20,
        "delivery_status":"SUCCESS",
        "allocate_flag":1,
      	"notify_info":{
            "app_send":0,
            "msg_phone":"86-15156789943"
        }
    }
]
  "sucess":ture,
  "t":1542626129429
}

请求失败返回示例

{
    "success":false,
    "code":500, // 错误码，详细请见错误码文档
    "msg":"system error,please contact the admin"
}

获取被移除的用户列表

支持的门锁类型

可视对讲 WIFI

接口地址

GET /v1.0/devices/{device_id}/door-lock/absent-users

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是

请求示例

GET /v1.0/devices/6c982a30639b8f6338d3ox/door-lock/absent-users

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Boolean	返回结果

result

参数名	类型	说明
user_id	String	用户id
user_type	Integer	用户类型 50：超级管理员 10：管理员 20：普通成员 40：分享成员 0：未知用户
lock_user_id	Integer	用户在锁上的编号

请求成功返回示例

{
  "result": [
{
      "user_id": "390981",
      "user_type": 10,
      "lock_user_id": 2
    }
],
  "success": true,
  "t": 1628241725953
}

请求失败返回示例

{
    "success":false,
    "code":500, // 错误码，详细请见错误码文档
    "msg":"system error,please contact the admin"
}

控制门锁设备删除用户

支持的门锁类型

可视对讲 WIFI

接口地址

POST /v1.0/smart-lock/devices/{device_id}/users/{user_ids}/actions/delete-users-issue

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是
user_ids	String	URI	用户 ID(多个用逗号分隔)	是

请求示例

POST /v1.0/smart-lock/devices/6c982a30639b8f6338****/users/xxx/actions/delete-users-issue

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Boolean	返回结果

请求成功返回示例

{
  "result": true,
  "success": true,
  "t": 1628241725953
}

请求失败返回示例

{
    "success":false,
    "code":500, // 错误码，详细请见错误码文档
    "msg":"system error,please contact the admin"
}

新增设备成员

支持的门锁类型

Wi-Fi 门锁
Zigbee 门锁
蓝牙门锁

接口地址

POST /v1.0/devices/{device_id}/user

请求参数

参数名	参数类型	说明	是否必填
device_id	String	设备 ID	是
nick_name	String	用户名称	是
sex	Integer	性别 1：男 2：女	是
birthday	Long	出生年月日	否
height	Integer	身高（cm）	否
weight	Integer	体重（g）	否
contact	String	联系方式	否

响应参数

名称	类型	说明
t	Long	返回时间
success	Boolean	是否成功
result	Object	结果

result参数说明

名称	类型	说明
user_id	String	添加的用户ID

修改设备成员

支持的门锁类型

Wi-Fi 门锁
Zigbee 门锁
蓝牙门锁

接口地址

PUT /v1.0/devices/{device_id}/users/{user_id}

请求参数

参数名	参数类型	说明	是否必填
device_id	String	设备 ID	是
user_id	String	添加的用户ID	是
nick_name	String	用户名称	是
sex	Integer	性别 1：男 2：女	是
birthday	Long	出生年月日	否
height	Integer	身高（cm）	否
weight	Integer	体重（g）	否

响应参数

名称	类型	说明
t	Long	时间戳
success	Boolean	是否成功
result	Object	结果

更新设备用户的角色

支持的门锁类型

Wi-Fi 门禁

接口地址

PUT /v1.0/smart-lock/devices/{device_id}/users/{user_id}/actions/role

请求参数

参数名	类型	参数类型	说明	是否必须
device_id	String	URI	设备 ID	是
user_id	String	URI	用户 ID	是
role	String	BODY	新角色 admin：管理员 normal：普通成员	是

请求示例

PUT /v1.0/smart-lock/devices/6c5fa86feedc16f77d****/users/8923iu****/actions/role

{
    "role":"admin"
}

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功。 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空

响应成功示例

{
  "success": true,
  "t": 1614147303662
}

响应失败返回示例**

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error,please contact the admin"
}

删除设备成员

支持的门锁类型

Wi-Fi 门锁
Zigbee 门锁
蓝牙门锁

接口地址

DELETE /v1.0/devices/{device_id}/users/{user_id}

请求参数

参数名	参数类型	说明	是否必填
device_id	String	设备 ID	是
user_id	String	用户ID	是

响应参数

名称	类型	说明
t	Long	时间戳
success	Boolean	是否成功
result	Object	结果

查询设备成员信息

支持的门锁类型

Wi-Fi 门锁
Zigbee 门锁
蓝牙门锁

不支持查询管理员

接口地址

GET /v1.0/devices/{device_id}/users/{user_id}

请求参数

参数名	参数类型	说明	是否必填
device_id	String	设备 ID	是
user_id	String	用户ID	是

响应参数

参数名	参数类型	说明
device_id	String	设备 ID
nick_name	String	用户名称
sex	Integer	性别 1：男 2：女
birthday	Long	出生年月日
height	Integer	身高（cm）
weight	Integer	体重（g）
contact	String	联系方式

查询设备成员信息（v1.1）

该接口支持获取当前用户的信息，不支持查询管理员。

支持的门锁类型

Wi-Fi 门禁

接口地址

GET /v1.1/devices/{device_id}/users/{user_id}

请求参数

参数名	类型	参数类型	说明	是否必须
device_id	String	URI	设备 ID	是
user_id	String	URI	用户 ID （如果查询当前用户，则需要传递 0 ）	是

请求示例

GET /v1.1/devices/vdevo16232264458****/users/0

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功。 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	返回结果

result说明

参数名	类型	说明
user_id	String	用户 ID
avatar_url	String	头像地址
user_contact	String	联系方式
user_type	Integer	用户类型管理员：10 普通成员：20 家庭主人：50
nick_name	String	用户昵称
lock_user_id	Integer	用户在锁上的编号
back_home_notify_attr	Integer	是否打开家人到家提醒开关 1：是 0：否
effective_flag	Integer	是否有效的标签（所谓有效是指当前用户的时效是否未过期） 1：是 0：否
time_schedule_info	Object	用户时效信息
uid	String	用户 UID

time_schedule_info说明

参数名	类型	说明
permanent	Boolean	是否永久
effective_time	Long	生效时间，精确到秒
expired_time	Long	失效时间，精确到秒
operate	String	操作 ADD：新增 MODIFY：修改 DELETE：删除
delivery_status	String	设备对操作的反馈 ONGOING：下发中 SUCCESS：下发成功 FAILED：下发失败
schedule_details	List	时效周期性信息

schedule_details说明

参数名	类型	说明
start_minute	Long	生效时间，是个分钟数，比如 “07:30”，那么该值=7x60+30=450
end_minute	Long	失效时间，是个分钟数，比如 “17:30”，那么该值=17x60+30=1050
working_day	Integer	星期，每个值累加： 1：星期天 2：星期一 4：星期二 8：星期三 16：星期四 32：星期五 64：星期六
all_day	Boolean	是否全天
time_zone_id	String	时区 ID，比如 Asia/Shanghai

响应成功示例

{
  "result": {
    "avatar_url": "https://thirdwx.qlogo.cn/mmopen/vi_32/y6E5GpvgQicwyxjCkJfpNcBo5Sd6wtmYbjHY6kzyibEn9yNicmGDZWrc0BxaaC2xFPibh5k9niaRMjGTEuNFZPFsP3g/132",
    "lock_user_id": 1,
    "nick_name": "长空",
    "user_contact": "",
    "user_id": "38028607",
    "user_type": 50
  },
  "success": true,
  "t": 1632448688665
}

响应失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error,please contact the admin"
}

根据设备 ID 查询成员信息列表

支持的门锁类型

Wi-Fi 门锁
Zigbee 门锁
蓝牙门锁

接口地址

GET /v1.0/devices/{device_id}/users

请求参数

参数名	参数类型	说明	是否必填
device_id	String	设备 ID	是

响应参数

参数名	参数类型	说明
device_id	String	设备 ID
nick_name	String	用户名称
sex	Integer	性别 1：男 2：女
birthday	Long	出生年月日
height	Integer	身高（cm）
weight	Integer	体重（g）
contact	String	联系方式

根据设备 ID查询成员信息列表-v1.1

说明：相比 v1.0 版本, 该接口支持根据关键字及角色信息进行数据过滤。

支持的门锁类型

Wi-Fi 门禁

接口地址

GET /v1.1/devices/{device_id}/users

请求参数

参数名	类型	参数类型	说明	是否必须
device_id	String	URI	设备 ID	是
keyword	String	QUERY	查询的关键字（目前只查询用户名称/账号，模糊匹配），当该值为空字符串则认为不参与过滤	是
role	String	QUERY	角色（如果为空字符串则认为不参与过滤） admin：管理员 normal：普通成员	是
page_no	Integer	QUERY	当前页数（从 1 开始计数）	是
page_size	Integer	QUERY	每页数据量	是

请求示例

GET /v1.1/devices/vdevo16232264458****/users?keyword=test&role=admin&page_no=1&page_size=10

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	返回结果

result说明

参数名	类型	说明
has_more	Boolean	是否还有更多数据
total_pages	Integer	总页数
total	Integer	数据总条数
records	List	分页数据

records说明

参数名	类型	说明
user_id	String	用户 ID
avatar_url	String	头像地址
user_contact	String	联系方式
user_type	Integer	用户类型 10：管理员 20：普通成 50：家庭主人
nick_name	String	用户昵称
lock_user_id	Integer	用户在锁上的编号
back_home_notify_attr	Integer	是否打开家人到家提醒开关 1：是 0：否
effective_flag	Integer	是否有效的标签（所谓有效是指当前用户的时效是否未过期） 1：是 0：否
time_schedule_info	Object	用户时效信息
uid	String	用户 UID

time_schedule_info说明

参数名	类型	说明
permanent	Boolean	是否永久
effective_time	Long	生效时间，精确到秒
expired_time	Long	失效时间，精确到秒
operate	String	操作 ADD：新增 MODIFY：修改 DELETE：删除
delivery_status	String	设备对操作的反馈 ONGOING：下发中 SUCCESS：下发成功 FAILED：下发失败
schedule_details	List	时效周期性信息

schedule_details说明

参数名	类型	说明
start_minute	Long	生效时间，是个分钟数，比如 “07:30”，那么该值=7x60+30=450
end_minute	Long	失效时间，是个分钟数，比如 “17:30”，那么该值=17x60+30=1050
working_day	Integer	星期，每个值累加： 1：星期天 2：星期一 4：星期二 8：星期三 16：星期四 32：星期五 64：星期六
all_day	Boolean	是否全天
time_zone_id	String	时区 ID，比如 Asia/Shanghai

响应成功示例

{
  "result": {
    "has_more": true,
    "records": [
      {
        "avatar_url": "",
        "back_home_notify_attr": 0,
        "effective_flag": 1,
        "lock_user_id": 1,
        "nick_name": "Nicole",
        "time_schedule_info": {
          "permanent": true
        },
        "user_contact": "test@163.com",
        "user_id": "30665363",
        "user_type": 50,
        "uid": "ay1***6168*****VdmWA"
      }
    ],
    "total": 14,
    "total_pages": 14
  },
  "success": true,
  "t": 1624613523063
}

响应失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error,please contact the admin"
}

分配门锁密码给设备成员

支持的门锁类型

Wi-Fi 门锁
Zigbee 门锁
蓝牙门锁

请求地址

POST /v1.0/devices/{device_id}/device-lock/users/{user_id}/allocate

请求参数

参数	类型	说明	是否必填
device_id	String	设备 ID	是
user_id	String	设备成员 ID	是
no	String	门锁编号	是
type	String	密码类型（fingerprint/password/card）	是

响应参数

参数	类型	说明
result	boolean	操作结果

响应成功示例

{
    "success": true,
    "t": 1571898808491,
    "result": true
}

将未分配的解锁方式分配给用户（支持同时分配多个）

支持的门锁类型

Wi-Fi 门禁
蓝牙门锁

请求地址

POST /v1.0/devices/{device_id}/door-lock/opmodes/actions/allocate

请求参数

参数	类型	参数类型	说明	是否必填
device_id	URI	String	设备 ID	是
user_id	BODY	String	用户 ID	是
unlock_list	BODY	List	解锁方式列表	是

unlock_list说明

参数名	类型	说明	是否必填
dp_code	String	解锁方式的 dpCode	是
unlock_sn	Integer	解锁方式编号	是

请求示例


POST /v1.0/devices/vdevo16232264458****/door-lock/opmodes/actions/allocate

{
  "user_id": "30665363",
  "unlock_list": [
    {
      "dp_code": "unlock_password",
      "unlock_sn": 2
    }
  ]
}

响应参数

参数	类型	说明
result	boolean	操作结果

响应成功示例

{
    "success": true,
    "t": 1571898808491,
    "result": true
}

获取用户帐号所关联的设备

支持的门锁类型

Wi-Fi 门禁

接口地址

GET /v1.0/smart-lock/users/{uid}/devices

请求参数

参数名	类型	参数类型	说明	必填
uid	String	URI	设备 ID	是
page_no	Integer	QUERY	当前页数（从 1 开始计数）	是
page_size	Integer	QUERY	通道 ID	每页数据量

请求示例

GET /v1.0/smart-lock/users/bay1629701943556****/devices?page_no=1&page_size=10

返回参数

参数名	类型	说明
code	Integer	错误响应码，成功时为空（详情⻅见错误码）
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	请求结果

result说明

参数名	类型	说明
total	Integer	数据总数
total_pages	Integer	总页数
has_more	Boolean	是否还有更多数据
records	List	分页数据

records说明

参数名	类型	说明
id	String	设备 ID
uuid	String	设备唯一标识
uid	String	用户 UID
name	String	设备名称
time_zone	String	时区
ip	String	设备 IP
local_key	String	密钥
sub	Boolean	是否为子设备
model	String	产品型号
active_time	Long	设备上次配网时间
lon	String	经度
lat	String	纬度
owner_id	String	设备所在家庭 ID
product_id	String	产品 ID
product_name	String	产品名
category	String	产品类别
icon	String	设备图标
online	Boolean	是否在线

请求成功返回示例

{
  "result": {
    "has_more": false,
    "records": [
      {
        "active_time": 1626252626,
        "category": "ldcg",
        "icon": "smart/program_category_icon/ldcg.png",
        "id": "6c8d95e9b2d8cfe1a*****",
        "ip": "",
        "lat": "",
        "local_key": "dc1ba7ed034****c",
        "lon": "",
        "model": "S-LUX-ZB",
        "name": "光照探测器",
        "online": true,
        "product_id": "pisltm67",
        "product_name": "亮度传感器",
        "sub": true,
        "time_zone": "+08:00",
        "uuid": "6c8d9*****d8cfe1a****"
      }
    ],
    "total": 2,
    "total_pages": 1
  },
  "success": true,
  "t": 1632462436318
}

请求失败返回示例

{
    "success": false,
    "code": 500, // 错误码，详细请见错误码文档
    "msg": "system error,please contact the admin"
}

门锁解锁方式 API

流程图

智能门锁开放能力

获取门锁成员已绑定的解锁方式列表

支持的门锁类型

Wi-Fi 门锁
Zigbee 门锁
蓝牙门锁
可视对讲 WIFI （仅支持家庭成员）

接口地址

GET /v1.0/devices/{device_id}/door-lock/user-types/{user_type}/users/{user_id}/assigned-keys

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是
user_type	Integer	URI	成员类型（1：家庭成员；2：非家庭成员）	是
user_id	String	URI	成员 ID	是
unlock_type	String	URL	解锁类型（fingerprint/password/card）	否

请求示例

GET /v1.0/devices/xxx/door-lock/user-types/2/users/xxx/assigned-keys?unlock_type=card

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	解锁方式信息

result

参数名	类型	说明
unlock_keys	List	解锁方式列表

unlock_keys说明

参数名	类型	说明
unlock_no	Integer	解锁方式ID（密码、指纹、卡等钥匙在门锁上的标识位）
unlock_type	String	解锁类型（fingerprint/password/card）
hijack	Boolean	是否为劫持解锁

请求成功返回示例

{
    "result":{
        "unlock_keys":[
            {
                "unlock_no":3,
                "unlock_type":"card",
                "hijack":false
            }
        ]
    },
    "success":true,
    "t":1593843316481
}

请求失败返回示例

{
    "success":false,
    "code":500, // 错误码，详细请见错误码文档
    "msg":"system error,please contact the admin"
}

获取门锁成员未绑定的解锁方式列表

支持的门锁类型

Wi-Fi 门锁
Zigbee 门锁
蓝牙门锁
Wi-Fi 门禁

接口地址

GET /v1.0/devices/{device_id}/door-lock/unassigned-keys

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是
unlock_type	String	URL	解锁类型（fingerprint/password/card/remoteControl）	否

请求示例

GET /v1.0/devices/xxxx/door-lock/unassigned-keys?unlock_type=card

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	解锁方式信息

result

参数名	类型	说明
unlock_keys	List	解锁方式列表

unlock_keys说明

参数名	类型	说明
unlock_no	Integer	解锁方式ID（密码、指纹、卡等钥匙在门锁上的标识位）
unlock_type	String	解锁类型（fingerprint/password/card）

请求成功返回示例

{
    "result":{
        "unlock_keys":[
            {
                "unlock_no":3,
                "unlock_type":"card"
            }
        ]
    },
    "success":true,
    "t":1593843316481
}

请求失败返回示例

{
    "success":false,
    "code":500, // 错误码，详细请见错误码文档
    "msg":"system error,please contact the admin"
}

云端发起解锁方式同步

支持的门锁类型

带网关的蓝牙门锁
常保活 Wi-Fi
可视对讲 Wi-Fi
Wi-Fi 门禁

接口地址

POST /v1.0/smart-lock/devices/{device_id}/opmodes/actions/sync

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是
codes	String	URL	解锁方式, 多个的话以逗号分隔 unlock_fingerprint：指纹 unlock_card：门卡 unlock_password：密码 unlock_face：人脸 unlock_hand：掌纹 unlock_finger_vein：指静脉 unlock_telecontrol_kit：遥控器	是

请求示例

PUT /v1.0/smart-lock/devices/vdevo12454656****/opmodes/actions/sync

{
    "codes":"unlock_fingerprint,unlock_password"
}

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Boolean	是否发起同步成功 true：成功 false：失败

请求成功返回示例

{
    "result":true,
    "success":true,
    "t":1593843316481
}

请求失败返回示例

{
    "success":false,
    "code":500, // 错误码，详细请见错误码文档
    "msg":"system error,please contact the admin"
}

门锁解锁方式录入

支持的门锁类型

Wi-Fi 门锁
Zigbee 门锁
蓝牙门锁
常保活 Wi-Fi 门锁（仅支持家庭成员）
可视对讲 Wi-Fi（仅支持家庭成员）
Wi-Fi 门禁

接口地址

PUT /v1.0/devices/{device_id}/door-lock/actions/entry

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是
user_id	String	BODY	成员 ID	是
user_type	Integer	BODY	成员类型（1：家庭成员；2：非家庭成员） Wi-Fi门禁请使用 2	是
unlock_type	String	BODY	解锁方式类型 fingerprint: 指纹解锁，password：密码解锁，card：门卡解锁，face：人脸解锁，remoteControl：遥控器	是
password_type	String	BODY	密码加密类型:ticket(当且仅当unlock_type为password, 且是蓝牙锁才有效)	否
ticket_id	String	BODY	密码加密临时秘钥ID(当且仅当unlock_type为password, 且是蓝牙锁才有效)	否
password	String	BODY	密码(当且仅当unlock_type为password, 且是蓝牙锁才有效)	否

请求示例

PUT /v1.0/devices/xxx/door-lock/actions/entry

{
    "unlock_type":"card",
	"user_type":2,
    "user_id":"000xxxwsn"
}

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	是否成功 true：成功 false：失败

请求成功返回示例

{
    "result":true,
    "success":true,
    "t":1593843316481
}

请求失败返回示例

{
    "success":false,
    "code":500, // 错误码，详细请见错误码文档
    "msg":"system error,please contact the admin"
}

门锁解锁方式删除

支持的门锁类型

Wi-Fi 门锁
Zigbee 门锁
蓝牙门锁
常保活 Wi-Fi 门锁（仅支持家庭成员）
Wi-Fi 门禁

接口地址

DELETE /v1.0/devices/{device_id}/door-lock/user-types/{user_type}/users/{user_id}/unlock-types/{unlock_type}/keys/{unlock_no}

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是
user_type	Integer	URI	成员类型（1：家庭成员；2：非家庭成员） Wi-Fi门禁请使用 2	是
user_id	String	URI	成员 ID	是
unlock_type	String	URI	解锁类型（fingerprint/password/card/remoteControl）	是
unlock_no	Integer	URI	解锁方式ID（密码、指纹、卡等钥匙在门锁上的标识位）	是

请求示例

DELETE /v1.0/devices/xxxx/door-lock/user-types/2/users/xxxx/unlock-types/fingerprint/keys/30

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	是否成功 true：成功 false：失败

请求成功返回示例

{
    "result":true,
    "success":true,
    "t":1593843316481
}

请求失败返回示例

{
    "success":false,
    "code":500, // 错误码，详细请见错误码文档
    "msg":"system error,please contact the admin"
}

取消录入解锁方式

支持的门锁类型

Wi-Fi 门锁
Zigbee 门锁
蓝牙门锁
常保活 Wi-Fi 门锁（仅支持家庭成员）
可视对讲 Wi-Fi（仅支持家庭成员）
可视对讲 Wi-Fi（仅支持家庭成员）
Wi-Fi 门禁

接口地址

PUT /v1.0/devices/{device_id}/door-lock/unlock-types/{unlock_type}/actions/cancel

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是
unlock_type	String	URI	解锁类型（fingerprint/password/card/remoteControl）	是

请求示例

PUT /v1.0/devices/xxx/door-lock/unlock-types/card/actions/cancel

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	是否成功 true：成功 false：失败

请求成功返回示例

{
    "result":true,
    "success":true,
    "t":1593843316481
}

请求失败返回示例

{
    "success":false,
    "code":500, // 错误码，详细请见错误码文档
    "msg":"system error,please contact the admin"
}

更新解锁方式名称

支持的门锁类型

Wi-Fi 门禁

接口地址

PUT /v1.0/devices/{device_id}/door-lock/opmodes/{unlock_sn}

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是
unlock_sn	Integer	URI	解锁方式编号	是
dp_code	String	BODY	解锁方式的 dpCode 密码：unlock_password 指纹：unlock_fingerprint 门卡：unlock_card 人脸：unlock_face 遥控器：unlock_telecontrol_kit	是
unlock_name	String	BODY	解锁方式名称	是

请求示例

PUT  /v1.0/devices/vdevo16232264458****/door-lock/opmodes/2

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	是否成功 true：成功 false：失败

请求成功返回示例

{
    "result":true,
    "success":true,
    "t":1593843316481
}

请求失败返回示例

{
    "success":false,
    "code":500, // 错误码，详细请见错误码文档
    "msg":"system error,please contact the admin"
}

设置解锁方式为挟持解锁

支持的门锁类型

Wi-Fi 门锁
Zigbee 门锁
蓝牙门锁

接口地址

PUT /v1.0/devices/{device_id}/door-lock/unlock-types/{unlock_type}/keys/{unlock_no}/hijack

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是
unlock_type	String	URI	解锁类型（fingerprint/password/card）	是
unlock_no	Integer	URI	解锁方式 ID（密码、指纹、卡等钥匙在门锁上的标识位）	是

请求示例

PUT /v1.0/devices/xxx/door-lock/unlock-types/card/keys/130/hijack

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	是否成功 true：成功 false：失败

请求成功返回示例

{
    "result":true,
    "success":true,
    "t":1593843316481
}

请求失败返回示例

{
    "success":false,
    "code":500, // 错误码，详细请见错误码文档
    "msg":"system error,please contact the admin"
}

删除解锁方式的挟持解锁

支持的门锁类型

Wi-Fi 门锁
Zigbee 门锁
蓝牙门锁

接口地址

DELETE /v1.0/smart-lock/devices/{device_id}/unlock-types/{unlock_type}/keys/{unlock_sn}/hijack

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是
unlock_type	String	URI	解锁类型指纹：unlock_fingerprint 门卡：unlock_card 密码：unlock_password	是
unlock_sn	Integer	URI	解锁方式 ID（密码、指纹、卡等钥匙在门锁上的标识位）	是

请求示例

DELETE /v1.0/smart-lock/devices/vdevo12454656****/unlock-types/unlock_fingerprint/keys/1/hijack

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	是否成功 true：成功 false：失败

请求成功返回示例

{
    "result":true,
    "success":true,
    "t":1593843316481
}

请求失败返回示例

{
    "success":false,
    "code":500, // 错误码，详细请见错误码文档
    "msg":"system error,please contact the admin"
}

设置解锁方式特殊属性

支持的门锁类型

Wi-Fi 门锁

接口地址

POST /v1.0/smart-lock/devices/{device_id}/opmodes/{opmode_id}/attribute/{attribute}/opmode-attr

请求参数

参数名	类型	参数类型	说明	是否必填
device_id	String	URI	设备 ID	是
opmode_id	Long	URI	解锁方式序号	是
attribute	Integer	URI	属性 1:语音属性 2:拍照属性	是
enabled	Boolean	BODY	是否开启 true:开启 false:关闭	是

请求示例

POST /v1.0/smart-lock/devices/vdevo12454656****/opnodes/1234/attribute/4/opmode-attr

返回参数

参数名	类型	说明
code	Integer	返回的错误码，成功时为空，详情⻅返回的错误码
success	Boolean	是否成功 true：成功 false：失败
t	Long	响应时间
msg	String	请求失败的信息，成功为空
result	Object	是否成功 true：成功 false：失败

请求成功返回示例

{
    "result":true,
    "success":true,
    "t":1593843316481
}

请求失败返回示例

{
    "success":false,
    "code":500, // 错误码，详细请见错误码文档
    "msg":"system error,please contact the admin"
}

门锁通用能力下发控制

门锁解锁方式录入结果推送

支持的门锁类型

Wi-Fi 门锁
Zigbee 门锁
蓝牙门锁

参数说明

参数名	类型	说明
bizCode	String	事件类型码
devId	String	设备 ID
uuid	Integer	设备 UUID
bizData	Object	解锁方式状态
ts	Long	时间戳

bizCode

bizCode	说明
doorUnlockMethodStatus	门锁解锁方式状态

bizData

code	数据类型	说明
finish	Boolean	是否完成录入
operate	Integer	操作 1. 发起操作 2. 取消操作
raised	Boolean	是否已发起
totalPeriod	Integer	总录入次数（会单独且只会推送一次总录入次数）
period	Integer	剩余录入次数
event	String	事件(unlockMethodEntry/unlockMethodDelete)

数据格式

{
    "bizCode":"doorUnlockMethodStatus",
    "bizData":{
        "finish":false,
        "operate":1,
        "raised":true,
        "totalPeriod":2,
        "period":2,
        "event":"unlockMethodEntry"
    },
    "uuid":"xxxx",
    "devId":"xxxx"
}

获取设备详情

接口描述

可查询设备的详情信息，包括设备属性和设备最新状态。

接口地址

GET /v1.0/devices/{device_id}

请求参数

参数名	类型	参数类型	必填	说明
device_id	String	URI	是	设备 ID

返回参数

参数名	类型	说明
code	Integer	响应码，详见错误码。
success	Boolean	判断请求是否成功。 true：成功 false：失败
msg	String	请求失败返回的信息，成功则返回空值。
result	Object<result>	返回结果。

result 说明

参数名	类型	说明
id	String	设备编号
name	String	设备名称
uid	String	用户 ID
local_key	String	密钥
category	String	产品类别
product_id	String	产品 ID
product_name	String	产品名称
sub	Boolean	判断是否为子设备 true：是 false：不是
uuid	String	设备唯一标识
owner_id	String	家庭 ID
online	Boolean	设备在线状态
status	Object<status>	设备功能状态
active_time	Long	设备激活时间，时间戳，精确到秒
biz_type	Long	应用 biztype
icon	String	设备图标
ip	String	设备 IP

status 说明

参数名	类型	说明
code	String	功能点 Code
value	String	功能点的值
type	String	功能点的类型

请求示例

GET /v1.0/devices/vdevo153490924188132

SDK 示例

TuyaClient client = new TuyaClient(clientId, secret, RegionEnum.CN);
DeviceVo deviceVo = client.getDeviceInfo(DEV_ID);
System.out.println("获取设备信息: ");
System.out.println(JSONObject.toJSONString(deviceVo));

返回示例

{
    "success": true,
    "result": {
        "active_time": 1589505938,
        "biz_type": 299009,
        "category": "qt",
        "create_time": 1560827137,
        "icon": "smart/icon/15402589135gknz23xajb_0.png",
        "id": "60613135b121cddc294****",
        "ip": "120.198.****.****",
        "local_key": "3a9b50126fe473****",
        "name": "体脂秤",
        "online": true,
        "owner_id": "1070****",
        "product_id": "g0er6hSKgMqr****",
        "product_name": "Wifi scales_OEM",
        "status": [
            {
                "code": "weight",
                "value": "48900"
            },
            {
                "code": "left_hand_r",
                "value": "0"
            },
            {
                "code": "right_hand_r",
                "value": "0"
            },
            {
                "code": "left_leg_r",
                "value": "0"
            },
            {
                "code": "right_leg_r",
                "value": "0"
            },
            {
                "code": "body_r",
                "value": "653"
            },
            {
                "code": "battery_low",
                "value": "false"
            }
        ],
        "sub": false,
        "time_zone": "+08:00",
        "uid": "ay157896239864843g****",
        "update_time": 1589764585,
        "uuid": "60613135b23cddc294****"
    }
}

错误码

以下为该接口常见的业务异常，更多的异常错误，请参考全局错误码。

错误码	说明
500	系统错误
1106	权限非法

上一篇垂直品类硬件 API

下一篇API 列表