智能门锁

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