提供一组锁SaaS专用的接口,方便对锁相关产品进行快速开发。
钥匙与虚拟用户绑定
定义描述
path | 版本 | 描述 | 是否需要用户身份的鉴权 |
---|---|---|---|
/lock/key/user/bind | 1.0.0 | 钥匙与虚拟用户进行绑定,只允许锁设备绑定的管理员进行操作 | 是,客户端SDK需启用身份的鉴权,进行身份认证 |
请求参数
参数 | 类型 | 必填 | 描述 |
---|---|---|---|
virtualUserId | String | 是 | 虚拟用户ID,与账户下创建的虚拟用户对应 |
lockUserId | String | 是 | 钥匙ID(对应锁端的锁用户ID,由设备上报获得) |
lockUserType | Integer | 是 | 钥匙类型(1-指纹,2-密码,3-卡,4-钥匙) |
lockUserPermType | Integer | 是 | 钥匙权限(1-普通用户;2-管理员用户;3-胁迫用户 ) |
iotId | String | 是 | 设备ID |
返回参数
无
示例
- 请求示例
{ "id": "1509086454180", "version": "1.0", "request": { "apiVer": "1.0.0", "iotToken": "token" }, "params": { "virtualUserId" : "10B6336xxxx28F58AA5A18", "lockUserId" : "10", "lockUserType" : 1, "lockUserPermType" : 2, "iotId" : "ChFrkX2xxxx010803d10" } }
- 正常返回示例
{ "code": 200, "message": "success", "data": null }
钥匙与虚拟用户解绑
定义描述
path | 版本 | 描述 | 是否需要用户身份的鉴权 |
---|---|---|---|
/lock/key/user/unbind | 1.0.0 | 钥匙与虚拟用户进行解除绑定,只允许锁设备绑定的管理员进行操作 | 是,客户端SDK需启用身份的鉴权,进行身份认证 |
请求参数
参数 | 类型 | 必填 | 描述 |
---|---|---|---|
virtualUserId | String | 是 | 虚拟用户ID,与账户下创建的虚拟用户对应 |
lockUserId | String | 是 | 钥匙ID(对应锁端的锁用户ID,由设备上报获得) |
lockUserType | Integer | 是 | 钥匙类型(1-指纹,2-密码,3-卡,4-钥匙) |
iotId | String | 是 | 设备ID |
返回参数
无
示例
- 请求示例
{ "id": "1509086454180", "version": "1.0", "request": { "apiVer": "1.0.0", "iotToken": "token" }, "params": { "virtualUserId" : "10B63xxxx428F58AA5A18", "lockUserId" : "10", "lockUserType" : 1, "iotId" : "ChFrkX2xxxxH0010803d10" } }
- 正常返回示例
{ "code": 200, "message": "success", "data": null }
查询虚拟用户和某批钥匙的绑定关系
定义描述
path | 版本 | 描述 | 是否需要用户身份的鉴权 |
---|---|---|---|
/lock/key/users/bindinfo/get | 1.0.0 | 查询虚拟用户和某个设备下某批钥匙的绑定关系,如果存在绑定关系则返回相应的关系信息。限定锁设备绑定的管理员查询方有效 | 是,客户端SDK需启用身份的鉴权,进行身份认证 |
请求参数
参数 | 类型 | 必填 | 描述 |
---|---|---|---|
virtualUserId | String | 是 | 虚拟用户ID,与账户下创建的虚拟用户对应 |
originalLockUsers | List | 是 | 钥匙ID列表(对应锁端的锁用户ID,由设备上报获得) |
参数 | 类型 | 描述 |
---|---|---|
iotId | String | 设备ID |
lockUserId | String | 钥匙ID(对应锁端的锁用户ID,由设备上报获得) |
lockUserType | Integer | 钥匙类型(1-指纹,2-密码,3-卡,4-钥匙) |
返回参数
参数 | 类型 | 必有 | 描述 |
---|---|---|---|
lockUsers | List | 否 | 存在绑定关系的钥匙列表 |
参数 | 类型 | 描述 |
---|---|---|
iotId | String | 设备ID |
lockUserId | String | 钥匙ID(对应锁端的锁用户ID,由设备上报获得) |
lockUserType | Integer | 钥匙类型(1-指纹,2-密码,3-卡,4-钥匙) |
lockUserPermType | Integer | 钥匙权限(1-普通用户;2-管理员用户;3-胁迫用户 ) |
keyNickName | String | 钥匙昵称(通过setKeyNickName设置过昵称后,在此处便可以获得昵称,否则为空) |
userId | String | 虚拟用户ID |
identityId | String | 账户身份ID |
tenantId | String | 租户ID |
isolationId | String | 资源隔离ID |
示例
- 请求示例
{ "id": "1509086454180", "version": "1.0", "request": { "apiVer": "1.0.0", "iotToken": "token" }, "params": { "virtualUserId" : "10B63xxxx428F58AA5A18", "originalLockUsers" : [ { "iotId" : "ChFrkX2Cxxxx010803d10", "lockUserId": "10", "lockUserType" : 1 }, { "iotId" : "ChFrkX2Cxxxx0803d10", "lockUserId": "12", "lockUserType" : 2 } ] } }
- 正常返回示例
{ "code": 200, "message": "success", "data": [ { "iotId" : "ChFrkX2Cxxxx0010803d10", "lockUserId": "10", "lockUserType" : 1, "lockUserPermType": 2, "keyNickName":"keyNickNameTest", "userId": "10B6336xxxxD428F58AA5A18", "identityId": "5070xxxxe6970731e258b2250", "tenantId": "C9A56xxxxAE9875CDE5F01B3", "isolationId": "a10xxxxrF8" } ] }
查询虚拟用户和某个钥匙的绑定关系
定义描述
path | 版本 | 描述 | 是否需要用户身份的鉴权 |
---|---|---|---|
/lock/key/user/bindinfo/get | 1.0.0 | 查询虚拟用户和某个钥匙的绑定关系,如果存在绑定关系则返回相应的关系信息,不存在则返回空。限定锁设备绑定的管理员查询方有效 | 是,客户端SDK需启用身份的鉴权,进行身份认证 |
请求参数
参数 | 类型 | 必填 | 描述 |
---|---|---|---|
virtualUserId | String | 是 | 虚拟用户ID,与账户下创建的虚拟用户对应 |
lockUserId | String | 是 | 钥匙ID(对应锁端的锁用户ID,由设备上报获得) |
lockUserType | Integer | 是 | 钥匙类型(1-指纹,2-密码,3-卡,4-钥匙) |
iotId | String | 是 | 设备ID |
返回参数
参数 | 类型 | 必有 | 描述 |
---|---|---|---|
iotId | String | 是 | 设备ID |
lockUserId | String | 是 | 钥匙ID(对应锁端的锁用户ID,由设备上报获得) |
lockUserType | Integer | 是 | 钥匙类型(1-指纹,2-密码,3-卡,4-钥匙) |
lockUserPermType | Integer | 是 | 钥匙权限(1-普通用户;2-管理员用户;3-胁迫用户 ) |
keyNickName | String | 否 | 钥匙昵称(通过setKeyNickName设置过昵称后,在此处便可以获得昵称,否则为空) |
userId | String | 是 | 虚拟用户ID |
identityId | String | 是 | 账户身份ID |
tenantId | String | 是 | 租户ID |
isolationId | String | 是 | 资源隔离ID |
示例
- 请求示例
{ "id": "1509086454180", "version": "1.0", "request": { "apiVer": "1.0.0", "iotToken": "token" }, "params": { "virtualUserId" : "10B63xxxxD428F58AA5A18", "iotId" : "ChFrkX2CExxxx10803d10", "lockUserId": "10", "lockUserType" : 1 } }
- 正常返回示例
{ "code": 200, "message": "success", "data": { "iotId" : "ChFrkX2Cxxxx10803d10", "lockUserId": "10", "lockUserType" : 1, "lockUserPermType": 2, "keyNickName": "keyNickNameTest", "userId": "10B6336Exxxx28F58AA5A18", "identityId": "5070opbxxxx3520731e258b2250", "tenantId": "C9A562xxxxCDE5F01B3", "isolationId": "a10xxxxLYnTrF8" } }
过滤还未绑定虚拟用户的钥匙信息
定义描述
path | 版本 | 描述 | 是否需要用户身份的鉴权 |
---|---|---|---|
/lock/key/user/unbind/filter | 1.0.0 | 过滤出当前还未绑定的钥匙列表。限定锁设备绑定的管理员查询方有效 | 是,客户端SDK需启用身份的鉴权,进行身份认证 |
/lock/key/user/unbind/filter | 1.0.2 | 调整入参,要求iotId、lockUserId等参数必填 | 是,客户端SDK需启用身份的鉴权,进行身份认证 |
请求参数
参数 | 类型 | 必填 | 描述 |
---|---|---|---|
originalLockUsers | List | 是 | 钥匙ID列表(对应锁端的锁用户ID,由设备上报获得) |
参数 | 类型 | 描述 |
---|---|---|
iotId | String | 设备ID |
lockUserId | String | 钥匙ID(对应锁端的锁用户ID,由设备上报获得) |
lockUserType | Integer | 钥匙类型(1-指纹,2-密码,3-卡,4-钥匙) |
lockUserPermType | Integer | 钥匙权限(1-普通用户;2-管理员用户;3-胁迫用户 ) |
keyNickName | String | 钥匙昵称(通过setKeyNickName设置过昵称后,在此处便可以获得昵称,否则为空) |
返回参数
参数 | 类型 | 必有 | 描述 |
---|---|---|---|
originalLockUsers | List | 否 | 过滤后的钥匙ID列表(对应锁端的锁用户ID) |
参数 | 类型 | 描述 |
---|---|---|
iotId | String | 设备ID |
lockUserId | String | 钥匙ID(对应锁端的锁用户ID,由设备上报获得) |
lockUserType | Integer | 钥匙类型(1-指纹,2-密码,3-卡,4-钥匙) |
lockUserPermType | Integer | 钥匙权限(1-普通用户;2-管理员用户;3-胁迫用户 ) |
示例
- 请求示例
{ "id": "1509086454180", "version": "1.0", "request": { "apiVer": "1.0.0", "iotToken": "token" }, "params": { "originalLockUsers": [ { "iotId" : "ChFrkXxxxx010803d10", "lockUserId": "10", "lockUserType" : 1, "lockUserPermType": 2 }, { "iotId" : "ChFrkX2xxxx010803d10", "lockUserId": "12", "lockUserType" : 2, "lockUserPermType": 1 } ] } }
- 正常返回示例
{ "code": 200, "message": "success", "data": [ { "iotId" : "ChFrkXxxxx010803d10", "lockUserId": "10", "lockUserType" : 1, "lockUserPermType": 2 } ] }
查询虚拟用户绑定的钥匙列表
定义描述
path | 版本 | 描述 | 是否需要用户身份的鉴权 |
---|---|---|---|
/lock/key/user/bindlist/get | 1.0.0 | 查询虚拟用户下绑定的钥匙列表 | 是,客户端SDK需启用身份的鉴权,进行身份认证 |
请求参数
参数 | 类型 | 必填 | 描述 |
---|---|---|---|
virtualUserId | String | 是 | 虚拟用户ID,与账户下创建的虚拟用户对应 |
lockUserType | Integer | 否 | 钥匙类型(1-指纹,2-密码,3-卡,4-钥匙)不填表示查询全部类型 |
lockUserPermType | Integer | 否 | 钥匙权限(1-普通用户;2-管理员用户;3-胁迫用户 )不填表示查询全部类型 |
返回参数
参数 | 类型 | 必有 | 描述 |
---|---|---|---|
lockUsers | List | 否 | 存在绑定关系的钥匙列表 |
参数 | 类型 | 描述 |
---|---|---|
iotId | String | 设备ID |
lockUserId | String | 钥匙ID(对应锁端的锁用户ID) |
lockUserType | Integer | 钥匙类型(1-指纹,2-密码,3-卡,4-钥匙) |
lockUserPermType | Integer | 钥匙权限(1-普通用户; 2-管理员用户; 3-胁迫用户 ) |
keyNickName | String | 钥匙昵称(通过setKeyNickName设置过昵称后,在此处便可以获得昵称,否则为空) |
userId | String | 虚拟用户ID |
identityId | String | 账户身份ID |
tenantId | String | 租户ID |
isolationId | String | 资源隔离ID |
示例
- 请求示例
{ "id": "1509086454180", "version": "1.0", "request": { "apiVer": "1.0.0", "iotToken": "token" }, "params": { "virtualUserId" : "10B633xxxx28F58AA5A18", "lockUserType" : 1, "lockUserPermType": 2 } }
- 正常返回示例
{ "code": 200, "message": "success", "data": [ { "iotId" : "ChFrkX2xxxx10803d10", "lockUserId": "10", "lockUserType" : 1, "lockUserPermType": 2, "userId": "10B6336xxxxF58AA5A18", "identityId": "5070opxxxx1e258b2250", "tenantId": "C9A56xxxxDE5F01B3", "isolationId": "a1xxxxTrF8" }, { "iotId" : "ChFrkX2xxxx0803d10", "lockUserId": "12", "lockUserType" : 2, "lockUserPermType": 1, "userId": "109C2DxxxxD8FA1673", "identityId": "5070opxxxx731e258b2250", "tenantId": "C9A5xxxxCDE5F01B3", "isolationId": "a1xxxxTrF8" } ] }
查询设备下的虚拟用户列表
定义描述
path | 版本 | 描述 | 是否需要用户身份的鉴权 |
---|---|---|---|
/lock/dev/virtual/user/get | 1.0.0 | 查询某个设备下绑定了钥匙的虚拟用户列表信息 | 是,客户端SDK需启用身份的鉴权,进行身份认证 |
请求参数
参数 | 类型 | 必填 | 描述 |
---|---|---|---|
iotId | String | 是 | 设备ID |
返回参数
参数 | 类型 | 必有 | 描述 |
---|---|---|---|
userInfos | List | 否 | 虚拟用户列表 |
参数 | 类型 | 必填 | 描述 |
---|---|---|---|
userId | String | 是 | 虚拟用户ID |
attrList | List | 是 | 用户的属性值(参看虚拟用户对用户属性的定义) |
参数 | 类型 | 必填 | 描述 |
---|---|---|---|
attrKey | String | 是 | 属性Key |
attrValue | String | 是 | 属性值 |
示例
- 请求示例
{ "id": "1509086454180", "version": "1.0", "request": { "apiVer": "1.0.0", "iotToken": "token" }, "params": { "iotId" : "ChFrkX2xxxx10803d10" } }
- 正常返回示例
{ "code": 200, "message": "success", "data": [ { "userId" : "10B6336xxxx28F58AA5A18", "attrList": [ { "attrKey": "name", "attrValue": "小明" }, { "attrKey": "birthday", "attrValue": "1985-07-03" } ] }, { "userId" : "109C2D6ED58xxxx7D8FA1673", "attrList": [ { "attrKey": "name", "attrValue": "妈妈" }, { "attrKey": "birthday", "attrValue": "1965-02-15" } ] } ] }
删除设备的钥匙信息
定义描述
path | 版本 | 描述 | 是否需要用户身份的鉴权 |
---|---|---|---|
/lock/key/user/delete | 1.0.0 | 删除指定设备的钥匙信息,如果钥匙已与虚拟用户绑定,那么该操作会优先触发虚拟用户的解绑,不管最终钥匙删除是否成功,均会解绑虚拟用户,只允许锁设备绑定的管理员进行操作 | 是,客户端SDK需启用身份的鉴权,进行身份认证 |
请求参数
参数 | 类型 | 必填 | 描述 |
---|---|---|---|
lockUserId | String | 是 | 钥匙ID(对应锁端的锁用户ID) |
lockUserType | Integer | 是 | 钥匙类型(1-指纹,2-密码,3-卡,4-钥匙) |
iotId | String | 是 | 设备ID |
返回参数
无
示例
- 请求示例
{ "id": "1509086454180", "version": "1.0", "request": { "apiVer": "1.0.0", "iotToken": "token" }, "params": { "lockUserId" : "10", "lockUserType" : 1, "iotId" : "ChFrkX2xxxx803d10" } }
- 正常返回示例
{ "code": 200, "message": "success", "data": null }
查询钥匙对应的虚拟用户信息
定义描述
path | 版本 | 描述 | 是否需要用户身份的鉴权 |
---|---|---|---|
/lock/key/virtual/user/get | 1.0.0 | 查询钥匙对应的虚拟用户信息 | 是,客户端SDK需启用身份的鉴权,进行身份认证 |
请求参数
参数 | 类型 | 必填 | 描述 |
---|---|---|---|
lockUserId | String | 是 | 钥匙ID(对应锁端的锁用户ID) |
lockUserType | Integer | 是 | 钥匙类型(1-指纹,2-密码,3-卡,4-钥匙) |
iotId | String | 是 | 设备ID |
返回参数
参数 | 类型 | 必有 | 描述 |
---|---|---|---|
userId | String | 是 | 虚拟用户ID |
attrList | List | 否 | 用户的属性值 |
参数 | 类型 | 必填 | 描述 |
---|---|---|---|
attrKey | String | 是 | 属性Key |
attrValue | String | 是 | 属性值 |
示例
- 请求示例
{ "id": "1509086454180", "version": "1.0", "request": { "apiVer": "1.0.0", "iotToken": "token" }, "params": { "lockUserId" : "10", "lockUserType" : 1, "iotId" : "ChFrkXxxxx10803d10" } }
- 正常返回示例
{ "code": 200, "message": "success", "data": { "userId" : "10B633xxxx8F58AA5A18", "attrList": [ { "attrKey": "name", "attrValue": "小明" }, { "attrKey": "birthday", "attrValue": "1985-07-03" } ] } }
设置锁设备的昵称
定义描述
path | 版本 | 描述 | 是否需要用户身份的鉴权 |
---|---|---|---|
/lock/nickname/set | 1.0.0 | 设置门锁设备的昵称,设备绑定的用户均可以设置,设置结果将同步所有关联用户 | 是,客户端SDK需启用身份的鉴权,进行身份认证 |
请求参数
参数 | 类型 | 必填 | 描述 |
---|---|---|---|
nickName | String | 是 | 昵称信息 |
iotId | String | 是 | 设备ID |
返回参数
无
示例
- 请求示例
{ "id": "1509086454180", "version": "1.0", "request": { "apiVer": "1.0.0", "iotToken": "token" }, "params": { "nickName" : "大门锁", "iotId" : "ChFrkXxxxx10803d10" } }
- 正常返回示例
{ "code": 200, "message": "success", "data": null }
查询锁的事件记录列表
定义描述
由于数据量巨大,该接口数据的查询依赖于大数据等基础设施能力,所以当前无法提供完全的实时性;当前该接口的数据时延情况如下:
- 90%的数据查询时延<1分钟,即在设备上报数据后1分钟内可以查询到
- 100%的数据查询延迟<2小时,即所有数据均可在2小时内查询到
path | 版本 | 描述 | 是否需要用户身份的鉴权 |
---|---|---|---|
/lock/event/history/query | 1.0.0 | 查询锁设备的事件记录列表 | 是,客户端SDK需启用身份的鉴权,进行身份认证 |
请求参数
参数 | 类型 | 必填 | 描述 |
---|---|---|---|
iotid | String | 是 | 设备ID |
events | List | 否 | 需要查询的设备事件类型列表(对应产品功能定义中事件定义的标识符) |
start | Long | 是 | 查询时间区间的开始时间(毫秒) |
end | Long | 是 | 查询时间区间的结束时间(毫秒) |
lockUserId | String | 否 | 钥匙ID(对应锁端的锁用户ID),与lockUserType同时有值或同时为null时有效,否则直接忽略设置 |
lockUserType | Integer | 否 | 钥匙类型(1-指纹,2-密码,3-卡,4-钥匙),与lockUserId同时有值或同时为null时有效,否则直接忽略设置 |
virtualUserId | String | 否 | 虚拟用户ID,当同时设置了lockUserId、lockUserType和virtualUserId时,将会同时生效,即在虚拟用户绑定的钥匙列表的基础上加上配置的(lockUserId、lockUserType) |
pageNo | Integer | 是 | 当前页号,从1开始的页序号 |
pageSize | Integer | 是 | 页大小,单页的记录数量上限(最大50) |
返回参数
参数 | 类型 | 必有 | 描述 |
---|---|---|---|
pageNo | Integer | 是 | 当前页号 |
pageSize | Integer | 是 | 页大小 |
total | Long | 是 | 记录总数 |
data | List | 否 | 事件记录列表 |
参数 | 类型 | 必填 | 描述 |
---|---|---|---|
iot_id | String | 是 | 设备ID |
event_code | String | 是 | 上报事件的标识符 |
service_date | String | 是 | 服务端记录时间(格式:2018-06-25 17:41:18) |
client_date | String | 是 | 客户端上报时间(格式:2018-06-25 17:41:18) |
KeyID | String | 否 | 钥匙ID(对应锁端的锁用户ID,由设备上报获得),当对应的事件具备该出参时,才包含该字段 |
LockType | Integer | 否 | 钥匙类型(1-指纹,2-密码,3-卡,4-钥匙),当对应的事件具备该出参时,才包含该字段 |
UserLimit | Integer | 否 | 钥匙权限(1-普通用户;2-管理员用户;3-胁迫用户 ),当对应的事件具备该出参时,才包含该字段 |
... | ... | 否 | 其他事件具备的出参信息,以具体的产品功能列表中事件的定义为准 |
示例
- 请求示例
{ "id": "1509086454180", "version": "1.0", "request": { "apiVer": "1.0.0", "iotToken": "token" }, "params": { "iotId" : "ChFrkX2xxxx0803d10", "events" : ["DoorOpenNotification","HijackingAlarm","DoorUnlockedAlarm"] "start" : 1629500044000, "end" : 1629587444000, "virtualUserId":"10Bxxxx28F58AA5A18", "pageNo" : 1, "pageSize" : 50 } }
- 正常返回示例
{ "code": 200, "message": "success", "data": [ { "iot_id" : "ChFrkX2xxxx0803d10", "event_code": "DoorOpenNotification", "service_date" : "2018-06-25 17:41:18", "client_date": "2018-06-25 17:41:18", "KeyID": "10", "LockType": 2 }, { "iot_id" : "ChFrkXxxxx10803d10", "event_code": "HijackingAlarm", "service_date" : "2018-06-25 17:40:18", "client_date": "2018-06-25 17:40:18", "KeyID": "10", "LockType": 2 }, { "iot_id" : "ChFrkXxxxx10803d10", "event_code": "DoorUnlockedAlarm", "service_date" : "2018-06-25 17:38:18", "client_date": "2018-06-25 17:38:18" } ] }
设置钥匙的昵称
定义描述
path | 版本 | 描述 | 是否需要用户身份的鉴权 |
---|---|---|---|
/living/lock/key/nickname/set | 1.0.0 | 设置锁钥匙的别名 | 是,客户端SDK需启用身份的鉴权,进行身份认证 |
请求参数
参数 | 类型 | 必填 | 描述 |
---|---|---|---|
lockUserId | String | 是 | 钥匙id |
lockUserType | Integer | 是 | 钥匙类型(1-指纹,2-密码,3-卡,4-钥匙) |
iotId | String | 是 | 设备id |
nickName | String | 是 | 钥匙别名 |
userId | String | 否 | 淘宝账号ID信息 |
userType | String | 否 | 账号类型(淘宝-TAOBAO) |
origin | String | 否 | 标示来源(目前只支持TmallGenie) |
返回参数
无
示例
- 请求示例
{ "id": "1509086454180", "version": "1.0", "request": { "apiVer": "1.0.0", "iotToken": "token" }, "params": { "lockUserId" : "10", "lockUserType" : 1, "iotId" : "ChFrkX2xxxx0803d10", "nickName":"nickNameTest", } }
- 正常返回示例
{ "code": 200, "message": "success", "data": null }