Remote Unlocking APIs

Last Updated on : 2024-06-26 09:21:43download

Get available remote unlocking methods

Applicable lock types

Zigbee lock
Bluetooth lock

API endpoint

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

Request parameters

Parameter name	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 parameters

Parameter name	Type	Description
code	Integer	The response code. This parameter value is empty if the API call succeeds. For more information, see the error codes.
success	Boolean	Indicates whether the API call is successful. Valid values: `true`: success. `false`: failure.
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 the specified unlocking command.

result

Parameter name	Type	Description
remote_unlock_type	String	The unlocking method. Valid values: `remoteUnlockWithoutPwd`: Unlock a door without a password. `remoteUnlockWithPwd`: Unlock a door with a password.
open	Boolean	Indicates whether the 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 parameters

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

Sample request

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

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

Response parameters

Parameter name	Type	Description
code	Integer	The response code. This parameter value is empty if the API call succeeds. For more information, see the error codes.
success	Boolean	Indicates whether the API call is successful. Valid values: `true`: success. `false`: failure.
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 API call is successful. Valid values:

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 parameters

Parameter name	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 `ticket_key` with AES using the `accessKey` that is generated on the Tuya Developer Platform.	Yes
password_type	String	BODY	The type of password encryption: `ticket`.	Yes
ticket_id	String	BODY	The ID of the specified temporary key.	Yes

Sample request

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

Response parameters

Parameter name	Type	Description
code	Integer	The response code. For more information, see the error codes.
success	Boolean	Indicates whether the API call is successful. Valid values: `true`: success. `false`: failure.
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 a 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 lock
Wi-Fi lock with video talk

API endpoint

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

Request parameters

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

Sample request

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

{
    "ticket_id":"xxxxx"
}

Response parameters

Parameter name	Type	Description
code	Integer	The response code. This parameter value is empty if the API call succeeds. For more information, see the error codes.
success	Boolean	Indicates whether the API call is successful. Valid values: `true`: success. `false`: failure.
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 a password (v1.1)

Unlock the 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 parameters

Parameter name	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
ticket_id	String	Body	The ID of the 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 parameters

Parameter name	Type	Description
code	Integer	The response code. This parameter value is empty if the API call succeeds. For more information, see the error codes.
success	Boolean	Indicates whether the API call is successful. Valid values: `true`: success. `false`: failure.
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 request for password-free unlocking

Applicable lock types

Type	Support
Applicable lock type	Wi-Fi lock

API endpoint

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

Request parameters

Parameter name	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
type	Integer	BODY	The reason for revoking the request for remote unlocking. Valid values: `1`: rejected `2`: canceled	Yes

Sample request

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

{
    "type":1
}

Response parameters

Parameter name	Type	Description
code	Integer	The response code. This parameter value is empty if the API call succeeds. For more information, see the error codes.
success	Boolean	Indicates whether the API call is successful. Valid values: `true`: success. `false`: failure.
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"
}

Lock or unlock without a 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 lock
Wi-Fi lock with video talk

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

API endpoint

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

Request parameters

Parameter name	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
ticket_id	String	Body	The ID of the specified temporary key.	Yes
open	Boolean	Body	The action. Valid values: `true`: Unlock a door. Default value. `false`: Lock a door.	No

Sample request

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

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

Response parameters

Parameter name	Type	Description
code	Integer	The response code. This parameter value is empty if the API call succeeds. For more information, see the error codes.
success	Boolean	Indicates whether the API call is successful. Valid values: `true`: success. `false`: failure.
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

The temporary key is used to request the API of locking or 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 parameters

Parameter name	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 parameters

Parameter name	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 API call is successful. Valid values: `true`: success. `false`: failure.
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 name	Type	Description
ticket_id	String	The ID of the specified temporary key.
ticket_key	String	The temporary key. It can be used after decryption with AES using the `accessKey` that is generated on 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 scenarios
1. When a user attempts to unlock a door, the camera lock captures an image and uploads it to the cloud.
2. The cloud stores the data of images and videos and sends a relative path to the client.
3. The client calls an API to get the full URL of images and videos.
4. The client gets the encrypted data and decrypts it.
5. The user gets the data and determines whether to unlock the door or revoke permissions to unlock without a password. The APIs will be called accordingly.
6. The cloud sends a command to unlock the door or revoke permissions to unlock without a password.
Remote unlocking with photo capturing in non-real time scenarios
1. The client calls an API to get the unlocking or alert images and videos in the last 90 seconds.
2. The client gets the encrypted data and decrypts it.
3. The user gets the data and determines whether to unlock the door or revoke permissions to unlock without a password. The APIs will be called accordingly.
4. The cloud sends a command to unlock the door or revoke permissions to unlock without a password.

The data of images and videos 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 values between 65 to 90 are randomly capitalized.
                    uid.append((char) (rd.nextInt(25) + 65));
                    break;
                case 2:
                    // ASCII values between 97 to 122 are randomly lowercased.
                    uid.append((char) (rd.nextInt(25) + 97));
                    break;
                default:
                    break;
            }
        }
        return uid.toString().getBytes();
    }

}

Get a cover image of the 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 parameters

Parameter name	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
file_type	Integer	URL	The file type. Valid values: `1`: remote unlocking `2`: alert	Yes

Sample request

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

Response parameters

Parameter name	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 API call is successful. Valid values: `true`: success. `false`: failure.
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 name	Type	Description
file_url	String	The full URL of the specified cover image.
file_key	String	The key to decrypt the specified file.
bucket	String	The storage space of the server where the file resides.
file_path	String	The relative path of the 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"
}

Prev DocDoor Lock API List

Next DocPassword Management APIs