Hotel Door Lock

Password Encryption Process

API List

Request method	API	Description
POST	/v1.0/devices/{device_id}/door-lock/password-ticket	Create a temporary key for password encryption.
POST	/v1.0/devices/{device_id}/door-lock/temp-password	Create a temporary password.
GET	/v1.0/devices/{device_id}/door-lock/temp-password/{password_id}	Obtain temporary password details.
GET	/v1.0/devices/{device_id}/door-lock/temp-passwords	Obtain temporary password list.
PUT	/v1.0/devices/{device_id}/door-lock/temp- passwords/{password_id}/modify-password	Modify temporary password.
DELETE	/v1.0/devices/{device_id}/door-lock/temp-passwords/{password_id}	Delete temporary password.
POST	/v1.0/devices/{device_id}/door-lock/temp-passwords/rest-password	Delete all temporary password.
POST	/v1.0/devices/{device_id}/door-lock/password-free/open-door	Open the door without password.
POST	/v1.0/devices/{device_id}/door-lock/advanced-password	Set advanced password.
GET	/v1.0/devices/{device_id}/door-lock/advanced-password	Query advanced password.
GET	/v1.0/devices/{device_id}/door-lock/open-logs	Query unlocking history.
GET	/v1.0/devices/{device_id}/door-lock/alarm-logs	Query unlocking alarm history.

API for Creating a Temporary key for Password Encryption

API Description

You can use this API to create a temporary key for password encryption. This API support WiFi/Zigbee/Bluetooth type door lock.

API Address

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

Request Parameters

Parameter	Type	Position	Description	Mandatory
device_id	String	URI	Unique ID of a device.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Object	Result object.

Parameters in result

Parameter	Type	Description
uid	String	Tuya user ID.
ticket_id	String	Temporary key ID.
ticket_key	String	The temporary key can be used after performing AES decryption based on the cloud developer’s accessKey.
expire_time	Long	Time available, Unit: s.

Request Example

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

Success Response Example

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

Failure Response Example

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

API for Creating a Temporary Password

API Description

You can use this API to create a temporary password. This API support WiFi/Zigbee/Bluetooth type door lock.

API Address

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

Request Parameters

Parameter	Type	Position	Description	Mandatory
device_id	String	URI	Unique ID of a device.	Yes
name	String	BODY	Temporary password name.	Yes
password	String	BODY	The original password length of the Wi-Fi lock is seven, and that of the Zigbee lock and Bluetooth lock is six. AES-128/ECB/PKCS7Padding encryption algorithm is used in secure password transmission. The key is the original ticket_key after AES decryption based on the cloud developer’s accessKey.	Yes
effective_time	Long	BODY	Valid time, 10-bit timestamp in seconds.	Yes
invalid_time	Long	BODY	invalid time, 10-bit timestamp in seconds.	Yes
password_type	String	BODY	Password encryption type: ticket.	Yes
ticket_id	String	BODY	Temporary key ID.	Yes
phone	String	BODY	Mobile number.	No
type	Integer	BODY	Valid type of door lock password. 1: one-time valid. 0: always valid within the valid time.	This field is required for Zigbee locks.
time_zone	String	BODY	Time zone. This field must be filled in if you use the periodic password function.	No
schedule_list	Array	BODY	The parameter list of periodic function.	No

Parameters in schedule_list

Parameter	Type	Position	Description	Mandatory
effective_time	Long	BODY	Valid time on the current day, in minutes.	Yes
invalid_time	Long	BODY	Invalid time on the current day, in minutes.	Yes
working_day	Integer	BODY	A week is represented by one byte. Bit0 to bit6 respectively represent Sunday to Saturday.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Object	Result object.

Parameters in result

Parameter	Type	Description
id	Long	Temporary password number.

Request Example

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

Success Response Example

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

Failure Response Example

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

API for Obtaining Temporary Password Details

API Description

You can use this API to obtain temporary password details. This API support WiFi/Zigbee/Bluetooth type door lock.

API Address

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

Request Parameters

Parameter	Type	Position	Description	Mandatory
device_id	String	URI	Unique ID of a device.	Yes
password_id	Long	URI	Unique ID of a password.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Object	Result object.

Parameters in result

Parameter	Type	Description
password_id	String	Temporary password number.
name	String	Temporary password name.
phase	Integer	Password status.
effective_time	Long	Valid time, 10-bit timestamp.
invalid_time	Long	Invalid time, 10-bit timestamp.
phone	String	Mobile number.
time_zone	String	Time zone.
delivery_status	Integer	Operation status. 1: in configuring 2: configuration succeeded 3: configuration failed 4: repeated password 5: password is full 6: valid time overlap. Return result for Zigbee lock
schedule_list	Array	The parameter list of periodic function.

Parameters in result.schedule_list

Parameter	Type	Description
effective_time	Long	Valid time on the current day, in minutes.
invalid_time	Long	Invalid time on the current day, in minutes.
working_day	Integer	A week is represented by one byte. Bit0 to bit6 respectively represent Sunday to Saturday.

Parameters in result.schedule_list

Door lock type	Description
zigbee	1: to be created. 2: normal. 3: frozen. 4: deleted. 5: creation failed.
wifi	0: deleted. 1: to be sent. 2: sent. 3: to be deleted.
bluetooth	0: deleted. 1: to be sent. 2: sent. 3: to be deleted. 7: sent failed.

Request Example

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

Success Response Example

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

Failure Response Example

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

API for Obtaining Temporary Password List

API Description

You can use this API to obtain temporary password list. This API support WiFi/Zigbee/Bluetooth type door lock.

API Address

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

Request Parameters

Parameter	Type	Position	Description	Mandatory
device_id	String	URI	Unique ID of a device.	Yes
valid	Boolean	URL	is it effective. true: effective false: invalid	No

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Array	List of temporary password list.

Parameters in result

Parameter	Type	Description
password_id	String	Temporary password number.
name	String	Temporary password name.
phase	Integer	Password status.
effective_time	Long	Valid time, 10-bit timestamp.
invalid_time	Long	Invalid time, 10-bit timestamp.
phone	String	Mobile number.
time_zone	String	Time zone.
delivery_status	Integer	Operation status. 1: in configuring 2: configuration succeeded 3: configuration failed 4: repeated password 5: password is full 6: valid time overlap. Return result for Zigbee lock
schedule_list	Array	The parameter list of periodic function.

Parameters in result.schedule_list

Parameter	Type	Description
effective_time	Long	Valid time on the current day, in minutes.
invalid_time	Long	Invalid time on the current day, in minutes.
working_day	Integer	A week is represented by one byte. Bit0 to bit6 respectively represent Sunday to Saturday.

Parameters in result.schedule_list

Door lock type	Description
zigbee	1: to be created. 2: normal. 3: frozen. 4: deleted. 5: creation failed.
wifi	0: deleted. 1: to be sent. 2: sent. 3: to be deleted.
bluetooth	0: deleted. 1: to be sent. 2: sent. 3: to be deleted. 7: sent failed.

Request Example

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

Success Response Example

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

Failure Response Example

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

API for Modifying the Temporary Password

API Description

You can use this API to modify temporary password. This API support WiFi/Zigbee door lock but Bluetooth door lock does not support.

API Address

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

Request Parameters

Parameter	Type	Position	Description	Mandatory
device_id	String	URI	Unique ID of a device.	Yes
password_id	Long	URI	Unique ID of a password.	Yes
name	String	BODY	Temporary password name.	Yes
password	String	BODY	The original password length of the Wi-Fi lock is seven, and that of the Zigbee lock and Bluetooth lock is six. AES-128/ECB/PKCS7Padding encryption algorithm is used in secure password transmission. The key is the original ticket_key after AES decryption based on the cloud developer’s accessKey.	Yes
effective_time	Long	BODY	Valid time, 10-bit timestamp in seconds.	Yes
invalid_time	Long	BODY	invalid time, 10-bit timestamp in seconds.	Yes
password_type	String	BODY	Password encryption type: ticket.	Yes
ticket_id	String	BODY	Temporary key ID.	Yes
phone	String	BODY	Mobile number.	No
type	Integer	BODY	Valid type of door lock password. 1: one-time valid. 0: always valid within the valid time.	This field is required for Zigbee locks.
time_zone	String	BODY	Time zone. This field must be filled in if you use the periodic password function.	No
schedule_list	Array	BODY	The parameter list of periodic function.	No

Parameters in schedule_list

Parameter	Type	Position	Description	Mandatory
effective_time	Long	BODY	Valid time on the current day, in minutes.	Yes
invalid_time	Long	BODY	Invalid time on the current day, in minutes.	Yes
working_day	Integer	BODY	A week is represented by one byte. Bit0 to bit6 respectively represent Sunday to Saturday.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Boolean	Operation result.

Parameters in result

Parameter	Type	Description
id	Long	Temporary password number.

Request Example

PUT /v1.0/devices/vdevo1534592******/door-lock/temp-passwords/123***/modify-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 
    }
  ] 
}

Success Response Example

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

Failure Response Example

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

API for Deleting Temporary Password

API Description

You can use this API to delete temporary password. This API support WiFi/Zigbee/Bluetooth type door lock.

API Address

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

Request Parameters

Parameter	Type	Position	Description	Mandatory
device_id	String	URI	Unique ID of a device.	Yes
password_id	Long	URI	Unique ID of a password.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Boolean	Operation result.

Request Example

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

Success Response Example

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

Failure Response Example

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

API for Deleting All Temporary Password

API Description

You can use this API to delete all temporary password.

API Address

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

Request Parameters

Parameter	Type	Position	Description	Mandatory
device_id	String	URI	Unique ID of a device.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Boolean	Operation result.

Request Example

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

Success Response Example

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

Failure Response Example

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

API for No Password to Open the Door

API Description

You can use this API to open the door without password. This API support WiFi/Zigbee/Bluetooth type door lock.

API Address

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

Request Parameters

Parameter	Type	Position	Description	Mandatory
device_id	String	URI	Unique ID of a device.	Yes
ticket_id	String	BODY	Temporary key ID.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Boolean	Operation result.

Request Example

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

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

Success Response Example

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

Failure Response Example

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

API for Setting Advanced Password

API Description

You can use this API to set advanced password.

API Address

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

Request Parameters

Parameter	Type	Position	Description	Mandatory
device_id	String	URI	Unique ID of a device.	Yes
password	String	BODY	The original length of the password is 6 passwords, the transmission uses the encryption algorithm using AES, the mode: ECB pkcs7padding data block 128 bits, the secret key is the temporary ticket_key obtained through the interface, and the original secret key after decrypting using the developer’s accessKey AES.	Yes
password_type	String	BODY	Password encryption type: ticket.	Yes
ticket_id	String	BODY	Temporary key ID.	Yes
advanced_type	String	BODY	Advanced password types. admin: administrator password emergency: emergency password	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Boolean	Operation result.

Request Example

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

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

Success Response Example

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

Failure Response Example

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

API for Querying Advanced Password

API Description

You can use this API to query advanced password.

API Address

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

Request Parameters

Parameter	Type	Position	Description	Mandatory
device_id	String	URI	Unique ID of a device.	Yes
advanced_type	String	URL	Advanced password types. admin: administrator password emergency: emergency password	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Object	Result object.

Parameters in result

Parameter	Type	Description
advanced_type	String	Advanced password types. admin: administrator password emergency: emergency password
phase	Integer	Password configuration status: 1:configured 2:configured successfully 3:configured failed

Request Example

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

Success Response Example

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

Failure Response Example

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

API for Querying Unlocking History

API Description

You can use this API to query unlocking history. This API support WiFi/Zigbee/Bluetooth type door lock.

API Address

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

Request Parameters

Parameter	Type	Position	Description	Mandatory
device_id	String	URI	Unique ID of a device.	Yes
page_no	Integer	URL	Page number.	Yes
page_size	Integer	URL	Number of records on a page.	Yes
start_time	Long	URL	Start time, 10-bit timestamp in seconds.	Yes
end_time	Long	URL	End time, 10-bit timestamp in seconds.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Object	Result object.

Parameters in result

Parameter	Type	Description
total	Integer	Total number of records.
logs	Array	List of unlocking history.

Parameters in result.logs

Parameter	Type	Description
status	Array	List of Door lock status.
update_time	Long	State change time.

Parameters in result.logs.status

Parameter	Type	Description
code	String	Status code.
value	Object	Status value.

Parameters in result.logs.status.code

Parameter	Description
unlock_finger	Unlock with a fingerprint. The number assigned locally by the lock.
unlock_password	Unlock with a password. The number assigned locally by the lock.
unlock_temporary	Unlock with a temporary password, and the value is password ID.
unlock_dynamic	Unlock with a dynamic password, and the value is password ID.
unlock_card	Unlock with a card. The number assigned locally by the lock.
unlock_face	Unlock with face recognition. The number assigned locally by the lock.
unlock_key	Unlock with a mechanical key. The number assigned locally by the lock.
unlock_identity_card	ID card unlock, the number assigned locally by the door lock.
unlock_emergency	Emergency password unlock, the number assigned locally by the door lock.

Request Example

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

Success Response Example

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

Failure Response Example

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

API for Querying Unlocking Alarm History

API Description

You can use this API to query unlocking alarm history. This API support WiFi/Zigbee/Bluetooth type door lock.

API Address

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

Request Parameters

Parameter	Type	Position	Description	Mandatory
device_id	String	URI	Unique ID of a device.	Yes
page_no	Integer	URL	Page number.	Yes
page_size	Integer	URL	Number of records on a page.	Yes
dp_codes	String	URL	Alarm function standard function code, separated by half-width commas (,), query general alarms by default.	No

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Object	Result object.

Parameters in result

Parameter	Type	Description
total	Integer	Total number of records.
records	Array	List of unlocking alarm history.

Parameters in result.logs

Parameter	Type	Description
status	Array	List of Door lock status.
update_time	Long	State change time.
nick_name	String	Nick name.

Parameters in result.logs.status

Parameter	Type	Description
code	String	Status code.
value	Object	Status value.

Parameters in result.logs.status.code

Parameter	Description
unlock_finger	Unlock with a fingerprint. The number assigned locally by the lock.
unlock_password	Unlock with a password. The number assigned locally by the lock.
unlock_temporary	Unlock with a temporary password, and the value is password ID.
unlock_dynamic	Unlock with a dynamic password, and the value is password ID.
unlock_card	Unlock with a card. The number assigned locally by the lock.
unlock_face	Unlock with face recognition. The number assigned locally by the lock.
unlock_key	Unlock with a mechanical key. The number assigned locally by the lock.
unlock_identity_card	ID card unlock, the number assigned locally by the door lock.
unlock_emergency	Emergency password unlock, the number assigned locally by the door lock.

Request Example

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

Success Response Example

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

Failure Response Example

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

Error Code

The following are common business exceptions for this interface. For more exception errors, see Global Error Codes.

error code	explain
500	system error