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

    Tuya CloudWeChat mini programEncryption and decryption toolRequest temporary key forpassword encryptionReturn temporary encryptionkey valid for 5 minutesDecrypt password with AES usingthe `accessKey` issued by platformReturn original key for passwordencryptionEncrypt original password with AESusing original keyReturn encrypted passwordCreate temporary passwordincluding ticketldReturn resultTuya CloudWeChat mini programEncryption and decryption tool

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