智能门锁开放能力

更新时间:2023-06-20 14:53:58下载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://airtake-public-data-1254153901.cos.ap-shanghai.myqcloud.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 权限非法