简体中文
简体中文
English
联系我们
注册
登录

智能门锁

更新时间:2022-06-29 11:20:50下载pdf

API 列表

API 的返回参数以本文描述为准,接口返回结果如果不在本文描述内,请勿使用。

action 描述
doorLock.alarmLogs 查询告警记录
doorLock.listRecords 开门记录/告警记录
doorLock.operateRecords 查询最近一条日志记录
doorLock.loglatest 日志记录
doorLock.getAvailableInstructions 获取门锁设备的标准 dpCode 和 dpId 的映射关系
doorLock.passwordFreeOpen 门锁免密开门
doorLock.openingLogs 查询开门记录
doorLock.getDynamicPassword 查询动态密码
doorLock.passwordTicket 密码加密的流程
doorLock.passwordTicket 查询密码加密的临时秘钥
doorLock.getTemporaryPassword 查询临时密码信息
doorLock.getTemporaryPasswordList 查询临时密码列表
doorLock.createTemporaryPassword 创建临时密码
doorLock.modifyTemporaryPassword 修改临时密码
doorLock. modifyTemporaryPassword 临时密码重命名
doorLock. deleteTemporaryPassword 删除临时密码
device.status 查询设备最新状态
device.control 指令下发
doorLock.remoteUnlocks 查询门锁支持的远程开门方式
doorLock.remoteUnlockConfig 设置门锁远程开门的开关
doorLock.listUnallocatedOpmodes 获取未关联的解锁方式列表
doorLock.allocateOpmode 关联解锁方式
doorLock.deallocateOpmode 取消关联解锁方式
doorLock.createPermissionSharing 门锁临时开锁权限分享链接-生成
doorLock.verifyPermissionSharing 门锁临时开锁权限分享链接-校验
doorLock.confirmPermissionSharing 门锁临时开锁权限分享链接-确认
doorLock.cancelPermissionSharing 门锁临时开锁权限分享链接-取消
doorLock.setHijack 设置解锁方式为劫持
doorLock.removeHijack 移除解锁方式劫持功能
doorLock.unlockInstruction 近程免密开门
doorLock.bleOpenInstruction 蓝牙近场开门数据组装
device.pairingAuthKey 查询密钥 authKey
timer.currentTime 查询系统时间
doorLock.getIssuedConfig 查询校验开锁前需要同步的配置
device.getListByIds t0 时间的下发
doorLock.getSyncableOpmodeTypes 成员数据同步
doorLock.openDoor 门锁含密开门
doorLock.cancelPasswordFreeOpen 门锁远程开门请求拒绝
doorLock.deleteOfflinePassword 删除离线密码
doorLock.getMediaUrl 获取最近一次的远程开门或告警封面图

用户相关 API 列表

action 描述
doorLock.getUser 获取用户信息
doorLock.listUserOpmodes 查询用户的解锁方式详情
doorLock.listUsers 成员列表

门锁通用功能

查询告警记录

支持的门锁类型

类型 支持
门锁类型 Wi-Fi 门锁
门锁类型 Zigbee 门锁
门锁类型 蓝牙门锁

接口地址

action:  doorLock.alarmLogs

请求参数

参数名 类型 参数类型 说明 是否必须
device_id String URI 设备 ID
page_no Integer URL 页号
page_size Integer URL 分页大小
codes String URL 告警功能标准功能 code,按逗号拼接

请求示例

{
  "action": "doorLock.alarmLogs",
  "params": {
    "device_id": "vdevo15345926009****",
    "page_no": "1",
    "page_size": "20",
    "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 状态变更时间
nick_name 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 门锁
门锁类型 蓝牙门锁

接口地址

action doorLock.listRecords

请求参数

参数名 类型 参数类型 说明 是否必填
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 每页数据量

请求示例

{
  "action": "doorLock.listRecords",
  "params": {
    "device_id":"eb289eyjlyn8****",
    "target_standard_dp_codes":"unlock_fingerprint,unlock_password",
    "start_time":0,
    "end_time":0,
    "page_no":0,
    "page_size":10
  }
}

返回参数

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

result 说明

参数名 类型 说明
record_id String 数据的唯一标识
user_id String 用户 ID
user_name String 用户名
unlock_name String 解锁方式对应的名称
avatar String 头像
gmt_create Long 数据的创建时间
dps List 一个数组,里面的每个元素的 key 是标准 dpCode,value 为 DP 的值
status Integer 状态
record_type String 记录类型. alarm-告警类型的记录; normal-普通开门记录
media_info_list JSON 数组 开门时拍的照片/视频信息
member_bindable_flag Integer 1- 可关联人; 0- 不能关联人(可能已经关联过了)
union_unlock_info JSON 数组 组合解锁信息集合
channel_id String 通道 ID. 当门锁是一个中控设备,可以控制多个门的时候, 该字段有用(比如门禁场景)

media_info_list 说明

字段 类型 描述
file_url String 文件地址 (全路径)
file_key String 加密密钥
file_path String 文件路径
bucket String 文件所在的 bucket

union_unlock_info 说明

字段 类型 描述
user_name String 用户名
opmode String 解锁类型。用什么方式解锁,是一个 dpCode,比如 "unlock_password"表示密码解锁
unlock_name String 解锁方式名称

请求成功返回示例

{
    "unreadCount":10,
    "total":25,
    "records":[
        {
            "dps":[
                {
                    "unlock_password":"97"
                }
            ],
            "avatar":"https://airtake-public-data.oss-cn-hangzhou.aliyuncs.com/smart/user_res/avatar/scale/user_icon_default.png",
            "user_name":"",
            "unlock_name":"",
            "gmt_create":1579339465000,
            "record_id":"15793300059C669FD0B31E173A6D1E2F550010946****",
            "user_id":"0",
            "status":1,
            "record_type":"normal",
            "member_bindable_flag":0,
            "channel_id":"12",
            "media_info_list":[
                {
                    "file_url":"https://ty-cn-storage30-1254153901.cos.ap-shanghai.myqcloud.com/6cd8d231782a2c3721Qhhl/1588216645118_1588215615.jpg",
                    "file_key":"659FAA1D8F95104"
                }
            ],
            "union_unlock_info":[
                {
                    "user_name":"王总",
                    "opmode":"unlock_password",
                    "unlock_name":"密码 1"
                },
                {
                    "user_name":"刘总",
                    "opmode":"unlock_fingerprint",
                    "unlock_name":"一阳指"
                }
            ]
        }
    ]
}

日志记录

支持的门锁类型

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

接口地址

action doorLock.operateRecords

请求参数

参数名 类型 参数类型 说明 是否必填
device_id String URI 设备 ID
startTime Long QUERY 起始时间 最近三天、最近一周、最近一个月、自定义(可选单天或任意时间段)可选全部,即默认选项,默认全部时传 0
endTime Long QUERY 结束时间 最近三天、最近一周、最近一个月、自定义(可选单天或任意时间段)可选全部,即默认选项,默认全部时传 0
userIds String QUERY 家庭成员用户 ID
logCategories Integer QUERY 日志大类:
  • 操作日志:operation
  • 开门记录:unlock_record
  • 关门记录:close_record
  • 告警记录:alarm_record
lastRowKey string QUERY 上一次查询记录会返回,第一次请求的时候不用传
pageSize Integer QUERY 最大 100
onlyShowMediaRecord bool QUERY true:带图片

请求示例

{
    "action": "doorLock.operateRecords",
    "params": {
  	"device_id":"deviceId",
	"startTime":"1646116582",
	"endTime":"1646116582",
	"userIds":"sha124124",
	"logCategories":"unlock_record",
	"onlyShowMediaRecord":"true",
    }
}

返回参数

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

result 说明

参数名 类型 说明
hasMore boolean 是否有更多数据
lastRowKey String 上一次请求 key
records Object

records 返回示例

{
  "records": [
    {
      "log_id": '34679xxx',
      "log_type": 'doorbell',
      "media_info_list": [
        {
          "bucket": 'ty-cn-bizlock-1254153901',
          "file_key": '3xgxxxxxxx',
          "file_path": 'xxxx.jpg',
          "file_url":'',
          "angle": 0,
          "media_key": 'uv59xsf9jcy5vdkm',
          "media_path": 'xxxxx.mjpeg',
          "media_url": '',
          "media_bucket": 'xxxx',
        },
      ],
      "unlock_name": '',
      "user_id": '0',
      "log_category": 'alarm_record',
      "user_name": '',
      "member_bindable_flag": false,
      "dp_id": 19,
      "time": 1654849301000,
      "record_type": 2,
      "current_user": false,
    },

查询最近一条日志记录

支持的门锁类型

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

接口地址

action doorLock.loglatest

请求参数

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

请求示例

{
"action": "doorLock.loglatest",
    "params": {
        "device_id":"vedeo411aa97e86169akp4",
    }
}

返回参数

参数名 类型 说明
exist bool 是否存在。true 表示存在。
logId Long 日志编号
logCategory string 日志大类:
  • 操作日志:operation
  • 开门记录:unlock_record
  • 关门记录:close_record
  • 告警记录:alarm_record
logType String 日志类型
recordType int 仅开门记录返回。
1. 普通开门记录
2. 告警记录
unlockNameRosettaKey String 关锁记录的多语言
currentUser bool 是否是当前用户的记录,true 表示当前用户的记录,非组合解锁必反回。
userId String 用户编号 (仅开门记录,劫持告警,操作记录返回)
userName String 用户名称
unlockName String 解锁方式名称,可能为空
time Long 日志事件时间
relateDevName String 关联设备名称
relateOpMode String 关联解锁信息
unionUnlockInfo object 组合解锁信息
data Long 告警或操作记录的详情数据
unReadCount int 未读记录数

unionUnlockInfo

参数名 类型 说明
userName String 组合解锁时,触发的用户名称 (可能为空)
opMode String 组合解锁时,解锁方式类型
unlockName String 组合解锁时,解锁方式名称 (可能为空)
currentUser bool 组合解锁时,是否是当前用户
sn int 组合解锁时,硬件编号

返回示例

{
    "logId":123345,
    "devId":"6ccf3bec5pnxkhdy",
    "logCategory":"operate_log",
    "logType":"dev_bind",
    "userId":123,
    "userName":"用户1",
    "currentUser":false,
    "unReadCount":1
    
}

获取门锁设备的标准 dpCode 和 dpId 的映射关系

支持的门锁类型

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

接口地址

action doorLock.getAvailableInstructions

请求参数

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

请求示例

{
  "device_id":"6cae1drr3kpl****"
}

返回参数

一个数组,数组中的元素如下。

字段名 类型 描述
dp_id Integer dpId
dp_code String dpCode

返回示例

[
    {
        "dp_code":"unlock_password",
        "dp_id":12
    },
    {
        "dp_code":"unlock_fingerprint",
        "dp_id":13
    }
]

门锁免密开门

支持的门锁类型

类型 支持
门锁类型 Wi-Fi 门锁
门锁类型 Zigbee 门锁
门锁类型 蓝牙门锁
门锁类型 公版 Wi-Fi 门禁

接口地址

action doorLock.passwordFreeOpen

请求参数

参数名 类型 参数类型 说明 是否必填
device_id String URI 设备 ID
ticket_id String Body 授权的密钥 ID (doorLock.passwordTicket 接口获取)
channel_id String Body 门禁的通道 ID (仅 Wi-Fi 门禁需要传此参数)

请求示例

{
  "action": "doorLock.passwordFreeOpen",
  "params": {
    "device_id": "vdevo15345926009****",
    "ticket_id": "9wxxoLM"
  }
}

返回参数

参数名 类型 说明
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 门锁
门锁类型 蓝牙门锁

接口地址

action: doorLock.openingLogs

请求参数

参数名 类型 说明 是否必须
device_id String 设备 ID
page_no Integer 页号
page_size Integer 分页大小
start_time Long 开始时间,单位毫秒
end_time Long 结束时间,单位毫秒

请求示例

{
  "action": "doorLock.openingLogs",
  "params": {
    "device_id": "vdevo15792460703****",
    "page_no": 1,
    "page_size": 20,
    "start_time": 1583213146000,
    "end_time": 1583213546000
  }
}

返回参数

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

result 说明

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

logs 说明

参数名 类型 说明
avatar String 头像
nick_name String 用户名
unlock_name String 密码名称
update_time Long 更新时间
user_id String 用户 ID
status List 门锁状态列表

status 说明

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

状态码说明

参数名 类型 说明
unlock_finger Long 指纹解锁,门锁本地分配的编号
unlock_password Long 密码解锁,门锁本地分配的编号
unlock_temporary Long 临时密码解锁,门锁本地分配的编号
unlock_dynamic Long 动态密码解锁,门锁本地分配的编号
unlock_card Long 卡片解锁,门锁本地分配的编号
unlock_face Long 人脸解锁,门锁本地分配的编号
unlock_key Long 机械钥匙解锁,门锁本地分配的编号

返回示例

{
  "success": true,
  "t": 1542626129429,
  "result": {
    "total": 1,
    "logs": [
      {
        "status": {
          "code": "unlock_finger",
          "value": "123456"
        },
        "update_time": 1543297979
      }
    ]
  }
}

查询动态密码

支持的门锁类型

类型 支持
门锁类型 Wi-Fi 门锁
门锁类型 Zigbee 门锁
门锁类型 蓝牙门锁

接口地址

action: doorLock.getDynamicPassword

请求参数

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

请求示例

{
  "action": "doorLock.getDynamicPassword",
  "params": {
    "device_id": "vdevo15792460703****"
  }
}

返回参数

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

result 说明

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

返回示例

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

密码加密的流程

智能门锁

查询密码加密的临时秘钥

支持的门锁类型

类型 支持
门锁类型 Wi-Fi 门锁
门锁类型 Zigbee 门锁
门锁类型 蓝牙门锁

接口地址

action: doorLock.passwordTicket

请求参数

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

请求示例

{
  "action": "doorLock.passwordTicket",
  "params": {
    "device_id": "vdevo15345926009****"
  }
}

返回参数

参数名 类型 说明
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": "901CC35A67DA3429C38E9622****3EAE1CE333462356D257FD1D3E5C"
  },
  "success": true,
  "t": 1592899848757
}

请求失败返回示例

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

查询临时密码信息

支持的门锁类型

类型 支持
门锁类型 Wi-Fi 门锁
门锁类型 Zigbee 门锁
门锁类型 蓝牙门锁
门锁类型 Wi-Fi 门禁

接口地址

action: doorLock.getTemporaryPassword

请求参数

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

请求示例

{
  "action": "doorLock.getTemporaryPassword",
  "params": {
    "device_id": "vdevo15345926009****",
    "password_id": 1001
  }
}

返回参数

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

result 说明

参数名 类型 说明
password_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 周期性功能参数列表
sn Integer 蓝牙产品的密码的序号

schedule_list

参数名 类型 说明
effective_time Long 当天开始时间,单位分钟
invalid_time Long 当天过期时间,单位分钟
working_day Int 星期用一个字节来表示,bit0 ~ bit6 分别代表周日~周六

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
  }
}

请求失败返回示例

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

查询临时密码列表

支持的门锁类型

类型 支持
门锁类型 Wi-Fi 门锁
门锁类型 Zigbee 门锁
门锁类型 蓝牙门锁
门锁类型 Wi-Fi 门禁

接口地址

action :doorLock.getTemporaryPasswordList

请求参数

参数名 类型 说明 是否必填
device_id String 设备 ID
valid Boolean true 是未失效密码
false 为失效密码

请求示例

{
  "action": "doorLock.getTemporaryPasswordList",
  "params": {
    "device_id": "vdevo15345926009****"
  }
}

返回参数

参数名 类型 说明
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 周期性功能参数列表
sn Integer 蓝牙产品的密码的序号

schedule_list

参数名 类型 说明
effective_time Long 当天开始时间,单位分钟
invalid_time Long 当天过期时间,单位分钟
working_day Int 星期用一个字节来表示,bit0 ~ bit6 分别代表周日~周六

phase 说明

zigbee: 1:待创建  2:正常  3:已冻结  4:已删除  5:创建失败
wifi:   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
    }
  ]
}

请求失败返回示例

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

创建临时密码

支持的门锁类型

类型 支持
门锁类型 Wi-Fi 门锁
门锁类型 Zigbee 门锁
门锁类型 蓝牙门锁
门锁类型 Wi-Fi 门禁

接口地址

action: doorLock.createTemporaryPassword

请求参数

参数名 类型 参数类型 说明 是否必填
device_id String URI 设备 ID
name String BODY 临时密码名称
password String BODY Wi-Fi 锁密码原文长度为 7,zigbee 锁/蓝牙锁原文密码为 6,密码,传输使用加密算法使用 AES,模式:ECB pkcs7padding 数据块 128 位,秘钥为通过接口查询的临时 ticket_key 使用开发者 accessKey(尽量通过接口查询,如果是 OEM 也可以直接拿平台上的使用) 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 周期性功能设置参数列表
bluetooth_symbolic Boolean BODY 蓝牙门锁微信小程序需要传递 true
sn Integer BODY 蓝牙产品的密码的序号

schedule_list

参数名 类型 参数类型 说明 是否必填
effective_time Long BODY 当天开始时间,单位分钟
invalid_time Long BODY 当天过期时间,单位分钟
working_day Int BODY 星期用一个字节来表示,bit0 ~ bit6 分别代表周日~周六

请求示例

{
  "action": "doorLock.createTemporaryPassword",
  "params": {
    "device_id": "vdevo15345926009****",
    "password": "956FAD7****09C68E168B77",
    "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 门锁
门锁类型 蓝牙门锁

接口地址

action: doorLock.createTemporaryPasswordWithoutName

请求参数

参数名 类型 参数类型 说明 是否必填
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 周期性功能设置参数列表
bluetooth_symbolic Boolean BODY 蓝牙门锁微信小程序需要传递 true
sn Integer BODY 蓝牙产品的密码的序号

schedule_list

参数名 类型 参数类型 说明 是否必填
effective_time Long BODY 当天开始时间,单位分钟
invalid_time Long BODY 当天过期时间,单位分钟
working_day Int BODY 星期用一个字节来表示,bit0 ~ bit6 分别代表周日~周六

请求示例

{
  "action": "doorLock.createTemporaryPasswordWithoutName",
  "params": {
    "device_id": "vdevo15345926009****",
    "password": "956FAD7****09C68E168B77",
    "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"
}

修改临时密码

支持的门锁类型

类型 支持
门锁类型 Wi-Fi 门锁
门锁类型 Zigbee 门锁
门锁类型 蓝牙门锁(不支持密码修改)
门锁类型 Wi-Fi 门禁

接口地址

action: doorLock.modifyTemporaryPassword

请求参数

参数名 类型 参数类型 说明 是否必填
device_id String URI 设备 ID
password_id Long URI 密码 ID
name String BODY 临时密码名字
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 周期性功能设置参数列表
bluetooth_symbolic Boolean BODY 蓝牙门锁微信小程序需要传递 true

schedule_list

参数名 类型 参数类型 说明 是否必填
effective_time Long BODY 当天开始时间,单位分钟
invalid_time Long BODY 当天过期时间,单位分钟
working_day Int BODY 星期用一个字节来表示,bit0 ~ bit6 分别代表周日~周六

请求示例

{
  "action": "doorLock.modifyTemporaryPassword",
  "params": {
    "device_id": "vdevo15345926009****",
    "password_id": 1234213434,
    "phone": "",
    "effective_time": "",
    "invalid_time": "",
    "name": "",
    "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"
}

临时密码重命名

支持的门锁类型

类型 支持
门锁类型 Wi-Fi 门锁
门锁类型 Zigbee 门锁
门锁类型 蓝牙门锁(不支持密码修改)

接口地址

action: doorLock.modifyTemporaryPassword

请求参数

参数名 类型 参数类型 说明 是否必填
device_id String URI 设备 ID
password_id Long URI 密码 ID
name String BODY 临时密码名字
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 周期性功能设置参数列表
bluetooth_symbolic Boolean BODY 蓝牙门锁微信小程序需要传递 true

schedule_list

参数名 类型 参数类型 说明 是否必填
effective_time Long BODY 当天开始时间,单位分钟
invalid_time Long BODY 当天过期时间,单位分钟
working_day Int BODY 星期用一个字节来表示,bit0 ~ bit6 分别代表周日~周六

请求示例

{
  "action": "doorLock.modifyTemporaryPassword",
  "params": {
    "device_id": "vdevo15345926009****",
    "password_id": 1234213434,
    "phone": "",
    "effective_time": "",
    "invalid_time": "",
    "name": "修改名字",
    "password": "",
    "password_type": "",
    "ticket_id": ""
  }
}

返回参数

参数名 类型 说明
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 门锁
门锁类型 蓝牙门锁
门锁类型 Wi-Fi 门禁

接口地址

action : doorLock.deleteTemporaryPassword

请求参数

参数名 类型 说明
device_id String 设备 ID
password_id String 密码 ID
bluetooth_symbolic Boolen 蓝牙门锁微信小程序需要传递 true

请求示例

{
  "action": "doorLock.deleteTemporaryPassword",
  "params": {
    "device_id": "vdevo15345926009****",
    "password_id": 12342134123
  }
}

返回参数

参数名 类型 说明
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 门锁
门锁类型 蓝牙门锁

接口地址

action : doorLock.removalInvalidTempPasswords

请求参数

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

请求示例

{
  "action": "doorLock.removalInvalidTempPasswords",
  "params": {
    "device_id": "vdevo15345926009****"
  }
}

返回参数

参数名 类型 说明
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"
}

查询设备最新状态

请求地址

action:  device.status

params 请求参数

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

请求示例

{
  "action": "device.status",
  "params": {
    "device_id": "vdevo15834602718****"
  }
}

响应参数

参数名 类型 说明
code Integer 响应码
success Boolean 是否成功:
  • true:成功
  • false:失败
msg String 请求失败的信息,成功为空
result Boolean 是否成功

响应示例

{
  "result": [
    {
      "code": "switch_led",
      "value": true
    },
    {
      "code": "work_mode",
      "value": "white"
    },
    {
      "code": "bright_value_v2",
      "value": 370
    },
    {
      "code": "temp_value_v2",
      "value": 216
    },
    {
      "code": "scene_data_v2",
      "value": ""
    },
    {
      "code": "countdown_1",
      "value": 0
    },
    {
      "code": "control_data",
      "value": "{\"bright\":370,\"change_mode\":\"gradient\",\"h\":0,\"s\":0,\"temperature\":216,\"v\":0}"
    }
  ],
  "success": true,
  "t": 1583740617030
}

指令下发

请求地址

action:  device.control

params 请求参数

参数名 类型 说明 是否必需
device_id String 设备 ID
commands Object 命令集

请求示例

{
  "action": "device.control",
  "params": {
    "device_id": "vdevo15813256493****",
    "commands": [
      {
        "code": "switch_led",
        "value": true
      }
    ]
  }
}

响应参数

参数名 类型 说明
code Integer 响应码
success Boolean 是否成功:
  • true:成功
  • false:失败
msg String 请求失败的信息,成功为空
result Boolean 是否成功

查询门锁支持的远程开门方式

支持的门锁类型

类型 支持
门锁类型 Wi-Fi 门锁
门锁类型 Zigbee 门锁
门锁类型 蓝牙门锁

接口地址

action : doorLock.remoteUnlocks

请求参数

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

请求示例

{
  "action": "doorLock.remoteUnlocks",
  "params": {
    "device_id": "vdevo15345926009****"
  }
}

返回参数

参数名 类型 说明
code Integer 错误响应码,成功时为空(详情参考错误码)
success Boolean 是否成功:
  • true:成功
  • false:失败
t Long 响应时间
msg String 请求失败的信息,成功为空
result List 结果

result

参数名 类型 说明
remote_unlock_type String 开门方式:
remoteUnlockWithoutPwd: 免密开门
remoteUnlockWithPwd: 含密开门
open Boolen 是否开启
device_id String 设备 ID

请求成功返回示例

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

请求失败返回示例

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

设置门锁远程开门的开关

支持的门锁类型

类型 支持
门锁类型 Wi-Fi 门锁
门锁类型 Zigbee 门锁
门锁类型 蓝牙门锁

接口地址

action : doorLock.remoteUnlockConfig

请求参数

参数名 类型 参数类型 说明
device_id String URI 设备 ID
remote_unlock_type String Body 开门方式
open Boolen Body 是否开启

请求示例

{
  "action": "doorLock.remoteUnlockConfig",
  "params": {
    "device_id": "vdevo15345926009****",
    "open": true,
    "remote_unlock_type": ""
  }
}

返回参数

参数名 类型 说明
code Integer 错误响应码,成功时为空(详情参考错误码)
success Boolean 是否成功:
  • true:成功
  • false:失败
t Long 响应时间
msg String 请求失败的信息,成功为空
result Boolen 结果

请求成功返回示例

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

请求失败返回示例

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

获取未关联的解锁方式列表

支持的门锁类型

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

接口地址

action : doorLock.listUnallocatedOpmodes

请求参数

参数名 类型 说明
device_id String 设备 ID
page_no Integer 当前页数 (从 1 开始计数)
page_size Integer 每页数据量

请求示例

{
	"device_id":"6cdbaew2mm6v****",
  	"page_no":1,
  	"page_size": 10
}

返回参数

参数名 类型 说明
opmode String 解锁方式的类型
standard_dp String 解锁方式的标准 DP
unlock_info List 解锁方式的具体值

unlock_info 说明

参数名 类型 说明
dp_code String 解锁方式的标准 dpCode
unlock_sn Integer 解锁方式的编号
unlock_name String 门锁方式名称

返回示例

[
    {
        "opmode":"12",
        "standard_dp":"unlock_fingerprint",
      	"unlock_info":[
          {
            "dp_code":"unlock_fingerprint",
            "unlock_sn":3,
            "unlock_name":"一阳指"
          }
        ]
    }
]

关联解锁方式

支持的门锁类型

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

接口地址

action : doorLock.allocateOpmode

请求参数

参数名 类型 参数类型 说明
device_id String URI 设备 ID
user_id String BODY 用户 ID
unlock_list 数组 BODY 解锁方式列表

*unlock_list 说明

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

请求示例

{
    "device_id":"eb289eyjlyn8****",
    "user_id":"23578",
    "unlock_list":[
        {
            "dp_code":"unlock_password",
            "unlock_sn":1
        },
        {
            "dp_code":"unlock_card",
            "unlock_sn":2
        }
    ]
}

返回参数

参数名 类型 说明
code Integer 错误响应码,成功时为空(详情参考错误码)
success Boolean 是否成功:
  • true:成功
  • false:失败
t Long 响应时间
msg String 请求失败的信息,成功为空
result Boolen 结果

返回结果示例

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

取消关联解锁方式

支持的门锁类型

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

接口地址

action : doorLock.deallocateOpmode

请求参数

参数名 类型 说明
device_id String 设备 ID
user_id String 用户 ID (解锁方式目前属于谁)
dp_code String 解锁方式的标准 dpCode
unlock_sn Integer 解锁方式编号

请求示例

{
	"device_id":"6cdbaew2mm6v****",
  	"user_id":"109238",
  	"dp_code":"unlock_password",
  	"unlock_sn":3
}

返回参数

参数名 类型 说明
code Integer 错误响应码,成功时为空(详情参考错误码)
success Boolean 是否成功:
  • true:成功
  • false:失败
t Long 响应时间
msg String 请求失败的信息,成功为空
result Boolen 结果

返回结果示例

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

门锁临时开锁权限分享链接-生成

支持的门锁类型

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

接口地址

action : doorLock.createPermissionSharing

请求参数

参数名 类型 说明 备注
device_id String 设备 ID
app_schema String 应用标识 ‘cloud’
sharer String 分享人账号 分享人为当前登录用户,则填写当前登录用户的 uid
receiver String 接受人账号(可不填写)
permission_detail JSON 权限详情

permission_detail 说明

参数名 类型 说明
biz_type String 业务类型:
- unlock_ble:蓝牙开锁
- unlock_fingerprint:指纹开锁
available_times Integer 可用次数。
- -1:不限次数
- 其他值:表示可用次数
name String name
effective_time Long 有效时间, 不填写则为永远
invalid_time Long 失效时间, 不填写则为永远
schedule_start_time Integer 循环的开始时间 (以小时分钟形式存放, 比如 “07:30” 时,该值是 7x60+30=450)
schedule_end_time Integer 循环的结束时间(以小时分钟形式存放, 比如 “08:30” 时,该值是 8x60+30=510)
working_day Integer 循环工作日 workingDay 的格式说明: 一周的时间打标。bit0 ~ bit6 分别代表周日~周六; 1 表示有效, 0 表示无效; 最后一位以 0 表示.比如周一/周二/周五的表示为: 00100110 = 38, 最终 workingDay=38

请求示例

{
    "action":"doorLock.createPermissionSharing",
    "params":{
        "device_id":"vdev233****",
        "sharer":"ay16188442964611MKHJ",
        "app_schema":"e5b2e9464c206cff6e16f8280f5be730",
      	"permission_detail":{
            "biz_type":"unlock_ble",
            "available_times":-1,
            "name":"张阿姨蓝牙开锁",
            "effective_time":1621101162000,
            "invalid_time":1621965162000,
            "schedule_start_time":450,
            "schedule_end_time":510,
            "working_day":38
        }
    }
}

返回参数

参数名 类型 说明
sharing_id String 分享 ID
sharing_ticket String 分享票据,一次有效
expire_time Long 失效时间,单位:秒

返回示例

{
    "expire_time":300,
    "sharing_id":"1213089",
    "sharing_ticket":"3ea6e254e83750dc924dd78dd5a61460"
}

门锁临时开锁权限分享链接-校验

支持的门锁类型

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

接口地址

action : doorLock.verifyPermissionSharing

请求参数

参数名 类型 说明 备注
sharing_ticket String 分享票据

请求示例

{
	"sharing_ticket":"3ea6e254e83750dc924dd78dd5a61460"
}

返回参数

参数名 类型 说明
sharing_id String 分享 ID
sharing_ticket String 分享票据,一次有效
expire_time Long 失效时间,单位:秒 (如果小于等于 0 则说明已失效)

返回示例

{
    "expire_time":100,
    "sharing_id":"1213089",
    "sharing_ticket":"3ea6e254e83750dc924dd78dd5a61460"
}

门锁临时开锁权限分享链接-确认

支持的门锁类型

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

接口地址

action : doorLock.confirmPermissionSharing

请求参数

参数名 类型 说明 备注
sharing_id String 分享 ID
app_schema String 应用标识 ‘cloud’
sharing_ticket String 分享票据
receiver String 接受人账号 为打开此分享链接账号的 uid

请求示例

{
    "action":"doorLock.confirmPermissionSharing",
    "params":{
        "sharing_id":"10001",
        "sharing_ticket":"3ea6e254e83750dc924dd78dd5a61460",
        "app_schema":"e5b2e9464c206cff6e16f8280f5be730",
      	"receiver":"ay16198742964611KDYU"
    }
}

返回参数

成功则会返回值, 不成功返回 null

参数名 类型 说明
permission_id Long 权限 ID
biz_type String 业务类型:
- unlock_ble:蓝牙开锁
- unlock_fingerprint:指纹开锁
available_times Integer 可用次数。
- -1:不限次数
- 其他值表示可用次数
name String 名称
effective_time Long 有效时间
invalid_time Long 失效时间
schedule_start_time Integer 循环的开始时间 (以小时分钟形式存放, 比如"07:30" 时,该值是 7x60+30=450)
schedule_end_time Integer 循环的结束时间 (以小时分钟形式存放, 比如"08:30" 时,该值是 8x60+30=510)
working_day Integer 循环工作日 workingDay 的格式说明: 一周的时间打标。bit0 ~ bit6 分别代表周日~周六; 1 表示有效, 0 表示无效; 最后一位以 0 表示。比如周一/周二/周五的表示为: 00100110 = 38, 最终 workingDay=38
effective_flag Integer 是否有效的标记。0- 无效, 1- 有效, 2- 未生效 (由于时间未到)
schedule_effective_flag Integer 当前时间是否落在循环时间的内。0-无效, 1-有效 (当 effective_flag 无效, 这里一定是无效)

返回示例

{
    "biz_type":"unlock_ble",
    "available_times":1,
    "name":"张阿姨蓝牙开锁",
    "effective_time":1621101162000,
    "invalid_time":1621965162000,
    "schedule_start_time": 480,
    "schedule_end_time": 510,
    "working_day":100,
    "effective_flag":1,
    "schedule_effective_flag":0
}

门锁临时开锁权限分享链接-取消

支持的门锁类型

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

接口地址

action : doorLock.cancelPermissionSharing

请求参数

参数名 类型 说明 备注
sharing_id String 分享 ID
sharing_ticket String 分享票据

请求示例

{
  "sharing_id":"2322",
  "sharing_ticket":"3ea6e254e83750dc924dd78dd5a61460"
}

返回参数

参数名 类型 说明
code Integer 错误响应码,成功时为空(详情参考错误码)
success Boolean 是否成功:
  • true:成功
  • false:失败
t Long 响应时间
msg String 请求失败的信息,成功为空
result Boolen 结果

返回结果示例

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

设置解锁方式为劫持

支持的门锁类型

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

接口地址

doorLock.setHijack

请求参数

参数名 类型 参数类型 说明 是否必填
device_id String URI 设备 ID
unlock_no Integer BODY 解锁方式编号
unlock_type String BODY 解锁方式类型:fingerprint、password、card、face

请求示例

{
    "device_id":"vdev2332211",
    "unlock_no":2,
    "unlock_type":"fingerprint",
}

返回示例

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

移除解锁方式劫持功能

支持的门锁类型

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

接口地址

doorLock.removeHijack

请求参数

参数名 类型 参数类型 说明 是否必填
device_id String URI 设备 ID
unlock_no Integer BODY 解锁方式编号
unlock_type String BODY 解锁方式类型:fingerprint、password、card、face

请求示例

{
    "device_id":"vdev2332211",
    "unlock_sn":2,
    "unlock_type":"unlock_fingerprint",
}

返回示例

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

蓝牙门锁专有功能

近程免密开门

支持的门锁类型

类型 支持
门锁类型 蓝牙门锁

接口地址

acton:   doorLock.unlockInstruction

请求参数

参数名 类型 参数类型 说明 是否必填
device_id String URI 设备 ID
bluetooth_sn Integer BODY 蓝牙通信时防重放 sn (接入蓝牙 SDK 后,为蓝牙实例里的_ble_sn)
device_random String BODY 门锁设备随机数 (doorLock.getIssuedConfig 接口获取到的随机数)

请求示例

{
  "action": "doorLock.unlockInstruction",
  "params": {
    "device_id": "vdevo15345926009****",
    "bluetooth_sn": 123,
    "device_random": "123"
  }
}

返回参数

参数名 类型 说明
code Integer 错误响应码,成功时为空(详情参考错误码)
success Boolean 是否成功:
  • true:成功
  • false:失败
t Long 响应时间
msg String 请求失败的信息,成功为空
result Object 开门指令信息

result 说明

参数名 类型 说明
instruction String 开门指令
next_sn Integer 下一个蓝牙通信时防重放 sn

请求成功返回示例

{
  "result": {
    "next_sn": 123,
    "instruction": "9wxxoLM"
  },
  "success": true,
  "t": 1592899848757
}

请求失败返回示例

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

蓝牙近场开门数据组装

说明

doorLock.unlockInstruction 接口的升级,可替换 doorLock.unlockInstruction 接口。

接口地址

acton:   doorLock.bleOpenInstruction

请求参数

参数名 类型 参数类型 说明 是否必填
device_id String URI 设备 ID
bluetooth_sn Integer BODY 蓝牙通信时防重放 sn (接入蓝牙 sdk 后,为蓝牙实例里的_ble_sn)
device_random String BODY 门锁设备随机数 (doorLock.getIssuedConfig 接口获取到的随机数)
open Boolean BODY 开门还是关门。true: 开门,false: 关门
bluetooth_major_version Integer BODY 蓝牙协议的大版本。比如 "3.x"则该值=3, "4.x"则该值=4。 不传则默认是 3

请求示例

{
  "action": "doorLock.bleOpenInstruction",
  "params": {
    "device_id":"6cae1drr3kpl****",
      "bluetooth_sn":7,
      "device_random":"760a57c866b113f63ef702bb2e914ad4"  ,
      "open":true,
      "bluetooth_major_version":3
    }
}

返回参数

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

result 说明

参数名 类型 说明
instruction String 蓝牙开门指令 (16 进制的,拿到之后下发给设备)
next_sn Integer 下一个蓝牙通信时防重放 sn

请求成功返回示例

{
  "result": {
    "next_sn": 123,
    "instruction":"0472426c51476e714b336a333462764b6a635518a38ae29bf3fdc9f60261c15bf725cbb171921b7c129e6adf4e7dee390bf0dc17dca7c51f44eae4d51d1bd102ea",
  },
  "success": true,
  "t": 1592899848757
}

请求失败返回示例

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

查询密钥 authKey

接口地址

action :device.pairingAuthKey

请求参数

参数名 类型 说明 是否必填
home_id Long 家庭 ID
uuid String 设备唯一标识
uid String 用户 ID

请求示例

{
  "action": "device.pairingAuthKey",
  "params": {
    "home_id": "25761214",
    "uuid": "c3ac4b0d54af****",
    "uid": "ay16009313532665****"
  }
}

返回参数

参数名 类型 说明
code Integer 错误响应码,成功时为空(详情⻅见错误码)
success Boolean 是否成功:
  • true:成功
  • false:失败
t Long 响应时间
msg String 请求失败的信息,成功为空
result Object 配网密钥

result 说明

参数名 类型 说明
encrypted_auth_key String 密钥 1
random String 登入密钥

请求成功返回示例

{
  "result": {
    "encrypted_auth_key": "456789056789",
    "rondom": "6783456789"
  },
  "success": true,
  "t": 1603679935012
}

请求失败返回示例

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

查询系统时间

接口地址

action :timer.currentTime

请求参数

请求示例

{
  "action": "timer.currentTime",
  "params": {}
}

返回参数

参数名 类型 说明
code Integer 错误响应码,成功时为空(详情⻅见错误码)
success Boolean 是否成功:
  • true:成功
  • false:失败
t Long 响应时间
msg String 请求失败的信息,成功为空
result Long 服务器时间戳

请求成功返回示例

{
  "result": true,
  "success": 1607087405739,
  "t": 1603679935012
}

请求失败返回示例

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

查询校验开锁前需要同步的配置

支持的门锁类型

类型 支持
门锁类型 蓝牙门锁

接口地址

action : doorLock.getIssuedConfig

请求参数

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

请求示例

{
  "action": "doorLock.getIssuedConfig",
  "params": {
    "device_id": "vdevo16036791579****"
  }
}

返回参数

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

result 说明

参数名 类型 说明
lock_random Object 门锁随机数, 根据 distribute 判断是否需要下发
lock_record Object 查询离线开门记录,一定要下发,DP ID 为 0 则走透传

lock_random/lock_record 说明

参数名 类型 说明
distribute Boolean 是否需要下发
wake_up_ins Object 16 进制字符串
dp_id Integer 下发的 DP 编号
ins String 查询记录的 DP 数据 (16 进制)
dev_unlock_id String 门锁随机数

请求成功返回示例

{
  "result": {
    "lock_random": {
      "dev_unlock_id": "0005",
      "dp_id": 70,
      "wake_up_ins": "ffff0005000000000000000000ffff3532373737393530",
      "distributed": true,
      "ins": "3532373737393530"
    },
    "lock_record": {
      "dpId": 56,
      "distributed": true,
      "ins": "ffff0005000000000000000000ffff3532373737393530"
    }
  },
  "success": true,
  "t": 1608518987114
}

请求失败返回示例

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

T0 时间的下发

t0 时间是离线密码算法中的一个参数,取得是设备的激活时间. 所以可以使用 device.getListByIds 接口获取

接口地址

action : device.getListByIds

请求参数

参数名 类型 说明 是否必填
device_ids String 设备 ID 列表 (多个的话用逗号隔开)

请求示例

{
	"action": "device.getListByIds",
	"params": {
		"device_ids": "vdevo153490924188132"
	}
}

返回参数

一个数组,数组中的每个元素的字段如下

参数名 类型 说明 备注
id String 设备编号
uid String 用户 ID
local_key String 密钥
category String 产品类别
product_id String 产品 ID
sub Boolean 是否是子设备(true:是,false:不是)
uuid String 设备唯一标识
owner_id String 设备拥有者 ID
online Boolean 设备在线状态
name String 设备名称
ip String ip 地址
time_zone String 时区
create_time Long 设备初次配网时间
update_time Long 设备状态更新时间
active_time Long 设备上次配网时间 此值为需要下发的 T0 时间
status List 设备功能状态

返回示例

[
    {
         "sub":false,
         "create_time":1618287272,
         "local_key":"ede14e228a7d7c85",
         "owner_id":"34720161",
         "biz_type":329944,
         "ip":"219.133.159.132",
         "icon":"smart/icon/bay1599447209665AVnx/c7ec976e16d2b309e61ffb65442a65bb.jpg",
         "lon":"114.03490357760252",
         "time_zone":"+08:00",
         "product_name":"恒温调奶器",
         "uuid":"378fb516c5b8****",
         "active_time":1622000424,
         "uid":"ay1620733026105K****",
         "update_time":1622000425,
         "product_id":"bemvogz0z6wl****",
         "name":"恒温调奶器",
         "online":true,
         "id":"6c59dc783afa9dfc27****",
         "category":"cn",
         "lat":"22.64856786505044",
         "status":[
                 {
                      "code":"DIY_FUNC1",
                      "value":"23 蜂蜜水 83 蜂蜜水 P3 蜂蜜水 A3 蜂蜜水"
                },
                {
                      "code":"fun1_water",
                      "value":241
                }
         ]
    }
]

获取到数据之后,取 active_time 字段,然后将其装换为 16 进制进行下发。

成员数据同步

支持的门锁类型

类型 支持
门锁类型 蓝牙门锁

描述

由于每次设备上线+刷新用户列表,都会进行数据同步。当用户频繁刷新用户列表页时,会频繁的发起数据同步,可能前一个同步还没有结束,下一个又开始了。这个无论对于设备本地/云端服务,都是一个浪费,所以该接口的目的是控制同步的频率,只有面板调用该接口返回的数据的 distributed=true 时,才下发同步指令给设备。
云端会控制频率,5s 内只能做一次同步。

接口地址

action : doorLock.getSyncableOpmodeTypes

请求参数

参数名 类型 参数类型 说明 是否必填 备注
device_id String URI 设备 ID
target_standard_dp_codes String String 标准 dpCodes, 多个的话以逗号分割 这里应该给记录型的 dpCode. 比如希望查看指纹+密码,那么该值为: “unlock_fingerprint,unlock_password”

请求示例

{
	"device_id":"6cdbaew2mm6v****",
  	"target_standard_dp_codes":"unlock_fingerprint",
}

返回参数

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

result 说明

参数名 类型 说明
dp_id Integer 下发的 dpId
distributed Boolean 是否需要下发
ins String 指令 (16 进制, 直接下发即可)

返回示例

{
    "dp_id":54,
    "distributed":true,
    "ins":"03"
}

Zigbee 门锁专有功能

门锁含密开门

支持的门锁类型

类型 支持
门锁类型 Zigbee 门锁

接口地址

action : doorLock.openDoor

请求参数

参数名 类型 参数类型 说明 是否必填
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

返回信息

参数名 类型 说明
code Integer 响应码(详情参考错误码章节)
success Boolean 是否成功:
  • true:成功
  • false:失败
msg String 请求失败的信息,成功为空
result Boolean 返回结果

返回示例

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

Wi-Fi 门锁专有功能

门锁远程开门请求拒绝

支持的门锁类型

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

接口地址

doorLock.cancelPasswordFreeOpen

请求参数

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

请求示例

{
  "action": "doorLock.cancelPasswordFreeOpen",
  "params": {
    "device_id": "vdevo16036791579****",
    "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 门锁

接口地址

doorLock.getMediaUrl

请求参数

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

请求示例

{
  	"device_id":"vdev2332211",
	"file_type":1
}

返回参数

字段名称 类型 描述
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"
}

用户相关

获取用户信息

接口地址

doorLock.getUser

请求参数

参数名 类型 说明 是否必填
device_id String 设备 ID
user_id String 用户 ID。如果获取当前登录用户的信息,传 0

请求示例

{
    "device_id":"00000561bcddc235****",
    "user_id":"0"
}

返回参数

字段名称 类型 描述
user_id string 成员编号
lock_user_id Integer 锁用户 ID
avatar_url string 头像地址
user_type Integer 用户类型。50. 家庭拥有者; 10. 管理员 ; 20.普通成员; 30. 没有名字的成员
nick_name string 用户昵称
user_contact string 联系方式

示例

{
    "user_id":"0000000001",
    "lock_user_id":2,
    "nick_name":"123",
    "avatar_url":"smart/user_res/ay1519797357494tgSIE/scale/avatar_1524487255195.jpg",
    "user_type":10,
    "user_contact":"86-15278010021"
}

查询用户的解锁方式详情

接口地址

doorLock.listUserOpmodes

请求参数

参数名 类型 说明 是否必填
device_id String 设备 ID
user_id String 用户编号
target_unlock_standard_dp_codes String 目标的解锁方式的标准 dpCode,多个以逗号隔开(可为空)
unlock_fingerprint: 指纹
unlock_password: 密码
unlock_card: 门卡
page_no int 页编号
page_size int 每页个数

请求示例

{
    "action":"doorLock.listUserOpmodes",
    "params":{
        "device_id":"vdevo16036791579****",
        "user_id":"1212****",
   "target_unlock_standard_dp_codes":
          "unlock_fingerprint,unlock_password,unlock_card",
        "page_no":1,
        "page_size":100
    }
}

返回参数

参数名 类型 说明
code Integer 错误响应码,成功时为空(详情⻅见错误码)
success Boolean 是否成功:
  • true:成功
  • false:失败
t Long 响应时间
msg String 请求失败的信息,成功为空
result JSON 分页数据

result 参数结构

参数名 类型 说明
has_more bool 是否还有更多数据
true: 是
false: 否
records json_array 记录数据

records 参数结构

参数名 类型 说明
user_name String 用户名称
user_id String 用户云端编号
user_type String 用户类型
0:未知人员类型
10:管理员
20:普通家人
30:标记成员
lock_user_id String 用户在门锁上的编号
unlock_name String 解锁方式名称
dp_code String 类型
unlock_fingerprint: 指纹
unlock_password: 密码
unlock_card: 门卡
unlock_sn int 解锁方式在门锁上的编号
unlock_attr int 解锁方式属性
0: 无任何属性
1: 劫持
photo_unlock int 是否开启解锁抓拍
0. 不开启
1. 开启

请求成功返回示例

{
    "result":{
        "total":1,
        "records":[
              {
                  "dp_code":"unlock_password",
                  "unlock_attr":0,
                  "unlock_name":"lin",
                  "user_name":"小明",
                  "user_id":"2887****",
                  "unlock_sn":3,
                  "uid":"ay1562298621752U****",
                  "unlock_id":"12-3",
                  "lock_user_id":2,
                  "user_type":20,
                  "photo_unlock": false
              }
        ],
        "has_more":false,
        "total_pages":0
    },
    "success":true,
    "t":1624204036171
}

请求失败返回示例

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

查询成员列表

接口地址

doorLock.listUsers

请求参数

参数名 类型 说明 是否必填 备注
device_id String 设备 ID
target_standard_dp_codes String 标准 dpCodes,多个的话以逗号分割(若为空则不会给出用户的解锁方式信息) 这里应该给记录型的 dpCode. 比如希望查看指纹+密码,那么改值为: “unlock_fingerprint,unlock_password”
page_no Integer 当前页数(从 1 开始计数)
page_size Integer 每页数据量

请求示例

{
	"device_id":"tuya384dfed85348****",
  	"target_standard_dp_codes":"unlock_fingerprint,unlock_password",
  	"page_no":1,
  	"page_size": 10
}

返回参数

参数名 类型 说明
code Integer 错误响应码,成功时为空(详情⻅见错误码)
success Boolean 是否成功:
  • true:成功
  • false:失败
t Long 响应时间
msg String 请求失败的信息,成功为空
result JSON 分页数据

result 参数结构

参数名 类型 说明
user_id String 用户 ID
lock_user_id Integer 锁具用户 ID. 云端需要保证该值不为 0
user_contact String 联系方式
nick_name String 昵称
avatar_url String 头像地址
user_type Integer 成员类型>50. 家庭拥有者; 10. 管理员 ; 20.普通成员; 30. 没有名字的成员
back_home_notify_attr Integer 家人到家提醒是否设置. 0-否; 1-是
unlock_detail List 成员拥有的解锁方式列表
effective_flag Integer 是否有效的标签。0- 无效,1- 有效,2- 未生效 (由于时间未到)
time_schedule_info JSON 用户时效信息

unlock_detail 说明

字段名称 类型 描述
dp_code String dp_code
open Boolean 是否打开
count Integer 当前解锁方式的数量, 该值= unlockList.size()
unlock_list List 解锁方式列表

unlock_list 说明

字段名称 类型 描述
dp_code String 解锁方式的标准 dpCode
unlock_sn Integer 解锁方式编号
unlock_name String 名称
unlock_attr Integer 解锁方式属性. 1: 特殊,0: 非特殊
allocate_flag Integer 是否是从未分配的解锁方式分配给用户的。1-是, 0-否

time_schedule_info 说明

字段名称 类型 描述
permanent Boolean 是否永久
effective_time Long 生效时间
expired_time Long 失效时间
operate String 操作(ADD/MODIFY/DELETE). 目前只有 MODIFY
delivery_status String 硬件对操作的反馈(ONGOING/SUCCESS/FAILED)
schedule_details JSON 周期性信息

schedule_details 说明

字段名称 类型 描述
all_day Boolean 是否全天
effective_time Long 生效时间
invalid_time Long 失效时间
working_day Integer workingDay 的格式说明: 一周的时间打标。bit0 ~ bit6 分别代表周日~周六; 1 表示有效, 0 表示无效; 最后一位以 0 表示。比如周一/周二/周五的表示为: 00100110 = 38, 最终 workingDay=38

返回示例

[
    {
        "user_id":"125674",
      	"uid":"ay15355889716302****",
        "lock_user_id":2,
        "user_contact":"",
        "nick_name":"test",
        "avatar_url":"",
        "user_type":20,
        "back_home_notify_attr":1,
        "unlock_detail":[
            {
                "dp_code":"unlock_password",
                "open":true,
                "count":1,
                "unlock_list":[
                    {
                        "dp_code":"unlock_password",
                        "unlock_sn":3,
                        "unlock_name":"指纹 3",
                        "unlock_attr":1,
                      	"allocate_flag":1
                    }
                ]
            }
        ],
        "effective_flag":1,
        "time_schedule_info":{
            "permanent":true
        }
    }
]