提供一组锁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，由设备上报获得）
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" : "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，由设备上报获得）
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" : "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 否 存在绑定关系的钥匙列表
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" : "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 否 虚拟用户列表
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" : "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 否 用户的属性值
attrList列表结构
参数 类型 必填 描述
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 否 事件记录列表
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" : "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
}