Smart Lock

Last Updated on : 2024-06-21 08:48:25download

API list

The parameters in the response of each API request mentioned in this topic must follow the content as described in the following sections. If the returned result is not mentioned, do not make that API request.

Action	Description
doorLock.alarmLogs	Query alert records.
doorLock.listRecords	Query the history of unlocking operations and alerts.
doorLock.operateRecords	Query the operation records.
doorLock.loglatest	Query the latest log entry.
doorLock.getAvailableInstructions	Get mappings between standard `dpCode` and `dpId`.
doorLock.passwordFreeOpen	Unlock a door without a password.
doorLock.openingLogs	Query unlocking records.
doorLock.getDynamicPassword	Query dynamic password
doorLock.passwordTicket	The process of password encryption.
doorLock.passwordTicket	Query a temporary key for password encryption.
doorLock.getTemporaryPassword	Query information about a temporary password.
doorLock.getTemporaryPasswordList	Query a list of temporary passwords.
doorLock.createTemporaryPassword	Create a temporary password.
doorLock.modifyTemporaryPassword	Modify a temporary password.
doorLock.modifyTemporaryPassword	Rename a temporary password.
doorLock.deleteTemporaryPassword	Delete a temporary password.
device.status	Query the latest status of a device.
device.control	Send a command.
doorLock.remoteUnlocks	Query remote unlocking methods supported by a smart lock.
doorLock.remoteUnlockConfig	Set the on/off status for remote unlocking.
doorLock.listUnallocatedOpmodes	Get a list of unlocking methods that are not bound with users.
doorLock.allocateOpmode	Bind an unlocking method with a user.
doorLock.deallocateOpmode	Unbind an unlocking method from a user.
doorLock.createPermissionSharing	Create a link for temporary unlocking.
doorLock.verifyPermissionSharing	Verify a link for temporary unlocking.
doorLock.confirmPermissionSharing	Confirm a link for temporary unlocking.
doorLock.cancelPermissionSharing	Cancel sharing a link for temporary unlocking.
doorLock.setHijack	Enable duress alarms for an unlocking method.
doorLock.removeHijack	Disable duress alarms for an unlocking method.
doorLock.unlockInstruction	Implement remote unlocking without password within a short range.
doorLock.bleOpenInstruction	Assemble data for short-range Bluetooth unlocking.
device.pairingAuthKey	Query the `authKey`.
timer.currentTime	Query system time.
doorLock.getIssuedConfig	Query the configuration to be synched before unlocking verification.
device.getListByIds	Send the `T0` time.
doorLock.getSyncableOpmodeTypes	Sync data of users.
doorLock.openDoor	Unlock a door with password.
doorLock.cancelPasswordFreeOpen	Reject a request for remote unlocking.
doorLock.deleteOfflinePassword	Delete an offline password.
doorLock.getMediaUrl	Get the cover image of the last remote unlocking operation or alert.

API list about user information

Action	Description
doorLock.getUser	Get user information.
doorLock.listUserOpmodes	Query list of unlocking methods for a user.
doorLock.listUsers	Query a list of users.

Generic lock features

Query alert records

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock
Applicable lock type	Zigbee lock
Applicable lock type	Bluetooth lock

API endpoint

action:  doorLock.alarmLogs

Request parameter

Parameter name	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
page_no	Integer	URL	The page number.	Yes
page_size	Integer	URL	The number of entries returned on each page.	Yes
codes	String	URL	The standard data point (DP) identifier that supports alerts. Multiple identifiers are separated with commas (,).	Yes

Sample request

{
  "action": "doorLock.alarmLogs",
  "params": {
    "device_id": "vdevo15345926009 **** ",
    "page_no": "1",
    "page_size": "20",
    "codes": "hijack"
  }
}

Return parameter

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 operation 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.

Description of result

Parameter name	Type	Description
total	Integer	The total number of records.
records	List	The list of alert records.

Description of records

Parameter name	Type	Description
status	List	The list of lock alerts.
update_time	Long	The time when the status is updated.
nick_name	String	The username.

Description of status

Parameter name	Type	Description
code	String	The DP identifier of a specified alert.
value	Object	The status value. The value of a duress alarm is the value of the DP set to trigger a duress event.

Sample response on success

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

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

Query history of unlocking operations and alerts

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock
Applicable lock type	Bluetooth lock

API endpoint

action doorLock.listRecords

Request parameter

Parameter name	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
target_standard_dp_codes	String	QUERY	The standard DP identifier. Multiple values of `dp_code` are separated with commas (,).	Yes
start_time	Long	QUERY	The start time. Set the value to `0` when the time range is not required.	Yes
end_time	Long	QUERY	The end time. Set the value to `0` when the time range is not required.	Yes
page_no	Integer	QUERY	The current page number, starting from `1`.	Yes
page_size	Integer	QUERY	The maximum number of entries returned on each page.	Yes

Sample request

{
  "action": "doorLock.listRecords",
  "params": {
    "device_id":"eb289eyjlyn8 **** ",
    "target_standard_dp_codes":"unlock_fingerprint,unlock_password",
    "start_time":0,
    "end_time":0,
    "page_no":0,
    "page_size":10
  }
}

Return parameter

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 operation 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.

Description of result

Parameter name	Type	Description
record_id	String	The unique identifier of a record.
user_id	String	The user ID.
user_name	String	The username.
unlock_name	String	The name of an unlocking method.
avatar	String	The avatar of the user.
gmt_create	Long	The time when the data was created.
dps	List	An array of key-value pairs. For each element, the key is a standard DP identifier indicated by `dp_code` and the value is the DP value.
status	Integer	The status.
record_type	String	The type of the specified record. Valid values: `alarm`: an alert record. `normal`: a general unlocking record.
media_info_list	JSON array	The photo or video captured during unlocking.
member_bindable_flag	Integer	Indicates whether a locking method can be bound with a user. Valid values: `1`: yes. `0`: No. Maybe the record is already bound with a user.
union_unlock_info	JSON array	The information about combined unlocking methods.
channel_id	String	The channel ID. This parameter applies when a smart lock is used as a hub to control multiple doors, for example, in the case of access control.

Description of media_info_list

Field	Type	Description
file_url	String	The full path of the file.
file_key	String	The encryption key.
file_path	String	The path of the file.
bucket	String	The bucket where a file is stored.

Description of union_unlock_info

Field	Type	Description
user_name	String	The username.
opmode	String	The type of unlocking. This parameter represents an unlocking method indicated by a DP identifier. For example, `unlock_password` represents unlocking with password.
unlock_name	String	The name of the unlocking method.

Sample response on success

{
    "unreadCount":10,
    "total":25,
    "records":[
        {
            "dps":[
                {
                    "unlock_password":"97"
                }
            ],
            "avatar":"https://airtake-public-data.oss-cn-hangzhou.aliyuncs.com/smart/user_res/avatar/scale/user_icon_default.png",
            "user_name":"",
            "unlock_name":"",
            "gmt_create":1579339465000,
            "record_id":"15793300059C669FD0B31E173A6D1E2F550010946 **** ",
            "user_id":"0",
            "status":1,
            "record_type":"normal",
            "member_bindable_flag":0,
            "channel_id":"12",
            "media_info_list":[
                {
                    "file_url":"https://ty-cn-storage30-1254153901.cos.ap-shanghai.myqcloud.com/6cd8d231782a2c3721Qhhl/1588216645118_1588215615.jpg",
                    "file_key":"659FAA1D8F95104"
                }
            ],
            "union_unlock_info":[
                {
                    "user_name": "William",
                    "opmode":"unlock_password",
                    "unlock_name":"Password 1"
                },
                {
                    "user_name":"James",
                    "opmode":"unlock_fingerprint",
                    "unlock_name":"Young",
                }
            ]
        }
    ]
}

Operation records

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock
Applicable lock type	Bluetooth lock

API endpoint

action doorLock.operateRecords

Request parameter

Parameter name	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
startTime	Long	QUERY	The start time. You can select the last three days, the last week, and the last month, or customize a date or period. The default value is `0` to specify all time.	Yes
endTime	Long	QUERY	The end time. You can select the last three days, the last week, and the last month, or customize a date or period. The default value is `0` to specify all time.	Yes
userIds	String	QUERY	The user ID.	No
logCategories	Integer	QUERY	The log category. Valid values: `operation`: operation log `unlock_record`: unlocking log `close_record`: locking log `alarm_record`: alarm log	No
lastRowKey	string	QUERY	Set this parameter to return the records found in the last query. Skip this parameter in your initial query.	No
pageSize	Integer	QUERY	A maximum of 100 entries can be returned on each page.	Yes
onlyShowMediaRecord	bool	QUERY	`true`: returns only the records that contain images.	No

Sample request

{
    "action": "doorLock.operateRecords",
    "params": {
      "device_id":"deviceId",
    "startTime":"1646116582",
    "endTime":"1646116582",
    "userIds":"sha124124",
    "logCategories":"unlock_record",
    "onlyShowMediaRecord":"true",
    }
}

Return parameter

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 operation 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.

Description of result

Parameter name	Type	Description
hasMore	boolean	Indicates whether more data is available.
lastRowKey	String	The row key of the last entry returned by the previous query.
records	Object

Sample response with records

{
  "records": [
    {
      "log_id": '34679xxx',
      "log_type": 'doorbell',
      "media_info_list": [
        {
          "bucket": 'ty-cn-bizlock-1254153901',
          "file_key": '3xgxxxxxxx',
          "file_path": 'xxxx.jpg',
          "file_url":'',
          "angle": 0,
          "media_key": 'uv59xsf9jcy5vdkm',
          "media_path": 'xxxxx.mjpeg',
          "media_url": '',
          "media_bucket": 'xxxx',
        },
      ],
      "unlock_name": '',
      "user_id": '0',
      "log_category": 'alarm_record',
      "user_name": '',
      "member_bindable_flag": false,
      "dp_id": 19,
      "time": 1654849301000,
      "record_type": 2,
      "current_user": false,
    },

Query latest log entry

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock
Applicable lock type	Bluetooth lock

API endpoint

action doorLock.loglatest

Request parameter

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

Sample request

{
"action": "doorLock.loglatest",
    "params": {
        "device_id":"vedeo411aa97e86169akp4",
    }
}

Return parameter

Parameter name	Type	Description
exist	bool	Indicates whether the specified log entry exists. `true`: yes.
logId	Long	The log ID.
logCategory	string	The log category. Valid values: `operation`: operation log `unlock_record`: unlocking log `close_record`: locking log `alarm_record`: alarm log
logType	String	The type of log. Valid values:
recordType	int	The type of record that requires unlocking records only. Valid values: `1`: common unlocking record `2`: alarm record
unlockNameRosettaKey	String	The multilingual setting of a locking log entry.
currentUser	bool	Indicates whether the record is generated by the current user. If so, the value is `true`. This parameter is required by non-combined unlocking methods.
userId	String	The user ID, required only by unlocking records, duress alarms, and operation records.
userName	String	The username.
unlockName	String	The name of an unlocking method. The value can be empty.
time	Long	The time when an event occurs.
relateDevName	String	The name of the associated device.
relateOpMode	String	The details of the associated unlocking method.
unionUnlockInfo	object	The information about a combined unlocking method.
data	Long	The details of an alarm or operation log entry.
unReadCount	int	The number of unchecked log entries.

unionUnlockInfo

Parameter name	Type	Description
userName	String	The username triggered by the combined unlocking method. The value can be empty.
opMode	String	The type of unlocking method that is used for combined unlocking.
unlockName	String	The name of the unlocking method that is used for combined unlocking. The value can be empty.
currentUser	bool	Indicates whether the combined unlocking method is used by the current user.
sn	int	The hardware SN of the device that is bound with the combined unlocking method.

Sample response

{
    "logId":123345,
    "devId":"6ccf3bec5pnxkhdy",
    "logCategory":"operate_log",
    "logType":"dev_bind",
    "userId":123,
    "userName":"User 1",
    "currentUser":false,
    "unReadCount":1

}

Get mappings between standard dpCode and dpId

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock
Applicable lock type	Bluetooth lock

API endpoint

action doorLock.getAvailableInstructions

Request parameter

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

Sample request

{
  "device_id":"6cae1drr3kpl **** "
}

Return parameter

An array that includes the elements listed in the following table is returned.

Field name	Type	Description
dp_id	Integer	The DP ID.
dp_code	String	The DP identifier.

Sample response

[
    {
        "dp_code":"unlock_password",
        "dp_id":12
    },
    {
        "dp_code":"unlock_fingerprint",
        "dp_id":13
    }
]

Unlock door without password

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock
Applicable lock type	Zigbee lock
Applicable lock type	Bluetooth lock
Applicable lock type	Standard Wi-Fi lock

API endpoint

action doorLock.passwordFreeOpen

Request parameter

Parameter name	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
ticket_id	String	Body	The ID of the ticket for authorization. You can call `doorLock.passwordTicket` to get the value.	Yes
channel_id	String	Body	The channel ID of access control. This parameter is required only for Wi-Fi access control.	No

Sample request

{
  "action": "doorLock.passwordFreeOpen",
  "params": {
    "device_id": "vdevo15345926009 **** ",
    "ticket_id": "9wxxoLM"
  }
}

Return parameter

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

Query unlocking records

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock
Applicable lock type	Zigbee lock
Applicable lock type	Bluetooth lock

API endpoint

action: doorLock.openingLogs

Request parameter

Parameter name	Type	Description	Required
device_id	String	The device ID.	Yes
page_no	Integer	The page number.	Yes
page_size	Integer	The number of entries returned on each page.	Yes
start_time	Long	The start time of the period to be queried. Unit: milliseconds.	Yes
end_time	Long	The end time of the period to be queried. Unit: milliseconds.	Yes

Sample request

{
  "action": "doorLock.openingLogs",
  "params": {
    "device_id": "vdevo15792460703 **** ",
    "page_no": 1,
    "page_size": 20,
    "start_time": 1583213146000,
    "end_time": 1583213546000
  }
}

Return parameter

Parameter name	Type	Description
code	Integer	The response code. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation 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.

Description of result

Parameter name	Type	Description
total	Integer	The total number of unlocking records.
logs	List	The unlocking records.

Description of logs

Parameter name	Type	Description
avatar	String	The avatar of the user.
nick_name	String	The username.
unlock_name	String	The name of the password.
update_time	Long	The time when the data was last updated.
user_id	String	The user ID.
status	List	The list of lock status.

Description of status

Parameter name	Type	Description
code	String	The status code.
value	String	The status value.

Description of status code

Parameter name	Type	Description
unlock_finger	Long	Unlock with a fingerprint. The number is assigned locally by the lock.
unlock_password	Long	Unlock with a password. The number is assigned locally by the lock.
unlock_temporary	Long	Unlock with a temporary password. The number is assigned locally by the lock.
unlock_dynamic	Long	Unlock with a dynamic password. The number is assigned locally by the lock.
unlock_card	Long	Unlock with a card. The number is assigned locally by the lock.
unlock_face	Long	Unlock with face recognition. The number is assigned locally by the lock.
unlock_key	Long	Unlock with a mechanical key. The number is assigned locally by the lock.

Sample response

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

Query dynamic password

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock
Applicable lock type	Zigbee lock
Applicable lock type	Bluetooth lock

API endpoint

action: doorLock.getDynamicPassword

Request parameter

Parameter name	Type	Description	Yes
device_id	String	The device ID.	Yes

Sample request

{
  "action": "doorLock.getDynamicPassword",
  "params": {
    "device_id": "vdevo15792460703 **** "
  }
}

Return parameter

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

Description of result

Parameter name	Type	Description
dynamic_password	String	The dynamic password.

Sample response

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

Process of password encryption

Query temporary key for password encryption

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock
Applicable lock type	Zigbee lock
Applicable lock type	Bluetooth lock

API endpoint

action: doorLock.passwordTicket

Request parameter

Parameter name	Type	Description	Required
device_id	String	The device ID.	Yes

Sample request

{
  "action": "doorLock.passwordTicket",
  "params": {
    "device_id": "vdevo15345926009 **** "
  }
}

Return parameter

Parameter name	Type	Description
code	Integer	The response code. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation 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.

Description of result

Parameter name	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": "901CC35A67DA3429C38E9622 **** 3EAE1CE333462356D257FD1D3E5C"
  },
  "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"
}

Query temporary password

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock
Applicable lock type	Zigbee lock
Applicable lock type	Bluetooth lock
Applicable lock type	Wi-Fi access control devices

API endpoint

action: doorLock.getTemporaryPassword

Request parameter

Parameter name	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
password_id	Long	URI	The password ID.	Yes

Sample request

{
  "action": "doorLock.getTemporaryPassword",
  "params": {
    "device_id": "vdevo15345926009 **** ",
    "password_id": 1001
  }
}

Return parameter

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 operation 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.

Description of result

Parameter name	Type	Description
password_id	Long	The ID of a specified temporary password.
name	String	The name of a specified temporary password.
phase	Integer	The status of the temporary password. Valid values:
effective_time	Long	The 10-digit timestamp of the effective time.
invalid_time	Long	The 10-digit timestamp when a temporary password expires.
phone	String	The mobile phone number.
time_zone	String	The time zone.
delivery_status	Integer	The status of the operation. Valid values: `1`: Setting. `2`: Set successfully. `3`: Failed to set. `4`: Reset the password. `5`: No more passwords can be added. `6`: The validity period is overlapped with that of another password. This field is required for Zigbee locks.
schedule_list	List	The parameter list for the schedule feature.
sn	Integer	The serial number of the password for the Bluetooth lock.

schedule_list

Parameter name	Type	Description
effective_time	Long	The time when a password becomes effective on that day. Unit: minutes.
invalid_time	Long	The time when a password expires on that day. Unit: minutes.
working_day	Int	A week is represented with one byte. Bits 0 to 6 represent each day in a week from Sunday to Saturday.

Description of phase

Zigbee:
- 1: To be created
- 2: normal
- 3: Frozen
- 4: Deleted
- 5: Creation failed
Wi-Fi:
- 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: Failed to send

Sample response on success

{
  "success": true,
  "t": 1542626129429,
  "result": {
    "password_id": 1001, // The primary key of a temporary password.
    "effective_time": 1530841779, // The 10-digit timestamp of the effective time.
    "invalid_time": 1530881779, // The 10-digit timestamp of the expiration time.
    "name": "Tenant A's password", // The name of a temporary password.
    "phase": 1, // The password status.
    "phone": "123547127362",
    "time_zone": "Asia/Shanghai",
    "delivery_status": 1
  }
}

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

Query temporary password list

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock
Applicable lock type	Zigbee lock
Applicable lock type	Bluetooth lock
Applicable lock type	Wi-Fi access control devices

API endpoint

action: doorLock.getTemporaryPasswordList

Request parameter

Parameter name	Type	Description	Required
device_id	String	The device ID.	Yes
valid	Boolean	Mark whether a password is valid. Valid values: `true`: Mark a valid password. `false`: Mark an invalid password.	Yes

Sample request

{
  "action": "doorLock.getTemporaryPasswordList",
  "params": {
    "device_id": "vdevo15345926009 **** "
  }
}

Return parameter

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 operation 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 deleted password.

Description of result

Parameter name	Type	Description
id	Long	The ID of a specified temporary password.
name	String	The name of a specified temporary password.
phase	Integer	The status of the temporary password. Valid values:
effective_time	Long	The 10-digit timestamp of the effective time.
invalid_time	Long	The 10-digit timestamp when a temporary password expires.
phone	String	The mobile phone number.
time_zone	String	The time zone.
delivery_status	Integer	The status of the operation. Valid values: `1`: Setting. `2`: Set successfully. `3`: Failed to set. `4`: Reset the password. `5`: No more passwords can be added. `6`: The validity period is overlapped with that of another password. This field is required for Zigbee locks.
schedule_list	List	The parameter list for the schedule feature.
sn	Integer	The serial number of the password for the Bluetooth lock.

schedule_list

Parameter name	Type	Description
effective_time	Long	The time when a password becomes effective on that day. Unit: minutes.
invalid_time	Long	The time when a password expires on that day. Unit: minutes.
working_day	Int	A week is represented with one byte. Bits 0 to 6 represent each day in a week from Sunday to Saturday.

Description of phase

Zigbee: 1: to be created, 2: normal, 3: frozen, 4: deleted, 5: failed to create
Wi-Fi: 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: failed to send

Sample response on success

{
  "success": true,
  "t": 1542626129429,
  "result": [
    {
      "password_id": 1001, // The primary key of a temporary password.
      "effective_time": 1530841779, // The 10-digit timestamp of the effective time.
      "invalid_time": 1530881779, // The 10-digit timestamp of the expiration time.
      "name": "Tenant A's password", // The name of a temporary password.
      "phase": 1, // The password status.
      "phone": "123547127362",
      "time_zone": "Asia/Shanghai",
      "delivery_status": 1
    }
  ]
}

Sample response on failure

{
  "success": false,
  "code": 500, // The error code. For more information, see Global Error Codes.
  "msg": "System exception. Contact the administrator."
}

Create temporary password

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock
Applicable lock type	Zigbee lock
Applicable lock type	Bluetooth lock
Applicable lock type	Wi-Fi access control devices

API endpoint

action: doorLock.createTemporaryPassword

Request parameter

Parameter name	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
name	String	BODY	The name of a specified temporary password.	Yes
password	String	BODY	The length of the original password is seven for Wi-Fi locks and six for Zigbee locks and Bluetooth locks. 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. Try to make an API request to get the value of `accessKey`. For an OEM WeChat mini program, you can also check `accessKey on the platform.	Yes
effective_time	Long	BODY	The 10-digit timestamp of the effective time. Unit: seconds.	Yes
invalid_time	Long	BODY	The 10-digit timestamp of the expiration time. Unit: seconds.	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
phone	String	BODY	The mobile phone number.	No
type	Integer	BODY	The validity type of the lock password. Valid values: `1`: a one-time password. `0`: a password can be used as many times as needed before it expires.	This field is required for Zigbee locks.
time_zone	String	BODY	The time zone. This field is required if you use the schedule feature.	No
schedule_list	List	BODY	The parameter list for the schedule feature.	No
bluetooth_symbolic	Boolean	BODY	Set the value to `true` for the WeChat mini program of a Bluetooth lock.	No
sn	Integer	BODY	The serial number of the password for the Bluetooth lock.	No

schedule_list

Parameter name	Type	Parameter type	Description	Required
effective_time	Long	BODY	The time when a password becomes effective on that day. Unit: minutes.	Yes
invalid_time	Long	BODY	The time when a password expires on that day. Unit: minutes.	Yes
working_day	Int	BODY	A week is represented with one byte. Bits 0 to 6 represent each day in a week from Sunday to Saturday.	Yes

Sample request

{
  "action": "doorLock.createTemporaryPassword",
  "params": {
    "device_id": "vdevo15345926009 **** ",
    "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
      }
    ]
  }
}

Return parameter

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 operation 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.

Description of result

Parameter name	Type	Description
id	Long	The ID of a specified temporary password.

Sample response on success

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

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

Create unnamed temporary password

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock
Applicable lock type	Zigbee lock
Applicable lock type	Bluetooth lock

API endpoint

action: doorLock.createTemporaryPasswordWithoutName

Request parameter

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 seven for Wi-Fi locks and six for Zigbee locks and Bluetooth locks. 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
effective_time	Long	BODY	The 10-digit timestamp of the effective time. Unit: seconds.	Yes
invalid_time	Long	BODY	The 10-digit timestamp of the expiration time. Unit: seconds.	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
phone	String	BODY	The mobile phone number.	No
type	Integer	BODY	The validity type of the lock password. Valid values: `1`: a one-time password. `0`: a password can be used as many times as needed before it expires.	This field is required for Zigbee locks.
time_zone	String	BODY	The time zone. This field is required if you use the schedule feature.	No
schedule_list	List	BODY	The parameter list for the schedule feature.	No
bluetooth_symbolic	Boolean	BODY	Set the value to `true` for the WeChat mini program of a Bluetooth lock.	No
sn	Integer	BODY	The serial number of the password for the Bluetooth lock.	No

schedule_list

Parameter name	Type	Parameter type	Description	Required
effective_time	Long	BODY	The time when a password becomes effective on that day. Unit: minutes.	Yes
invalid_time	Long	BODY	The time when a password expires on that day. Unit: minutes.	Yes
working_day	Int	BODY	A week is represented with one byte. Bits 0 to 6 represent each day in a week from Sunday to Saturday.	Yes

Sample request

{
  "action": "doorLock.createTemporaryPasswordWithoutName",
  "params": {
    "device_id": "vdevo15345926009 **** ",
    "password": "956FAD7 **** 09C68E168B77",
    "effective_time": 1579156726,
    "invalid_time": 1579243126,
    "phone": 11233213,
    "time_zone": "",
    "schedule_list": [
      {
        "effective_time": 720,
        "invalid_time": 1080,
        "working_day": 0
      }
    ]
  }
}

Return parameter

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 operation 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.

Description of result

Parameter name	Type	Description
id	Long	The ID of a specified temporary password.

Sample response on success

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

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

Modify temporary password

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock
Applicable lock type	Zigbee lock
Applicable lock type	Bluetooth lock (password change is not supported)
Applicable lock type	Wi-Fi access control devices

API endpoint

action: doorLock.modifyTemporaryPassword

Request parameter

Parameter name	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
password_id	Long	URI	The password ID.	Yes
name	String	BODY	The name of a specified temporary password.	No
password	String	BODY	The length of the original password is seven for Wi-Fi locks and six for Zigbee locks. Bluetooth locks do not support password change. 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
effective_time	Long	BODY	The 10-digit timestamp of the effective time. Unit: seconds.	Yes
invalid_time	Long	BODY	The 10-digit timestamp of the expiration time. Unit: seconds.	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
phone	String	BODY	The mobile phone number.	No
type	Integer	BODY	The validity type of the lock password. Valid values: `1`: a one-time password. `0`: a password can be used as many times as needed before it expires.	This field is required for Zigbee locks.
time_zone	String	BODY	The time zone. This field is required if you use the schedule feature.	No
schedule_list	List	BODY	The parameter list for the schedule feature.	No
bluetooth_symbolic	Boolean	BODY	Set the value to `true` for the WeChat mini program of a Bluetooth lock.	No

schedule_list

Parameter name	Type	Parameter type	Description	Required
effective_time	Long	BODY	The time when a password becomes effective on that day. Unit: minutes.	Yes
invalid_time	Long	BODY	The time when a password expires on that day. Unit: minutes.	Yes
working_day	Int	BODY	A week is represented with one byte. Bits 0 to 6 represent each day in a week from Sunday to Saturday.	Yes

Sample request

{
  "action": "doorLock.modifyTemporaryPassword",
  "params": {
    "device_id": "vdevo15345926009 **** ",
    "password_id": 1234213434,
    "phone": "",
    "effective_time": "",
    "invalid_time": "",
    "name": "",
    "password": "",
    "password_type": "ticket",
    "ticket_id": "xxx"
  }
}

Return parameter

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 operation 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 deleted password.

Sample response on success

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

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

Rename temporary password

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock
Applicable lock type	Zigbee lock
Applicable lock type	Bluetooth lock (password change is not supported)

API endpoint

action: doorLock.modifyTemporaryPassword

Request parameter

Parameter name	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
password_id	Long	URI	The password ID.	Yes
name	String	BODY	The name of a specified temporary password.	Yes
password	String	BODY	The length of the original password is seven for Wi-Fi locks and six for Zigbee locks. Bluetooth locks do not support password change. 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.	No
effective_time	Long	BODY	The 10-digit timestamp of the effective time. Unit: seconds.	No
invalid_time	Long	BODY	The 10-digit timestamp of the expiration time. Unit: seconds.	No
password_type	String	BODY	The password is encrypted using a ticket.	No
ticket_id	String	BODY	The ID of a specified temporary key.	No
phone	String	BODY	The mobile phone number.	No
type	Integer	BODY	The validity type of the lock password. Valid values: `1`: a one-time password. `0`: a password can be used as many times as needed before it expires.	This field is required for Zigbee locks.
time_zone	String	BODY	The time zone. This field is required if you use the schedule feature.	No
schedule_list	List	BODY	The parameter list for the schedule feature.	No
bluetooth_symbolic	Boolean	BODY	Set the value to `true` for the WeChat mini program of a Bluetooth lock.	No

schedule_list

Parameter name	Type	Parameter type	Description	Required
effective_time	Long	BODY	The time when a password becomes effective on that day. Unit: minutes.	Yes
invalid_time	Long	BODY	The time when a password expires on that day. Unit: minutes.	Yes
working_day	Int	BODY	A week is represented with one byte. Bits 0 to 6 represent each day in a week from Sunday to Saturday.	Yes

Sample request

{
  "action": "doorLock.modifyTemporaryPassword",
  "params": {
    "device_id": "vdevo15345926009 **** ",
    "password_id": 1234213434,
    "phone": "",
    "effective_time": "",
    "invalid_time": "",
    "name": "New name",
    "password": "",
    "password_type": "",
    "ticket_id": ""
  }
}

Return parameter

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 operation 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 deleted password.

Sample response on success

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

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

Delete temporary password

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock
Applicable lock type	Zigbee lock
Applicable lock type	Bluetooth lock
Applicable lock type	Wi-Fi access control devices

API endpoint

action : doorLock.deleteTemporaryPassword

Request parameter

Parameter name	Type	Description	Yes
device_id	String	The device ID.	Yes
password_id	String	The password ID.	Yes
bluetooth_symbolic	Boolean	Set the value to `true` for the WeChat mini program of a Bluetooth lock.	No

Sample request

{
  "action": "doorLock.deleteTemporaryPassword",
  "params": {
    "device_id": "vdevo15345926009 **** ",
    "password_id": 12342134123
  }
}

Return parameter

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 operation 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

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

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

Delete invalid temporary passwords from lock

This API is currently being developed.

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock
Applicable lock type	Zigbee lock
Applicable lock type	Bluetooth lock

API endpoint

action : doorLock.removalInvalidTempPasswords

Request parameter

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

Sample request

{
  "action": "doorLock.removalInvalidTempPasswords",
  "params": {
    "device_id": "vdevo15345926009 **** "
  }
}

Return parameter

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 operation 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

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

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

Query latest status of device

API endpoint

action: device.status

Request parameter

Parameter name	Type	Description	Required
device_id	String	The device ID.	Yes

Sample request

{
  "action": "device.status",
  "params": {
    "device_id": "vdevo15834602718 **** "
  }
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation 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	Indicates whether the operation is successful.

Sample response

{
  "result": [
    {
      "code": "switch_led",
      "value": true
    },
    {
      "code": "work_mode",
      "value": "white"
    },
    {
      "code": "bright_value_v2",
      "value": 370
    },
    {
      "code": "temp_value_v2",
      "value": 216
    },
    {
      "code": "scene_data_v2",
      "value": ""
    },
    {
      "code": "countdown_1",
      "value": 0
    },
    {
      "code": "control_data",
      "value": "{\"bright\":370,\"change_mode\":\"gradient\",\"h\":0,\"s\":0,\"temperature\":216,\"v\":0}"
    }
  ],
  "success": true,
  "t": 1583740617030
}

Send command

API endpoint

action: device.control

Request parameter

Parameter name	Type	Description	Required
device_id	String	The device ID.	Yes
commands	Object	The instruction set.	Yes

Sample request

{
  "action": "device.control",
  "params": {
    "device_id": "vdevo15813256493 **** ",
    "commands": [
      {
        "code": "switch_led",
        "value": true
      }
    ]
  }
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation 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	Indicates whether the operation is successful.

Query remote unlocking methods supported by lock

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock
Applicable lock type	Zigbee lock
Applicable lock type	Bluetooth lock

API endpoint

action : doorLock.remoteUnlocks

Request parameter

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

Sample request

{
  "action": "doorLock.remoteUnlocks",
  "params": {
    "device_id": "vdevo15345926009 **** "
  }
}

Return parameter

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 operation 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	List	The returned result.

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	Specifies whether to enable this feature.
device_id	String	The device ID.

Sample response on success

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

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 on/off status for remote unlocking

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock
Applicable lock type	Zigbee lock
Applicable lock type	Bluetooth lock

API endpoint

action : doorLock.remoteUnlockConfig

Request parameter

Parameter name	Type	Parameter type	Description	Yes
device_id	String	URI	The device ID.	Yes
remote_unlock_type	String	Body	The unlocking method.	Yes
open	Boolean	Body	Specifies whether to enable this feature.	Yes

Sample request

{
  "action": "doorLock.remoteUnlockConfig",
  "params": {
    "device_id": "vdevo15345926009 **** ",
    "open": true,
    "remote_unlock_type": ""
  }
}

Return parameter

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 operation 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

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

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 list of unlocking methods not bound with users

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock
Applicable lock type	Bluetooth lock

API endpoint

action : doorLock.listUnallocatedOpmodes

Request parameter

Parameter name	Type	Description	Yes
device_id	String	The device ID.	Yes
page_no	Integer	The current page number, starting from `1`.	Yes
page_size	Integer	The maximum number of entries returned on each page.	Yes

Sample request

{
    "device_id":"6cdbaew2mm6v **** ",
      "page_no":1,
      "page_size": 10
}

Return parameter

Parameter name	Type	Description
opmode	String	The type of unlocking method.
standard_dp	String	The standard DP identifier of an unlocking method.
unlock_info	List	The value of an unlocking method.

Description of unlock_info

Parameter name	Type	Description
dp_code	String	The standard DP identifier of an unlocking method.
unlock_sn	Integer	The ID of an unlocking method.
unlock_name	String	The name of an unlocking method.

Sample response

[
    {
        "opmode":"12",
        "standard_dp":"unlock_fingerprint",
          "unlock_info":[
          {
            "dp_code":"unlock_fingerprint",
            "unlock_sn":3,
            "unlock_name":"Young",
          }
        ]
    }
]

Bind unlocking method with user

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock
Applicable lock type	Bluetooth lock

API endpoint

action : doorLock.allocateOpmode

Request parameter

Parameter name	Type	Parameter type	Description	Yes
device_id	String	URI	The device ID.	Yes
user_id	String	BODY	The user ID.	Yes
unlock_list	Array	BODY	The list of unlocking methods.	Yes

Description of unlock_list

Parameter name	Type	Required	Description
dp_code	String	Yes	The standard DP identifier of an unlocking method.
unlock_sn	Integer	Yes	The serial number of the unlocking method.

Sample request

{
    "device_id":"eb289eyjlyn8 **** ",
    "user_id":"23578",
    "unlock_list":[
        {
            "dp_code":"unlock_password",
            "unlock_sn":1
        },
        {
            "dp_code":"unlock_card",
            "unlock_sn":2
        }
    ]
}

Return parameter

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 operation 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

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

Unbind unlocking method from user

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock
Applicable lock type	Bluetooth lock

API endpoint

action : doorLock.deallocateOpmode

Request parameter

Parameter name	Type	Description	Yes
device_id	String	The device ID.	Yes
user_id	String	The ID of the user with whom an unlocking method is currently bound.	Yes
dp_code	String	The standard DP identifier of an unlocking method.	Yes
unlock_sn	Integer	The serial number of the unlocking method.	Yes

Sample request

{
    "device_id":"6cdbaew2mm6v **** ",
      "user_id":"109238",
      "dp_code":"unlock_password",
      "unlock_sn":3
}

Return parameter

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 operation 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

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

Create link for temporary unlocking

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock
Applicable lock type	Bluetooth lock

API endpoint

action : doorLock.createPermissionSharing

Request parameter

Parameter name	Type	Description	Yes	Remarks
device_id	String	The device ID.	Yes
app_schema	String	The schema of a specified application.	Yes	‘cloud’
sharer	String	The account of the user who initiates the sharing invitation.	Yes	If the current user initiates the sharing invitation, enter the user’s UID.
receiver	String	The account of the user who receives the sharing invitation. This parameter is optional.	No
permission_detail	JSON	The details of permissions.	Yes

Description of permission_detail

Parameter name	Type	Description	Yes
biz_type	String	The business type. Valid values: `unlock_ble`: unlock over Bluetooth `unlock_fingerprint`: unlock with fingerprint	Yes
available_times	Integer	The number of times the password can be used. Valid values: `-1`: as many times as needed before the password expires. Enter another value to represent the number of times the password can be used.	Yes
name	String	name	No
effective_time	Long	The time when the password becomes effective. If this parameter is empty, the password is always valid.	No
invalid_time	Long	The time when the password expires. If this parameter is empty, the password is always valid.	No
schedule_start_time	Integer	The start time of the schedule. Unit: minutes. For example, `07:30` indicates that the value is `450`. Calculation: 7 x 60 + 30 = 450.
schedule_end_time	Integer	The expiration of the schedule. Unit: minutes. For example, `08:30` indicates that the value is `510`. Calculation: 8 x 60 + 30 = 510.
working_day	Integer	The weekly recurring field `workingDay` consists of seven bits, and each bit is 1 or 0. Bits 0 to 6 represent each day in a week from Sunday to Saturday. The schedule is run on the day with the bit value of 1. For example, Monday/Tuesday/Friday is represented as `00100110`, which equals to `38`, so the value of `working_day` is 38.	No

Sample request

{
    "action":"doorLock.createPermissionSharing",
    "params":{
        "device_id":"vdev233 **** ",
        "sharer":"ay16188442964611MKHJ",
        "app_schema":"e5b2e9464c206cff6e16f8280f5be730",
          "permission_detail":{
            "biz_type":"unlock_ble",
            "available_times":-1,
            "name":"Jane",
            "effective_time":1621101162000,
            "invalid_time":1621965162000,
            "schedule_start_time":450,
            "schedule_end_time":510,
            "working_day":38
        }
    }
}

Return parameter

Parameter name	Type	Description
sharing_id	String	The ID of the sharing invitation.
sharing_ticket	String	The one-time ticket for sharing.
expire_time	Long	The time when the password expires. Unit: seconds.

Sample response

{
    "expire_time":300,
    "sharing_id":"1213089",
    "sharing_ticket":"3ea6e254e83750dc924dd78dd5a61460"
}

Verify link for temporary unlocking

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock
Applicable lock type	Bluetooth lock

API endpoint

action : doorLock.verifyPermissionSharing

Request parameter

Parameter name	Type	Description	Yes	Remarks
sharing_ticket	String	The ticket for sharing.	Yes

Sample request

{
    "sharing_ticket":"3ea6e254e83750dc924dd78dd5a61460"
}

Return parameter

Parameter name	Type	Description
sharing_id	String	The ID of the sharing invitation.
sharing_ticket	String	The one-time ticket for sharing.
expire_time	Long	The time when the sharing invitation expires. Unit: seconds. A value less than or equal to 0 represents an expired sharing invitation.

Sample response

{
    "expire_time":100,
    "sharing_id":"1213089",
    "sharing_ticket":"3ea6e254e83750dc924dd78dd5a61460"
}

Confirm link for temporary unlocking

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock
Applicable lock type	Bluetooth lock

API endpoint

action : doorLock.confirmPermissionSharing

Request parameter

Parameter name	Type	Description	Yes	Remarks
sharing_id	String	The ID of the sharing invitation.	Yes
app_schema	String	The schema of a specified application.	Yes	‘cloud’
sharing_ticket	String	The ticket for sharing.	Yes
receiver	String	The account of the user who receives the sharing invitation.	Yes	This is the UID of the user who receives the sharing invitation.

Sample request

{
    "action":"doorLock.confirmPermissionSharing",
    "params":{
        "sharing_id":"10001",
        "sharing_ticket":"3ea6e254e83750dc924dd78dd5a61460",
        "app_schema":"e5b2e9464c206cff6e16f8280f5be730",
          "receiver":"ay16198742964611KDYU"
    }
}

Return parameter

Parameter name	Type	Description
permission_id	Long	The permission ID.
biz_type	String	The business type. Valid values: `unlock_ble`: unlock over Bluetooth `unlock_fingerprint`: unlock with fingerprint
available_times	Integer	The number of times the password can be used. Valid values: `-1`: as many times as needed before the password expires. Enter another value to represent the number of times the password can be used.
name	String	The name.
effective_time	Long	The validity period.
invalid_time	Long	The expiration time.
schedule_start_time	Integer	The start time of the schedule. Unit: minutes. For example, `07:30` indicates that the value is `450`. Calculation: 7 x 60 + 30 = 450.
schedule_end_time	Integer	The start time of the schedule. Unit: minutes. For example, `08:30` indicates that the value is `510`. Calculation: 8 x 60 + 30 = 510.
working_day	Integer	The weekly recurring field `workingDay` consists of seven bits, and each bit is 1 or 0. Bits 0 to 6 represent each day in a week from Sunday to Saturday. The schedule is run on the day with the bit value of 1. For example, Monday/Tuesday/Friday is represented as `00100110`, which equals to `38`, so the value of `working_day` is 38.
effective_flag	Integer	Indicates whether the password is valid. Valid values: `0`: invalid `1`: valid `2`: to be effective later
schedule_effective_flag	Integer	Indicates whether the schedule is valid in the current time. Valid values: `0`: invalid `1`: valid (invalid if `effective_flag` is `0`)

Sample response

{
    "biz_type":"unlock_ble",
    "available_times":1,
    "name":"Jane",
    "effective_time":1621101162000,
    "invalid_time":1621965162000,
    "schedule_start_time": 480,
    "schedule_end_time": 510,
    "working_day":100,
    "effective_flag":1,
    "schedule_effective_flag":0
}

Cancel sharing link for temporary unlocking

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock
Applicable lock type	Bluetooth lock

API endpoint

action : doorLock.cancelPermissionSharing

Request parameter

Parameter name	Type	Description	Yes	Remarks
sharing_id	String	The ID of the sharing invitation.	Yes
sharing_ticket	String	The ticket for sharing.	Yes

Sample request

{
  "sharing_id":"2322",
  "sharing_ticket":"3ea6e254e83750dc924dd78dd5a61460"
}

Return parameter

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 operation 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

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

Enable duress alarms for unlocking method

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock
Applicable lock type	Bluetooth lock

API endpoint

doorLock.setHijack

Request parameter

Parameter name	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
unlock_no	Integer	BODY	The serial number of the unlocking method.	Yes
unlock_type	String	BODY	The unlocking method. Valid values: `fingerprint`, `password`, `card`, and `face`.	Yes

Sample request

{
    "device_id":"vdev2332211",
    "unlock_no":2,
    "unlock_type":"fingerprint",
}

Sample response

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

Disable duress alarms for unlocking method

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock
Applicable lock type	Bluetooth lock

API endpoint

doorLock.removeHijack

Request parameter

Parameter name	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
unlock_no	Integer	BODY	The serial number of the unlocking method.	Yes
unlock_type	String	BODY	The unlocking method. Valid values: `fingerprint`, `password`, `card`, and `face`.	Yes

Sample request

{
    "device_id":"vdev2332211",
    "unlock_sn":2,
    "unlock_type":"unlock_fingerprint",
}

Sample response

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

Features dedicated to Bluetooth locks

Unlock without password in short distance

Applicable lock types

Type	Supported
Applicable lock type	Bluetooth lock

API endpoint

acton:   doorLock.unlockInstruction

Request parameter

Parameter name	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
bluetooth_sn	Integer	BODY	The serial number to prevent replay attack during Bluetooth communication. This is the value of `_ble_sn` for a Bluetooth instance after the Bluetooth SDK is integrated.	Yes
device_random	String	BODY	The random number of the lock. You can call `doorLock.getIssuedConfig` to get the value.	Yes

Sample request

{
  "action": "doorLock.unlockInstruction",
  "params": {
    "device_id": "vdevo15345926009 **** ",
    "bluetooth_sn": 123,
    "device_random": "123"
  }
}

Return parameter

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 operation 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 specified unlocking command.

Description of result

Parameter name	Type	Description
instruction	String	The information about a specified unlocking command.
next_sn	Integer	The next serial number to prevent replay attack during Bluetooth communication.

Sample response on success

{
  "result": {
    "next_sn": 123,
    "instruction": "9wxxoLM"
  },
  "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"
}

Assemble data for short-range Bluetooth unlocking

Description

This is an upgrade version of doorLock.unlockInstruction and can be used to replace doorLock.unlockInstruction.

API endpoint

acton:   doorLock.bleOpenInstruction

Request parameter

Parameter name	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
bluetooth_sn	Integer	BODY	The serial number to prevent replay attack during Bluetooth communication. This is the value of `_ble_sn` for a Bluetooth instance after the Bluetooth SDK is integrated.	Yes
device_random	String	BODY	The random number of the lock. You can call `doorLock.getIssuedConfig` to get the value.	Yes
open	Boolean	BODY	Indicates whether to lock or unlock the door. Valid values: `true`: unlock. `false`: lock.	No
bluetooth_major_version	Integer	BODY	The major version of the Bluetooth protocol. For example, set the value to `3` for “3.x” and to `4` for “4.x”. Default value: `3`.	No

Sample request

{
  "action": "doorLock.bleOpenInstruction",
  "params": {
    "device_id":"6cae1drr3kpl **** ",
      "bluetooth_sn":7,
      "device_random":"760a57c866b113f63ef702bb2e914ad4" ,
      "open":true,
      "bluetooth_major_version":3
    }
}

Return parameter

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 operation 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 specified unlocking command.

Description of result

Parameter name	Type	Description
instruction	String	The hexadecimal command for unlocking over Bluetooth. The obtained command is then sent to the lock.
next_sn	Integer	The next serial number to prevent replay attack during Bluetooth communication.

Sample response on success

{
  "result": {
    "next_sn": 123,
    "instruction":"0472426c51476e714b336a333462764b6a635518a38ae29bf3fdc9f60261c15bf725cbb171921b7c129e6adf4e7dee390bf0dc17dca7c51f44eae4d51d1bd102ea",
  },
  "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"
}

Query authKey

API endpoint

action :device.pairingAuthKey

Request parameter

Parameter name	Type	Description	Required
home_id	Long	The home ID.	Yes
uuid	String	The UUID of the specified device.	Yes
uid	String	The user ID.	Yes

Sample request

{
  "action": "device.pairingAuthKey",
  "params": {
    "home_id": "25761214",
    "uuid": "c3ac4b0d54af **** ",
    "uid": "ay16009313532665 **** "
  }
}

Return parameter

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 operation 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 authKey for pairing.

Description of result

Parameter name	Type	Description
encrypted_auth_key	String	The secret key 1.
random	String	The login key.

Sample response on success

{
  "result": {
    "encrypted_auth_key": "456789056789",
    "rondom": "6783456789"
  },
  "success": true,
  "t": 1603679935012
}

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

Query system time

API endpoint

action :timer.currentTime

Request parameter

None

Sample request

{
  "action": "timer.currentTime",
  "params": {}
}

Return parameter

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 operation 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	Long	The timestamp on the server.

Sample response on success

{
  "result": true,
  "success": 1607087405739,
  "t": 1603679935012
}

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

Query configuration to be synched before unlocking verification

Applicable lock types

Type	Supported
Applicable lock type	Bluetooth lock

API endpoint

action : doorLock.getIssuedConfig

Request parameter

Parameter name	Type	Description	Required
device_id	String	The device ID.	Yes

Sample request

{
  "action": "doorLock.getIssuedConfig",
  "params": {
    "device_id": "vdevo16036791579 **** "
  }
}

Return parameter

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 operation 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.

Description of result

Parameter name	Type	Description
lock_random	Object	The random number of the lock. The `distribute` parameter indicates whether to send the DP.
lock_record	Object	Query the offline unlocking records. This parameter is required and transparently sent if the DP ID is 0.

Description of lock_random/lock_record

Parameter name	Type	Description
distribute	Boolean	Specifies whether a DP needs to be sent.
wake_up_ins	Object	The hexadecimal string.
dp_id	Integer	The ID of the DP to be sent.
ins	String	The random number of the lock.
dev_unlock_id	String	The hexadecimal DP data of the queried records.

Sample response on success

{
  "result": {
    "lock_random": {
      "dev_unlock_id": "0005",
      "dp_id": 70,
      "wake_up_ins": "ffff0005000000000000000000ffff3532373737393530",
      "distributed": true,
      "ins": "3532373737393530"
    },
    "lock_record": {
      "dpId": 56,
      "distributed": true,
      "ins": "ffff0005000000000000000000ffff3532373737393530"
    }
  },
  "success": true,
  "t": 1608518987114
}

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

Send T0 time

T0 time is a parameter used in the offline password algorithm and represents the time when a device is activated. You can call device.getListByIds to get the T0 time.

API endpoint

action : device.getListByIds

Request parameter

Parameter name	Type	Description	Required
device_ids	String	The list of device IDs, separated with commas (,).	Yes

Sample request

{
    "action": "device.getListByIds",
    "params": {
        "device_ids": "vdevo153490924188132"
    }
}

Return parameter

An array that includes the elements listed in the following table is returned.

Parameter name	Type	Description	Remarks
id	String	The device ID.
uid	String	The user ID.
local_key	String	The secret key.
category	String	The product category.
product_id	String	The product ID (PID).
sub	Boolean	Indicates whether it is a sub-device. Valid values: `true`: yes `false`: no
uuid	String	The UUID of the specified device.
owner_id	String	The ID of the device owner.
online	Boolean	Indicates whether the device is online.
name	String	The name of the device.
ip	String	The IP address.
time_zone	String	The time zone.
create_time	Long	The time when the device is first paired.
update_time	Long	The time when the device status was last updated.
active_time	Long	The time when the device is last paired.	This is the T0 time to be sent.
status	List	The status of a DP.

Sample response

[
    {
         "sub":false,
         "create_time":1618287272,
         "local_key":"ede14e228a7d7c85",
         "owner_id":"34720161",
         "biz_type":329944,
         "ip":"219.133.159.132",
         "icon":"smart/icon/bay1599447209665AVnx/c7ec976e16d2b309e61ffb65442a65bb.jpg",
         "lon":"114.03490357760252",
         "time_zone":"+08:00",
         "product_name":"Thermostatic milk kettle",
         "uuid":"378fb516c5b8 **** ",
         "active_time":1622000424,
         "uid":"ay1620733026105K **** ",
         "update_time":1622000425,
         "product_id":"bemvogz0z6wl **** ",
         "name":"Thermostatic milk kettle",
         "online":true,
         "id":"6c59dc783afa9dfc27 **** ",
         "category":"cn",
         "lat":"22.64856786505044",
         "status":[
                 {
                      "code":"DIY_FUNC1",
                      "value":"23 honey water 83 honey water P3 honey water A3 honey water"
                },
                {
                      "code":"fun1_water",
                      "value":241
                }
         ]
    }
]

In the returned data, convert the active_time field value into the hexadecimal format and send the result.

Sync user data

Applicable lock types

Type	Supported
Applicable lock type	Bluetooth lock

Description

Data is synchronized each time the device goes online and the user list is refreshed. In the case of frequent refreshes, data is also frequently synchronized. Therefore, a new synchronization task might be started when the last one is still in progress. This will cause a waste of local and cloud resources.
Therefore, the purpose of this API request is to control the synchronization frequency. A synchronization command is sent to the device only when the panel calls this operation with distributed=true returned.
The cloud controls the frequency. Data is synchronized at an interval of at least five seconds.

API endpoint

action : doorLock.getSyncableOpmodeTypes

Request parameter

Parameter name	Type	Parameter type	Description	Required	Remarks
device_id	String	URI	The device ID.	Yes
target_standard_dp_codes	String	String	The standard DP identifier. Multiple DP identifiers are separated with commas (,).	Yes	Provide the record type of DP data. For example, set the value to `unlock_fingerprint,unlock_password` to query the fingerprints and passwords.

Sample request

{
    "device_id":"6cdbaew2mm6v **** ",
      "target_standard_dp_codes":"unlock_fingerprint",
}

Return parameter

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 operation 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.

Description of result

Parameter name	Type	Description
dp_id	Integer	The DP ID to be sent.
distributed	Boolean	Indicates whether a DP needs to be sent.
ins	String	The hexadecimal command. The command is sent to the lock.

Sample response

{
    "dp_id":54,
    "distributed":true,
    "ins":"03"
}

Features dedicated to Zigbee locks

Unlock with password

Applicable lock types

Type	Supported
Applicable lock type	Zigbee lock

API endpoint

action : doorLock.openDoor

Request parameter

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. 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

Response parameter

Parameter name	Type	Description
code	Integer	The response code. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation 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
}

Features dedicated to Wi-Fi locks

Reject request for remote unlocking

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock

API endpoint

doorLock.cancelPasswordFreeOpen

Request parameter

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

{
  "action": "doorLock.cancelPasswordFreeOpen",
  "params": {
    "device_id": "vdevo16036791579 **** ",
    "type": 1
  }
}

Return parameter

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

Get cover image of last remote unlocking operation or alert

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock

API endpoint

doorLock.getMediaUrl

Request parameter

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

Sample request

{
      "device_id":"vdev2332211",
    "file_type":1
}

Return parameter

Field name	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"
}

User-related operations

Get user information.

API endpoint

doorLock.getUser

Request parameter

Parameter name	Type	Description	Required
device_id	String	The device ID.	Yes
user_id	String	The user ID. Set the value to `0` to get information about the current user.	Yes

Sample request

{
    "device_id":"00000561bcddc235 **** ",
    "user_id":"0"
}

Return parameter

Field name	Type	Description
user_id	string	The member ID.
lock_user_id	Integer	The lock user ID.
avatar_url	string	The URL of an avatar.
user_type	Integer	The user type of the member. Valid values: `50`: home owner `10`: administrator `20`: common member `30`: anonymous member
nick_name	string	The nickname of the user.
user_contact	string	The contact method.

Example

{
    "user_id":"0000000001",
    "lock_user_id":2,
    "nick_name":"123",
    "avatar_url":"smart/user_res/ay1519797357494tgSIE/scale/avatar_1524487255195.jpg",
    "user_type":10,
    "user_contact":"86-15278010021"
}

Query unlocking method list of user

API endpoint

doorLock.listUserOpmodes

Request parameter

Parameter name	Type	Description	Required
device_id	String	The device ID.	Yes
user_id	String	The user ID.	Yes
target_unlock_standard_dp_codes	String	The DP identifier of the target unlocking method. Multiple DP identifiers are separated with commas (,). The value can be empty. Valid values: `unlock_fingerprint`: unlock with fingerprint `unlock_password`: unlock with password `unlock_card`: unlock with card	Yes
page_no	int	The page number.	Yes
page_size	int	The number of entries returned per page.	Yes

Sample request

{
    "action":"doorLock.listUserOpmodes",
    "params":{
        "device_id":"vdevo16036791579 **** ",
        "user_id":"1212 **** ",
   "target_unlock_standard_dp_codes":
          "unlock_fingerprint,unlock_password,unlock_card",
        "page_no":1,
        "page_size":100
    }
}

Return parameter

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 operation 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	JSON	The number of entries returned on each page.

Description of result

Parameter name	Type	Description
has_more	bool	Indicates whether more data is available. `true`: yes `false`: no
records	json_array	The array of records.

Description of records

Parameter name	Type	Description
user_name	String	The username.
user_id	String	The user ID stored in the cloud.
user_type	String	The user type of the member. Valid values: `0`: unknown type `10`: administrator `20`: common home member `30`: marked member
lock_user_id	String	The user ID on the lock.
unlock_name	String	The name of the unlocking method.
dp_code	String	The type of unlocking method. Valid values: `unlock_fingerprint`: unlock with fingerprint `unlock_password`: unlock with password `unlock_card`: unlock with card
unlock_sn	int	The serial number of a specified unlocking method on the lock.
unlock_attr	int	The attribute of an unlocking method. Valid values: `0`: no attribute `1`: duress alarm
photo_unlock	int	Indicates whether to enable capture during unlocking. Valid values: `0`: no `1`: yes

Sample response on success

{
    "result":{
        "total":1,
        "records":[
              {
                  "dp_code":"unlock_password",
                  "unlock_attr":0,
                  "unlock_name":"lin",
                  "user_name":"James",
                  "user_id":"2887 **** ",
                  "unlock_sn":3,
                  "uid":"ay1562298621752U **** ",
                  "unlock_id":"12-3",
                  "lock_user_id":2,
                  "user_type":20,
                  "photo_unlock": false
              }
        ],
        "has_more":false,
        "total_pages":0
    },
    "success":true,
    "t":1624204036171
}

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

Query a list of members

API endpoint

doorLock.listUsers

Request parameter

Parameter name	Type	Description	Required	Remarks
device_id	String	The device ID.	Yes
target_standard_dp_codes	String	The standard DP identifier. Multiple DP identifiers are separated with commas (,). If this parameter is empty, the user’s unlocking methods will not be returned.	Yes	Provide the record type of DP data. For example, set the value to `unlock_fingerprint,unlock_password` to query the fingerprints and passwords.
page_no	Integer	The current page number, starting from `1`.	Yes
page_size	Integer	The maximum number of entries returned on each page.	Yes

Sample request

{
    "device_id":"tuya384dfed85348 **** ",
      "target_standard_dp_codes":"unlock_fingerprint,unlock_password",
      "page_no":1,
      "page_size": 10
}

Return parameter

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 operation 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	JSON	The number of entries returned on each page.

Description of result

Parameter name	Type	Description
user_id	String	The user ID.
lock_user_id	Integer	The user ID stored on the lock. Make sure the value is not `0` in the cloud.
user_contact	String	The contact method.
nick_name	String	The nickname.
avatar_url	String	The URL of an avatar.
user_type	Integer	The type of member. Valid values: `50`: home owner `10`: administrator `20`: common member `30`: anonymous member
back_home_notify_attr	Integer	Indicates whether to enable notifications of home member arrival. Valid values: `0`: no. `1`: yes.
unlock_detail	List	The list of unlocking methods assigned to the member.
effective_flag	Integer	Indicates whether the unlocking method is valid. Valid values: `0`: invalid `1`: valid `2`: to be effective later
time_schedule_info	JSON	The information about the user’s validity period.

Description of unlock_detail

Field name	Type	Description
dp_code	String	dp_code
open	Boolean	Specifies whether to unlock the door.
count	Integer	The number of the current unlocking methods. The value is the same as that of `unlockList.size()`.
unlock_list	List	The list of unlocking methods.

Description of unlock_list

Field name	Type	Description
dp_code	String	The standard DP identifier of an unlocking method.
unlock_sn	Integer	The serial number of the unlocking method.
unlock_name	String	The name of the unlocking method.
unlock_attr	Integer	The attribute of the unlocking method. Valid values: `1`: emergency `0`: normal
allocate_flag	Integer	Indicates whether a specified unlocking method has never been allocated to a user before. Valid values: `1`: yes. `0`: no.

Description of time_schedule_info

Field name	Type	Description
permanent	Boolean	Specifies whether a specified unlocking method is always valid.
effective_time	Long	The effective time.
expired_time	Long	The expiration time.
operate	String	The operation type. Valid values: `ADD` `MODIFY` `DELETE` Currently, only `MODIFY` is supported.
delivery_status	String	The response from the device. Valid values: `ONGOING` `SUCCESS` `FAILED`
schedule_details	JSON	The details of the schedule.

Description of schedule_details

Field name	Type	Description
all_day	Boolean	Indicates whether the password is valid all the day.
effective_time	Long	The effective time.
invalid_time	Long	The expiration time.
working_day	Integer	The weekly recurring field `workingDay` consists of seven bits, and each bit is 1 or 0. Bits 0 to 6 represent each day in a week from Sunday to Saturday. The schedule is run on the day with the bit value of 1. The last bit is 0. For example, Monday/Tuesday/Friday is represented as `00100110`, which equals to `38`, so the value of `working_day` is 38.

Sample response

[
    {
        "user_id":"125674",
          "uid":"ay15355889716302 **** ",
        "lock_user_id":2,
        "user_contact":"",
        "nick_name":"test",
        "avatar_url":"",
        "user_type":20,
        "back_home_notify_attr":1,
        "unlock_detail":[
            {
                "dp_code":"unlock_password",
                "open":true,
                "count":1,
                "unlock_list":[
                    {
                        "dp_code":"unlock_password",
                        "unlock_sn":3,
                        "unlock_name":"Fingerprint 3",
                        "unlock_attr":1,
                          "allocate_flag":1
                    }
                ]
            }
        ],
        "effective_flag":1,
        "time_schedule_info":{
            "permanent":true
        }
    }
]