Tuya.com
简体中文
English
注册
登录开发者平台
简体中文
English
注册
登录开发者平台
智慧商业
search
根据文档目录筛选
智慧商业酒店门锁

酒店门锁

更新时间：2025-05-30 01:56:03下载pdf

密码加密流程

酒店门锁

API列表

请求方式 API 说明
POST /v1.0/devices/{device_id}/door-lock/password-ticket 获取密码加密的临时秘钥
POST /v1.0/devices/{device_id}/door-lock/temp-password 创建临时密码（支持周期性密码）
GET /v1.0/devices/{device_id}/door-lock/temp-password/{password_id} 获取临时密码信息
GET /v1.0/devices/{device_id}/door-lock/temp-passwords 获取临时密码列表
PUT /v1.0/devices/{device_id}/door-lock/temp- passwords/{password_id}/modify-password 修改临时密码
DELETE /v1.0/devices/{device_id}/door-lock/temp-passwords/{password_id} 删除临时密码
POST /v1.0/devices/{device_id}/door-lock/temp-passwords/rest-password 清空临时密码
POST /v1.0/devices/{device_id}/door-lock/password-free/open-door 门锁免密开门
POST /v1.0/devices/{device_id}/door-lock/advanced-password 设置高级密码
GET /v1.0/devices/{device_id}/door-lock/advanced-password 查询高级密码
GET /v1.0/devices/{device_id}/door-lock/open-logs 查询开门记录
GET /v1.0/devices/{device_id}/door-lock/alarm-logs 查询门锁告警记录

创建密码加密的临时密钥

接口描述

支持WiFi/Zigbee/Bluetooth门锁

接口地址

POST /v1.0/devices/{device_id}/door-lock/password-ticket

请求参数

参数名 类型 参数类型 说明 是否必需
device_id String URI 设备唯一标识 是

响应参数

参数名 类型 说明
code Integer 响应码（详情见错误码章节），成功时为空
success Boolean 是否成功：（true：成功，false：失败）
msg String 请求失败的信息，成功时为空
t Long 返回时间戳，13位
result Object 返回结果

result参数说明

参数名 类型 说明
ticket_id String 临时密钥唯一标识
ticket_key String 临时密钥Key(需要根据云开发者accessKey通过AES解密后方可使用)
expire_time Long 有效时间，单位：s

请求示例

POST /v1.0/devices/vdevo1534******/door-lock/password-ticket

返回成功示例

{ 
  "result": { 
    "expire_time": 360, 
    "ticket_id": "9w*******", 
    "ticket_key": "901CC35A67DA3429C389622******3EAE1CE333" 
  }, 
  "success": true, 
  "t": 1592899848757 
}

返回失败示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false,
  "t":1561378856383
}

创建临时密码

接口描述

支持WiFi/Zigbee/Bluetooth门锁

接口地址

POST /v1.0/devices/{device_id}/door-lock/temp-password

请求参数

参数名 类型 参数类型 说明 是否必需
device_id String URI 设备唯一标识 是
name String BODY 临时密码名称 是
password String BODY WiFi锁密码原文长度为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: 有效范围时间内一直有效		 是
time_zone String BODY 时区，需要周期性功能，则填入此项 否
schedule_list Array BODY 周期性功能设置参数列表 否

schedule_list参数说明

参数名 类型 参数类型 说明 是否必需
effective_time Long BODY 当天开始时间，单位分钟 是
invalid_time Long BODY 当天过期时间，单位分钟 是
working_day Integer BODY 星期用一个字节来表示，bit0bit6分别代表周日周六 是

响应参数

参数名 类型 说明
code Integer 响应码（详情见错误码章节），成功时为空
success Boolean 是否成功：（true：成功，false：失败）
msg String 请求失败的信息，成功时为空
t Long 返回时间戳，13位
result Object 返回结果

result参数说明

参数名 类型 说明
id Long 临时密码唯一标识

请求示例

POST /v1.0/devices/vdevo1534******/door-lock/temp-password

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

返回成功示例

{ 
  "result": { 
    "id": 124367346 
  }, 
  "success": true, 
  "t": 1592899848757 
}

返回失败示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false,
  "t":1561378856383
}

获取临时密码信息

接口描述

支持WiFi/Zigbee/Bluetooth门锁

接口地址

GET /v1.0/devices/{device_id}/door-lock/temp-password/{password_id}

请求参数

参数名 类型 参数类型 说明 是否必需
device_id String URI 设备唯一标识 是
password_id Long URI 密码唯一标识 是

响应参数

参数名 类型 说明
code Integer 响应码（详情见错误码章节），成功时为空
success Boolean 是否成功：（true：成功，false：失败）
msg String 请求失败的信息，成功时为空
t Long 返回时间戳，13位
result Object 返回结果

result参数说明

参数名 类型 说明
password_id String 临时密码唯一标识
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 Arrays 周期性功能参数列表

result.schedule_list参数说明

参数名 类型 说明
effective_time Long 当天开始时间，单位分钟
invalid_time Long 当天过期时间，单位分钟
working_day Integer 星期用一个字节来表示，bit0bit6分别代表周日周六

result.phase参数说明

门锁类型 密码状态说明
zigbee 1：待创建 2：正常 3：已冻结 4：已删除 5：创建失败
wifi 0：已删除 1：待下发 2：已下发 3：待删除
bluetooth 0：已删除 1：待下发 2：已下发 3：待删除 7：下发失败

请求示例

GET /v1.0/devices/vdevo153******/door-lock/temp-password/******

返回成功示例

{ 
  "success": true, 
  "t": 1542626129429, 
  "result": { 
    "password_id": 1001, 
    "effective_time": 1530841779,
    "invalid_time": 1530881779,
    "name": "Tenant A's password",
    "phase": 1,
    "phone": "123547127362", 
    "time_zone":"Asia/Shanghai", 
    "delivery_status": 1 
  } 
}

返回失败示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false,
  "t":1561378856383
}

获取临时密码列表

接口描述

支持WiFi/Zigbee/Bluetooth门锁

接口地址

GET /v1.0/devices/{device_id}/door-lock/temp-passwords

请求参数

参数名 类型 参数类型 说明 是否必需
device_id String URI 设备唯一标识 是
valid Boolean URL 是否有效
true: 有效
false: 无效		 否

响应参数

参数名 类型 说明
code Integer 响应码（详情见错误码章节），成功时为空
success Boolean 是否成功：（true：成功，false：失败）
msg String 请求失败的信息，成功时为空
t Long 返回时间戳，13位
result Array 临时密码列表

result参数说明

参数名 类型 说明
password_id String 临时密码唯一标识
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 Array 周期性功能参数列表

result.schedule_list参数说明

参数名 类型 说明
effective_time Long 当天开始时间，单位分钟
invalid_time Long 当天过期时间，单位分钟
working_day Integer 星期用一个字节来表示，bit0bit6分别代表周日周六

result.phase参数说明

门锁类型 密码状态说明
zigbee 1：待创建 2：正常 3：已冻结 4：已删除 5：创建失败
wifi 0：已删除 1：待下发 2：已下发 3：待删除
bluetooth 0：已删除 1：待下发 2：已下发 3：待删除 7：下发失败

请求示例

GET /v1.0/devices/vdevo153******/door-lock/temp-passwords

响应成功示例

{ 
  "success": true, 
  "t": 1542626129429, 
  "result": [
    { 
      "password_id": 1001, 
      "effective_time": 1530841779,
      "invalid_time": 1530881779,
      "name": "Tenant A's password",
      "phase": 1,
      "phone": "123547127362", 
      "time_zone":"Asia/Shanghai", 
      "delivery_status": 1 
    } 
  ]
}

返回失败示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false,
  "t":1561378856383
}

修改临时密码

接口描述

支持WiFi/Zigbee门锁(Bluetooth门锁不支持密码修改)

接口地址

PUT /v1.0/devices/{device_id}/door-lock/temp-passwords/{password_id}/modify-password

请求参数

参数名 类型 参数类型 说明 是否必需
device_id String URI 设备唯一标识 是
password_id Long URI 密码唯一标识 是
name String BODY 临时密码名称 是
password String BODY WiFi锁密码原文长度为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: 有效范围时间内一直有效		 是
time_zone String BODY 时区，需要周期性功能，则填入此项 否
schedule_list Array BODY 周期性功能设置参数列表 否

schedule_list参数说明

参数名 类型 参数类型 说明 是否必需
effective_time Long BODY 当天开始时间，单位分钟 是
invalid_time Long BODY 当天过期时间，单位分钟 是
working_day Integer BODY 星期用一个字节来表示，bit0bit6分别代表周日周六 是

响应参数

参数名 类型 说明
code Integer 响应码（详情见错误码章节），成功时为空
success Boolean 是否成功：（true：成功，false：失败）
msg String 请求失败的信息，成功时为空
t Long 返回时间戳，13位
result Boolean 操作结果

请求示例

PUT /v1.0/devices/vdevo1534592******/door-lock/temp-passwords/123******/modify-password

{
  "password": "956FAD7******09C68E168B77", 
  "effective_time": 1579156726, 
  "invalid_time": 1579243126, 
  "name": "test", 
  "phone": "1881234****", 
  "time_zone": "", 
  "schedule_list":[
    { 
       "effective_time": 720, 
       "invalid_time": 1080, 
       "working_day": 0 
    }
  ] 
}

响应成功示例

{ 
  "result": true, 
  "success": true, 
  "t": 1592899848757 
}

返回失败示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false,
  "t":1561378856383
}

删除临时密码

接口描述

支持WiFi/Zigbee/Bluetooth门锁

接口地址

DELETE /v1.0/devices/{device_id}/door-lock/temp-passwords/{password_id}

请求参数

参数名 类型 参数类型 说明 是否必需
device_id String URI 设备唯一标识 是
password_id Long URI 密码唯一标识 是

响应参数

参数名 类型 说明
code Integer 响应码（详情见错误码章节），成功时为空
success Boolean 是否成功：（true：成功，false：失败）
msg String 请求失败的信息，成功时为空
t Long 返回时间戳，13位
result Object 返回结果

请求示例

DELETE /v1.0/devices/vdevo1534******/door-lock/temp-passwords/123******

响应成功示例

{ 
  "result": true, 
  "success": true, 
  "t": 1592899848757 
}

返回失败示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false,
  "t":1561378856383
}

清空临时密码

接口描述

清空临时密码

接口地址

POST /v1.0/devices/{device_id}/door-lock/temp-passwords/rest-password

请求参数

参数名 类型 参数类型 说明 是否必需
device_id String URI 设备唯一标识 是
参数名 类型 说明
code Integer 响应码（详情见错误码章节），成功时为空
success Boolean 是否成功：（true：成功，false：失败）
msg String 请求失败的信息，成功时为空
t Long 返回时间戳，13位
result Boolean 操作结果

请求示例

POST /v1.0/devices/6cc2f3b***/door-lock/temp-passwords/rest-password

响应成功示例

{ 
  "result": true, 
  "success": true, 
  "t": 1592899848757 
}

返回失败示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false,
  "t":1561378856383
}

门锁免密开门

接口描述

支持WiFi/Zigbee/Bluetooth门锁

接口地址

POST /v1.0/devices/{device_id}/door-lock/password-free/open-door

请求参数

参数名 类型 参数类型 说明 是否必需
device_id String URI 设备 ID 是
ticket_id String BODY 临时秘钥ID 是

响应参数

参数名 类型 说明
code Integer 响应码（详情见错误码章节），成功时为空
success Boolean 是否成功：（true：成功，false：失败）
msg String 请求失败的信息，成功时为空
t Long 返回时间戳，13位
result Boolean 操作结果

请求示例

POST /v1.0/devices/6cc2f******/door-lock/password-free/open-door

{ 
  "ticket_id":"******"
}

响应成功示例

{ 
  "result": true, 
  "success": true, 
  "t": 1592899848757 
}

返回失败示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false,
  "t":1561378856383
}

设置高级密码

接口描述

设置高级密码

接口地址

POST /v1.0/devices/{device_id}/door-lock/advanced-password

请求参数

参数名 类型 参数类型 说明 是否必需
device_id String URI 设备唯一标识 是
password String BODY 密码原文长度为6密码，传输使用加密算法使用AES，模式:ECB pkcs7padding数据块128位，秘钥为通过接口获取的临时ticket_key使用开发者accessKey AES解密后的原始秘钥 是
password_type String BODY 密钥加密类型: ticket. 是
ticket_id String BODY 临时秘钥ID 是
advanced_type String BODY 高级密码类型:
admin: 管理员密码
emergency: 应急密码		 是

响应参数

参数名 类型 说明
code Integer 响应码（详情见错误码章节），成功时为空
success Boolean 是否成功：（true：成功，false：失败）
msg String 请求失败的信息，成功时为空
t Long 返回时间戳，13位
result Boolean 操作结果

请求示例

POST /v1.0/devices/vdevo15345******/door-lock/advanced-password

{ 
  "password_type":"ticket", 
  "password":"7A8F9B6******7C1D66", 
  "ticket_id":"fJeqZ***", 
  "advanced_type":"emergency" 
}

响应成功示例

{ 
  "result": true, 
  "success": true, 
  "t": 1592899848757 
}

返回失败示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false,
  "t":1561378856383
}

查询高级密码

接口描述

查询高级密码

接口地址

GET /v1.0/devices/{device_id}/door-lock/advanced-password

请求参数

参数名 类型 参数类型 说明 是否必需
device_id String URI 设备唯一标识 是
advanced_type String BODY 高级密码类型:
admin: 管理员密码
emergency: 应急密码		 是

响应参数

参数名 类型 说明
code Integer 响应码（详情见错误码章节），成功时为空
success Boolean 是否成功：（true：成功，false：失败）
msg String 请求失败的信息，成功时为空
t Long 返回时间戳，13位
result Object 返回结果

result参数说明

参数名 类型 说明
advanced_type String 高级密码类型:
admin: 管理员密码
emergency: 应急密码
phase Integer 密码配置状态:
1:配置中
2:配置成功
3:配置失败

请求示例

GET /v1.0/devices/vdevo153******/door-lock/advanced-password?advanced_type=admin

响应成功示例

{ 
  "success": true, 
  "t": 1542626129429, 
  "result": { 
    "advanced_type":"admin", 
    "phase":2 
  } 
}

返回失败示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false,
  "t":1561378856383
}

查询开门记录

接口描述

支持WiFi/Zigbee门锁

接口地址

GET /v1.0/devices/{device_id}/door-lock/open-logs

请求参数

参数名 类型 参数类型 说明 是否必需
device_id String URI 设备唯一标识 是
page_no Integer URL 页码 是
page_size Integer URL 页条数 是
start_time Long URL 开始时间 是
end_time Long URL 结束时间 是

响应参数

参数名 类型 说明
code Integer 响应码（详情见错误码章节），成功时为空
success Boolean 是否成功：（true：成功，false：失败）
msg String 请求失败的信息，成功时为空
t Long 返回时间戳，13位
result Object 返回结果

result参数说明

参数名 类型 说明
total Integer 记录数量
logs Array 开门记录列表

result.logs参数说明

参数名 类型 说明
status Array 门锁状态列表
update_time Long 状态变更时间

result.logs.status参数说明

参数名 类型 说明
code String 状态码
value Object 状态值

result.logs.status.code参数说明

状态码 说明
unlock_finger 指纹解锁，门锁本地分配的编号
unlock_password 密码解锁，门锁本地分配的编号
unlock_temporary 临时密码解锁，值为密码唯一标识(password_id)
unlock_dynamic 动态密码解锁，值为密码唯一标识(password_id)
unlock_card 卡片解锁，门锁本地分配的编号
unlock_face 人脸解锁，门锁本地分配的编号
unlock_key 机械钥匙解锁，门锁本地分配的编号
unlock_identity_card 身份证解锁，门锁本地分配的编号
unlock_emergency 应急密码解锁，门锁本地分配的编号

请求示例

GET /v1.0/devices/vdevo153459******/door-lock/open-logs?page_no=1&page_size=20&start_time=1543213146&end_time=1543213546

响应成功示例

{ 
  "success":true, 
  "t":1542626129429, 
  "result":{ 
    "total":1, 
    "logs":[ 
      { 
        "status":{ 
        "code":"unlock_finger", 
        "value":"123456" 
      },
      "update_time":1543297979 
      } 
    ] 
  } 
}

返回失败示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false,
  "t":1561378856383
}

获取门锁告警记录

接口描述

支持WiFi/Zigbee/Bluetooth门锁

接口地址

GET /v1.0/devices/{device_id}/door-lock/alarm-logs

请求参数

参数名 类型 参数类型 说明 是否必需
device_id String URI 设备唯一标识 是
page_no Integer URL 页码 是
page_size Integer URL 页条数 是
dp_codes String URL 告警标准功能code，默认查询通用告警 否

响应参数

参数名 类型 说明
code Integer 响应码（详情见错误码章节），成功时为空
success Boolean 是否成功：（true：成功，false：失败）
msg String 请求失败的信息，成功时为空
t Long 返回时间戳，13位
result Object 返回结果

result参数说明

参数名 类型 说明
total Integer Total number of records.
records Array List of unlocking alarm history.

result.logs参数说明

参数名 类型 说明
status Array 门锁告警状态列表
update_time Long 状态变更时间
nick_name String 用户名

result.logs.status参数说明

参数名 类型 说明
code String 状态码
value Object 状态值

result.logs.status.code参数说明

状态码 说明
unlock_finger 指纹解锁，门锁本地分配的编号
unlock_password 密码解锁，门锁本地分配的编号
unlock_temporary 临时密码解锁，值为密码唯一标识(password_id)
unlock_dynamic 动态密码解锁，值为密码唯一标识(password_id)
unlock_card 卡片解锁，门锁本地分配的编号
unlock_face 人脸解锁，门锁本地分配的编号
unlock_key 机械钥匙解锁，门锁本地分配的编号
unlock_identity_card 身份证解锁，门锁本地分配的编号
unlock_emergency 应急密码解锁，门锁本地分配的编号

请求示例

GET /v1.0/devices/vdevo1534592******/door-lock/alarm-logs?page_no=1&page_size=20&dp_codes=hijack

响应成功示例

{ 
  "success":true, 
  "t":1542626129429, 
  "result":{ 
    "total":1, 
    "records":[ 
      { 
        "status":{ 
        "code":"hijack", 
        "value":"unlock_fingerprint-02" 
      },
      "update_time":1543297979  
      } 
    ] 
  } 
}

返回失败示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false,
  "t":1561378856383
}

错误码

以下为该接口常见的业务异常，更多的异常错误，请参见全局错误码。

错误码 说明
500 系统错误
上一篇欢迎语管理
下一篇IoT 微信小程序 | H5 SDK
语言
简体中文
简体中文
English
400-881-8611
7×24小时服务热线
市场合作
marketing@tuya.com
业务合作
service@tuya.com
媒体联络
pr@tuya.com
关注“涂鸦智能”
涂鸦服务尽在掌握
关注“全球智能商业”
第一时间获取物联网资讯
联系我们加入我们TuyaExpoApp 商城TuyaGoTuyaGo服务商查询
法律声明隐私协议加州隐私权利声明服务条款廉正合规安全应急响应中心
©2014-2025 杭州涂鸦信息技术有限公司 版权
浙ICP备2022000504号
浙B2-20210233号
浙公网安备33010602004238号
简体中文
简体中文
English