锁的服务

更新时间：2019-06-06 15:43:34

锁的服务

提供一组锁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
}

错误码

错误码 错误信息 来源 描述
28530 lock user has been bound to other virtual user. 业务 钥匙已经和其他虚拟用户绑定

钥匙与虚拟用户解绑

定义描述

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需启用身份的鉴权

请求参数

参数 类型 必填 描述
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
}

错误码

错误码 错误信息 来源 描述
28504 device is offline. 业务 设备不在线

查询钥匙对应的虚拟用户信息

定义描述

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

错误码

错误码 错误信息 来源 描述
28601 user device not bind. 业务 用户设备没有绑定
28527 user not bind with lock. 业务 钥匙还未和虚拟用户绑定

设置锁设备的昵称

定义描述

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
}

错误码

错误码 错误信息 来源 描述
28601 user device not bind. 业务 用户设备没有绑定

查询锁的事件记录列表

定义描述

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
}

错误码

请参考公共错误码

results matching ""

    No results matching ""