Remote Unlock API

Remote Unlocking

Get the remote unlocking methods supported by a lock

Applicable lock types

• Zigbee lock
• Bluetooth lock

API endpoint

GET /v1.0/devices/{device_id}/door-lock/remote-unlocks

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes

Sample request

GET /v1.0/devices/vdevo153459260090544/door-lock/remote-unlocks

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The information about a specified unlocking command.

result

Parameter	Type	Description
remote_unlock_type	String	The unlocking methods. Valid values: remoteUnlockWithoutPwd: Unlock a door without a password. remoteUnlockWithPwd: Unlock a door with a password.
open	Boolean	Indicates whether a feature is enabled.

Sample response on success

{
    "result": {
        "remote_unlock_type": "remoteUnlockWithPwd",
        "open": true
    },
    "success": true,
    "t": 1592899848757
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Set a switch for a remote unlocking method

Applicable lock types

• Wi-Fi lock
• Zigbee lock
• Bluetooth lock

API endpoint

POST /v1.0/devices/{device_id}/door-lock/remote-unlock/config

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
remote_unlock_type	String	BODY	The unlocking methods. Valid values: remoteUnlockWithoutPwd: Unlock a door without a password. remoteUnlockWithPwd: Unlock a door with a password.	Yes
open	Boolean	BODY	Indicates whether a feature is enabled.	Yes

Sample request

POST /v1.0/devices/vdevo153459260090544/door-lock/remote-unlock/config

{
    "remote_unlock_type": "remoteUnlockWithPwd",
    "open": true
}

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	Indicates whether the operation is successful.

Sample response on success

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

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Unlock with a password

Applicable lock types

• Zigbee lock

API endpoint

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

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
password	String	Body	The length of the original password is six digits. The password is encrypted by using the AES-128 algorithm with ECB mode and PKCS7Padding. To get the original key, decrypt the temporary key ticket_key with AES using the accessKey that is issued by the platform.	Yes
password_type	String	BODY	The password is encrypted using a ticket.	Yes
ticket_id	String	BODY	The ID of a specified temporary key.	Yes

Sample request

POST /v1.0/devices/6c362ac3c53fbd6f3ewqfa/door-lock/open-door

Response parameter

Parameter	Type	Description
Code	Integer	The response code. For more information, see the error code section.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	The returned result.

Sample response

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

Unlock without password

Applicable lock types

• All-in-one Wi-Fi lock
• All-in-one Zigbee lock
• Zigbee lock for hotel use
• Bluetooth lock
• Keepalive Wi-Fi locks
• Wi-Fi lock with video talk

API endpoint

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

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
ticket_id	String	Body	The ID of a specified temporary key.	Yes

Sample request

POST /v1.0/devices/vdevo153459260090544/door-lock/password-free/open-door

{
    "ticket_id":"xxxxx"
}

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	The returned result.

Sample response on success

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

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Unlock without password (v1.1)

Unlock a specified channel without a password.

Applicable lock types

• Wi-Fi access control devices

API endpoint

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

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
ticket_id	String	Body	The ID of a specified temporary key. You can get the value through POST:/v1.0/devices/{device_id}/door-lock/password-ticket .	Yes
channel_id	Integer	Body	The channel ID.	Yes

Sample request

POST /v1.1/devices/vdevo15345926009****/door-lock/password-free/open-door

{
    "ticket_id":"WHmutLIq",
    "channel_id":1
}

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	The returned result.

Sample response on success

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

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Revoke a password-free unlocking

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock

API endpoint

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

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
type	Integer	BODY	The reason to revoke remote unlocking. Valid values: 1: Reject. 2: Cancel.	Yes

Sample request

PUT /v1.0/devices/vdevo153459260090544/door-lock/password-free/open-door/cancel

{
    "type":1
}

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	Indicates whether the operation is successful.

Sample response on success

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

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Unlock without password

Applicable lock types

• All-in-one Wi-Fi lock
• All-in-one Zigbee lock
• Zigbee lock for hotel use
• Bluetooth lock
• Keepalive Wi-Fi locks
• Wi-Fi lock with video talk

Note: Remote unlocking requires the DP remote_no_dp_key or remote_no_dp_setkey. Only all-in-one Wi-Fi locks support remote unlocking.

API endpoint

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

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
ticket_id	String	Body	The ID of a specified temporary key.	Yes
open	Boolean	Body	The operation. Valid values: true: Open a door. false: Close a door.	No

Sample request

POST /v1.0/smart-lock/devices/vdevo153459260090544/password-free/door-operate

{
    "ticket_id":"xxxxx",
    "open":false
}

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	The returned result.

Sample response on success

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

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Get a temporary key for password encryption

Note: The temporary key is used to request the API of unlocking without a password.

Applicable lock types

• Wi-Fi lock
• Zigbee lock
• Bluetooth lock
• Zigbee lock for hotel use
• Wi-Fi lock with video talk

API endpoint

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

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes

Sample request

POST /v1.0/smart-lock/devices/vdevo15345926009****/password-ticket

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The information about a temporary password.

result

Parameter	Type	Description
ticket_id	String	The ID of a specified temporary key.
ticket_key	String	The temporary key. It can be used after decryption with AES using the accessKey that is issued by the platform.
expire_time	Long	The remaining validity period.

Sample response on success

{
    "result": {
        "expire_time": 360,
        "ticket_id": "9wxxoLM",
        "ticket_key": "901CC35A67DA3429C38E9622xxxxx3EAE1CE333462356D257FD1D3E5C"
    },
    "success": true,
    "t": 1592899848757
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Remote unlocking with photo capturing

• The following figure shows how remote unlocking with photo capturing works.

  

• Remote unlocking with photo capturing in real time

  • When a user attempts to unlock a door, the camera lock captures a photo and uploads it to the cloud.
  • The cloud stores the media data and sends a relative path to the client.
  • The client calls an API to get the full URL of the media.
  • The client gets the encrypted media data and decrypts it.
  • The user gets the media data and determines whether to unlock the door or revoke permissions to unlock without a password. The APIs will be called accordingly.
  • The cloud sends a command to the lock accordingly.

• Remote unlocking with photo capturing in non-real time

  • The client calls an API to get the unlocking or alert media in the last 90 seconds.
  • The client gets the encrypted media data and decrypts it.
  • The user gets the media data and determines whether to unlock the door or revoke permissions to unlock without a password. The APIs will be called accordingly.
  • The cloud sends a command to the lock accordingly.

The media data is encrypted by using the AES algorithm with CBC mode and PKCS5Padding.

4	16	44	Video content
Placeholder	iv	Placeholder	Video content

The demo shows how decryption works.

package xxxxxxx;

import java.io.File;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.security.InvalidAlgorithmParameterException;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.security.SecureRandom;
import java.util.Random;

import javax.crypto.Cipher;
import javax.crypto.CipherInputStream;
import javax.crypto.CipherOutputStream;
import javax.crypto.NoSuchPaddingException;
import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;

public class EncryptUtils {

    private static final String DEFAULT_ALGORITHM = "AES";
    private static final String DEFAULT_FULL_ALGORITHM = "AES/CBC/PKCS5Padding";

    // Encryption
    public static File encryptFile(String key, File originFile, String destPath) {
        FileInputStream in = null;
        FileOutputStream out = null;
        File destFile = null;
        try {
            destFile = new File(destPath);
            if (originFile.exists() && originFile.isFile()) {
                if (!destFile.getParentFile().exists()) {
                    destFile.getParentFile().mkdirs();
                }
                destFile.createNewFile();
                in = new FileInputStream(originFile);
                out = new FileOutputStream(destFile, true);
                byte[] iv = getIv();
                Cipher cipher = initAESCipher(iv, key, Cipher.ENCRYPT_MODE);
                CipherInputStream cipherInputStream = new CipherInputStream(in, cipher);
                byte[] cache = new byte[1024];
                int nRead;
                out.write(new byte[4]);
                out.write(iv);
                out.write(new byte[4]);
                out.write(new byte[40]);
                out.flush();
                while ((nRead = cipherInputStream.read(cache)) != -1) {
                    out.write(cache, 0, nRead);
                    out.flush();
                }
                cipherInputStream.close();
            }
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            try {
                if (out != null) {
                    out.close();
                }
                if (in != null) {
                    in.close();
                }
            } catch (IOException e) {
                e.printStackTrace();
            }
        }
        return destFile;
    }

    // Decryption
    public static File decryptFile(String key, InputStream in, File destFile) {
        FileOutputStream out = null;
        try {
            if (!destFile.getParentFile().exists()) {
                destFile.getParentFile().mkdirs();
            }
            destFile.createNewFile();
            out = new FileOutputStream(destFile);
 
            byte[] iv = new byte[16];
            in.skip(4);
            int read = in.read(iv);
            if (read != 16) {
                throw new IOException("iv length error");
            }
            in.skip(44);
            Cipher cipher = initAESCipher(iv, key, Cipher.DECRYPT_MODE);
            CipherOutputStream cipherOutputStream = new CipherOutputStream(out, cipher);
            byte[] buffer = new byte[1024];
            int r;
            while ((r = in.read(buffer)) >= 0) {
                cipherOutputStream.write(buffer, 0, r);
            }
            cipherOutputStream.close();
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            try {
                if (in != null) {
                    in.close();
                }
            } catch (IOException e) {
                e.printStackTrace();
            }
            try {
                if (out != null) {
                    out.close();
                }
            } catch (IOException e) {
                e.printStackTrace();
            }
        }
        return destFile;
    }
 
    private static Cipher initAESCipher(byte[] iv, String sKey, int cipherMode) {
        try {
            IvParameterSpec zeroIv = new IvParameterSpec(iv);
            SecretKeySpec key = new SecretKeySpec(sKey.getBytes(), DEFAULT_ALGORITHM);
            Cipher cipher = Cipher.getInstance(DEFAULT_FULL_ALGORITHM);
            cipher.init(cipherMode, key, zeroIv);
            return cipher;
        } catch (NoSuchAlgorithmException e) {
            e.printStackTrace();
        } catch (NoSuchPaddingException e) {
            e.printStackTrace();
        } catch (InvalidKeyException e) {
            e.printStackTrace();
        } catch (InvalidAlgorithmParameterException e) {
            e.printStackTrace();
        }
        return null;
    }
 
    public static byte[] getIv() {
        StringBuilder uid = new StringBuilder();
        // Generate a 16-digit strong random number.
        Random rd = new SecureRandom();
        for (int i = 0; i < 16; i++) {
            // Generate a 3-digit random number between zero and two.
            int type = rd.nextInt(3);
            switch (type) {
                case 0:
                    // Generate a random number between zero and nine.
                    uid.append(rd.nextInt(10));
                    break;
                case 1:
                    // ASCII between 65 to 90 are randomly capitalized.
                    uid.append((char) (rd.nextInt(25) + 65));
                    break;
                case 2:
                    // ASCII between 97 to 122 are randomly lowercased.
                    uid.append((char) (rd.nextInt(25) + 97));
                    break;
                default:
                    break;
            }
        }
        return uid.toString().getBytes();
    }

}

Get cover image of last remote unlocking or alert

Applicable lock types

• Wi-Fi lock
• Zigbee lock for hotel use
• Bluetooth lock

API endpoint

GET /v1.0/devices/{device_id}/door-lock/latest/media/url

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
file_type	Integer	URL	The file type. Valid values: 1: cover images related to remote unlocking. 2: cover images related to alerts.	Yes

Sample request

GET /v1.0/devices/6cdb36b2e489885fa57lzm/door-lock/latest/media/url?file_type=1

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.

result

Parameter	Type	Description
file_url	String	The full URL of a specified cover image.
file_key	String	The key to decrypt a specified file.
bucket	String	The full URL of a specified cover image.
file_path	String	The relative path of a specified file.

Sample response on success

{
    "result": {
        "bucket": "ty-cn-storage60-1254153901",
        "file_key": "u8kstrtjm7qun83q",
        "file_path": "/3039e1-30532026.jpg",
        "file_url": "https://ty-cn-storage60-1254153901.cos.tuyacn.com6"
    },
    "success": true,
    "t": 1614147303662
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Get a list of albums

Applicable lock types

• Wi-Fi lock with video talk

API endpoint

GET /v1.0/smart-lock/devices/{device_id}/albums-media

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes

Sample request

GET /v1.0/smart-lock/devices/vdevo153459260090544/albums-media

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.

result

Parameter	Type	Description
eventTypes	array[int]	The types of cover images and videos in a specified album.
albumList	List	A list of albums.
orderCode	Integer	The plan used for the current album query. Valid values: doorlock_cloud_storage_7day: unlimited cloud storage for 7 days. doorlock_cloud_storage_30day: unlimited cloud storage for 30 days. cloud_free_storage_3day: free cloud storage for 3 days.

albumList

Parameter	Type	Description
eventType	int	The file type.
fileUrl	String	The URL of a specified cover image.
fileKey	String	The secret key of a specified cover image.
mediaPath	String	The URL of a specified video file.
mediaKey	String	The secret key of a specified video file.
mediaBucket	String	The repository where the video file is located.
uploadTime	long	The reporting time in seconds.

Description of eventType

Type value	Type	Description
0	int	Anti-pry alert
1	int	Remote unlocking request
2	int	Fingerprint attempt failed
3	int	Password attempt failed
4	int	Card attempt failed
5	int	Face recognition failed
6	int	Palm print recognition failed
7	int	Finger vein recognition failed
8	int	Unlock with fingerprint
9	int	Unlock with password
10	int	Unlock with card
11	int	Unlock with face recognition
12	int	Unlock with palm print
13	int	Unlock with finger vein
14	int	Unlock with temporary password
15	int	Unlock with dynamic password
16	int	Remote unlocking
17	int	Report unlocking with temporary password
18	int	Report doorbell request
19	int	Duress alarm
20	int	Low battery alert
21	int	Mechanical key attempt
22	int	High temperature alert
23	int	Doorbell ringing and remote unlocking
24	int	Loitering alert
25	int	Lock tampering
26	int	Unlock with special fingerprint
27	int	Unlocking in arm mode
28	int	Unlock with remote control

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result": {
        "album_list": [
      {
        "event_type": 0,
        "file_id": 109167468,
        "file_key": "76679d2579c74eb7",
        "file_url": "https://ty-cn-storage30-1254153901.cos.tuyacn.com/d76182-35779292-dc706aecd4469145/unify/1630051338.jpeg?sign=q-sign-algorithm%3Dsha1%26q-ak%3DAKIDopcCYgw0qRoyV5qfKjvg2pPkqESnb5zI%26q-sign-time%3D1630137629%3B1630141229%26q-key-time%3D1630137629%3B1630141229%26q-header-list%3Dhost%26q-url-param-list%3D%26q-signature%3D29b40dd6ed4281b78321ec978ce1e56361fd7b57",
        "upload_time": 1630051337
      }
    ],
    "event_types": [
      0
    ],
    "order_code": "cloud_free_storage_3day"
    }
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}