提供一组锁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" : "10B6336EFE05374FF99BDD428F58AA5A18",
           "lockUserId" : "10",
           "lockUserType" : 1,
           "lockUserPermType" : 2,
           "iotId" : "ChFrkX2CEx6DO88EHXNH0010803d10"
        }
    }
              
  • 正常返回示例
    {
        "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" : "10B6336EFE05374FF99BDD428F58AA5A18",
           "lockUserId" : "10",
           "lockUserType" : 1,
           "iotId" : "ChFrkX2CEx6DO88EHXNH0010803d10"
        }
    }
              
  • 正常返回示例
    {
        "code": 200,
        "message": "success",
        "data": null
    }
              

查询虚拟用户和某批钥匙的绑定关系

定义描述

path 版本 描述 是否需要用户身份的鉴权
/lock/key/users/bindinfo/get 1.0.0 查询虚拟用户和某个设备下某批钥匙的绑定关系,如果存在绑定关系则返回相应的关系信息。限定锁设备绑定的管理员查询方有效 是,客户端SDK需启用身份的鉴权,进行身份认证

请求参数

参数 类型 必填 描述
virtualUserId String 虚拟用户ID,与账户下创建的虚拟用户对应
originalLockUsers List 钥匙ID列表(对应锁端的锁用户ID,由设备上报获得)
originalLockUsers列表结构
参数 类型 描述
iotId String 设备ID
lockUserId String 钥匙ID(对应锁端的锁用户ID,由设备上报获得)
lockUserType Integer 钥匙类型(1-指纹, 2-密码, 3-卡, 4-钥匙)

返回参数

参数 类型 必有 描述
lockUsers List 存在绑定关系的钥匙列表
lockUsers列表结构
参数 类型 描述
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" : "10B6336EFE05374FF99BDD428F58AA5A18",
           "originalLockUsers" : [
                {
                   "iotId" : "ChFrkX2CEx6DO88EHXNH0010803d10",
                   "lockUserId": "10",
                   "lockUserType" : 1
                },
                {
                   "iotId" : "ChFrkX2CEx6DO88EHXNH0010803d10",
                   "lockUserId": "12",
                   "lockUserType" : 2
                }
            ]
        }
    }
              
  • 正常返回示例
    {
        "code": 200,
        "message": "success",
        "data": [
           {
               "iotId" : "ChFrkX2CEx6DO88EHXNH0010803d10",
               "lockUserId": "10",
               "lockUserType" : 1,
               "lockUserPermType": 2,
               "keyNickName":"keyNickNameTest",
               "userId": "10B6336EFE05374FF99BDD428F58AA5A18",
               "identityId": "5070opb4c20352a76092886e6970731e258b2250",
               "tenantId": "C9A56275D954421FAAE9875CDE5F01B3",
               "isolationId": "a103cg3XCLYnTrF8"
           }
        ]
    }
              

查询虚拟用户和某个钥匙的绑定关系

定义描述

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" : "10B6336EFE05374FF99BDD428F58AA5A18",
           "iotId" : "ChFrkX2CEx6DO88EHXNH0010803d10",
           "lockUserId": "10",
           "lockUserType" : 1
        }
    }
    
              
  • 正常返回示例
    {
        "code": 200,
        "message": "success",
        "data": {
               "iotId" : "ChFrkX2CEx6DO88EHXNH0010803d10",
               "lockUserId": "10",
               "lockUserType" : 1,
               "lockUserPermType": 2,
               "keyNickName": "keyNickNameTest",
               "userId": "10B6336EFE05374FF99BDD428F58AA5A18",
               "identityId": "5070opb4c20352a76092886e6970731e258b2250",
               "tenantId": "C9A56275D954421FAAE9875CDE5F01B3",
               "isolationId": "a103cg3XCLYnTrF8"
           }
    }
              

过滤还未绑定虚拟用户的钥匙信息

定义描述

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,由设备上报获得)
originalLockUsers列表结构
参数 类型 描述
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)
originalLockUsers列表结构
参数 类型 描述
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" : "ChFrkX2CEx6DO88EHXNH0010803d10",
                "lockUserId": "10",
                "lockUserType" : 1,
                "lockUserPermType": 2
              },
     ​         {         
                "iotId" : "ChFrkX2CEx6DO88EHXNH0010803d10",
                "lockUserId": "12",
                "lockUserType" : 2,
                "lockUserPermType": 1
              }
           ]   
        }
    }
    
              
  • 正常返回示例
    {
        "code": 200,
        "message": "success",
        "data": [
          {         
           "iotId" : "ChFrkX2CEx6DO88EHXNH0010803d10",
           "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 存在绑定关系的钥匙列表
lockUsers列表结构
参数 类型 描述
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" : "10B6336EFE05374FF99BDD428F58AA5A18",
           "lockUserType" : 1,
           "lockUserPermType": 2
          }  
    }
              
  • 正常返回示例
    {
        "code": 200,
        "message": "success",
        "data": [
          {
               "iotId" : "ChFrkX2CEx6DO88EHXNH0010803d10",
               "lockUserId": "10",
               "lockUserType" : 1,
               "lockUserPermType": 2,
               "userId": "10B6336EFE05374FF99BDD428F58AA5A18",
               "identityId": "5070opb4c20352a76092886e6970731e258b2250",
               "tenantId": "C9A56275D954421FAAE9875CDE5F01B3",
               "isolationId": "a103cg3XCLYnTrF8"
           },
           {
               "iotId" : "ChFrkX2CEx6DO88EHXNH0010803d10",
               "lockUserId": "12",
               "lockUserType" : 2,
               "lockUserPermType": 1,
               "userId": "109C2D6ED589E54C69A32A38C7D8FA1673",
               "identityId": "5070opb4c20352a76092886e6970731e258b2250",
               "tenantId": "C9A56275D954421FAAE9875CDE5F01B3",
               "isolationId": "a103cg3XCLYnTrF8"
           }
        ]   
    }
              

查询设备下的虚拟用户列表

定义描述

path 版本 描述 是否需要用户身份的鉴权
/lock/dev/virtual/user/get 1.0.0 查询某个设备下绑定了钥匙的虚拟用户列表信息 是,客户端SDK需启用身份的鉴权,进行身份认证

请求参数

参数 类型 必填 描述
iotId String 设备ID

返回参数

参数 类型 必有 描述
userInfos List 虚拟用户列表
userInfos列表结构
参数 类型 必填 描述
userId String 虚拟用户ID
attrList List 用户的属性值(参看虚拟用户对用户属性的定义)
attrList列表结构
参数 类型 必填 描述
attrKey String 属性Key
attrValue String 属性值

示例

  • 请求示例
    {
        "id": "1509086454180",
        "version": "1.0",
        "request": {
            "apiVer": "1.0.0",
        "iotToken": "token"
        },
        "params": {         
           "iotId" : "ChFrkX2CEx6DO88EHXNH0010803d10"
          }  
    }
              
  • 正常返回示例
    {
        "code": 200,
        "message": "success",
        "data": [
          {
               "userId" : "10B6336EFE05374FF99BDD428F58AA5A18",
               "attrList": [
                    {
                        "attrKey": "name",
                        "attrValue": "小明"
                    },
                    {
                        "attrKey": "birthday",
                        "attrValue": "1985-07-03"
                    }
               ]
           },
           {
               "userId" : "109C2D6ED589E54C69A32A38C7D8FA1673",
               "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" : "ChFrkX2CEx6DO88EHXNH0010803d10"
          }  
    }
              
  • 正常返回示例
    {
        "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 用户的属性值
attrList列表结构
参数 类型 必填 描述
attrKey String 属性Key
attrValue String 属性值

示例

  • 请求示例
    {
        "id": "1509086454180",
        "version": "1.0",
        "request": {
            "apiVer": "1.0.0",
        "iotToken": "token"
        },
        "params": { 
           "lockUserId" : "10",
           "lockUserType" : 1,         
           "iotId" : "ChFrkX2CEx6DO88EHXNH0010803d10"
          }  
    }
              
  • 正常返回示例
    {
        "code": 200,
        "message": "success",
        "data": {
                "userId" : "10B6336EFE05374FF99BDD428F58AA5A18",
               "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" : "ChFrkX2CEx6DO88EHXNH0010803d10"
          }  
    }
              
  • 正常返回示例
    {
        "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 事件记录列表
data列表结构
参数 类型 必填 描述
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" : "ChFrkX2CEx6DO88EHXNH0010803d10",
           "events" : ["DoorOpenNotification","HijackingAlarm","DoorUnlockedAlarm"]
           "start" : 1629500044000,
           "end" : 1629587444000,
           "virtualUserId":"10B6336EFE05374FF99BDD428F58AA5A18",
           "pageNo" : 1,
           "pageSize" : 50
        }
    }
    
              
  • 正常返回示例
    {
        "code": 200,
        "message": "success",
        "data": [
           {
               "iot_id" : "ChFrkX2CEx6DO88EHXNH0010803d10",
               "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" : "ChFrkX2CEx6DO88EHXNH0010803d10",
               "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" : "ChFrkX2CEx6DO88EHXNH0010803d10",
               "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" : "ChFrkX2CEx6DO88EHXNH0010803d10",
           "nickName":"nickNameTest",
        }
    }
              
  • 正常返回示例
    {
        "code": 200,
      "message": "success",
        "data": null
    }