Zigbee Lock API

Last Updated on : 2021-11-23 04:00:58download

Note: Use TYSdk.apiRequest to make API requests.

Set a gesture password

Operation

tuya.m.device.lock.gesturepwd.set

API version

1.0

Request parameter

Parameter	Data type	Description	Optional
devId	`String`	The ID of the device to be managed.	No
open	`Boolean`	Specifies whether to enable this feature.	No
password	`String`	The password to be set.	Yes

Return parameter

Parameter	Data type	Description
AtopResult	`Boolean`	Indicates whether the request is successful.

Sample request

{
 "devId" : "25230882b4e62d61b52a",
 "open" : true,
}

Verify the specified gesture password

Operation

tuya.m.device.lock.gesturepwd.validate
Verifies the gesture password that a user enters. The cloud records the number of failed attempts. If the upper limit is exceeded, the password is locked.

API version

1.0

Request parameter

Parameter	Data type	Description	Optional
devId	`String`	The ID of the device to be managed.	No
password	`String`	The password to be verified.	No

Return parameter

Parameter	Data type	Description
devId	`String`	The ID of the managed device.
uid	`String`	The UID of the user who made the request.
password	`String`	The verified password.
password	`Integer`	The type of password. Valid values: `1`: gesture password `2`: digital password
status	`Boolean`	Indicates whether the password is valid.
checkResult	`Boolean`	The result of the gesture password verification.
spareTime	`Integer`	The number of remaining attempts. Maximum value: `5`.

Sample request

{
 "devId" : "25230882b4e62d61b52a",
 "password" : "123456",
}

Sample response

{
    "result": {
      "devId":"123",
      "uid":"111",
      "password":"123456",
      "status":true,
      "checkResult":false,
      "spareTime":4
    }
}

Get the account to send a verification code

Operation

tuya.m.device.user.account.get

API version

1.0

Request parameter

Parameter	Data type	Description	Optional
devId	`String`	The ID of the device to be managed.	No

Sample request

{
  "devId" : "25230882b4e62d61b52a",
}

Sample response

{
  "result" : {
    "account":"13577778888",
    "countryCode":"86"
  },
  "t" : 1573612927418,
  "success" : true,
  "status" : "ok"
}

Send a verification code

Operation

tuya.m.device.user.verifycode.send
Sends a verification code to a specific account.

API version

1.0

Request parameter

Parameter	Data type	Description	Optional
account	`String`	The account to which the verification code is sent.	No

Sample request

{
 "account" : "hzj@qq.com",
}

Send and verify a verification code

Operation

tuya.m.device.user.verifycode.check

API version

1.0

Request parameter

Parameter	Data type	Description	Optional
account	`String`	The account to be managed.	No
code	`String`	The verification code to be verified.	No

Sample request

{
  "account" : "hzj@qq.com",
  "code" : "123456",
}

Get a list of home members

Operation

tuya.m.zigbee.member.list

API version

1.0

Delete invalid temporary unlocking methods

Operation

tuya.m.device.lock.zigbee.temppwdList.remove

API version

1.0

Request parameter

Parameter	Data type	Description	Optional
devId	`String`	The ID of the device to be managed.	No

Sample request

{
 "devId" : "25230882b4e62d61b52a",
}

Sample response

{
  "result": true,
  "t": 1550562572623,
  "success": true,
  "status": "ok"
}

Set the duress alert feature

Operation

tuya.m.scale.hijacking.add.config

API version

1.0

Request parameter

Parameter	Data type	Description	Optional
devId	`String`	The ID of the device to be managed.	No
dpId	`Integer`	The first half of the value of `unlockId`.	No
dpValue	`Integer`	The second half of the value of `unlockId`.	No

Sample request

{
  "devId" : "25230882b4e62d61b52a",
  "dpValue":"1-1",
  "dpId":"1"
}

Sample response

{
  "result":true,
  "t":1573024513335,
  "success":true,
  "status":"ok"
}

Disable the duress alert feature

Operation

tuya.m.scale.hijacking.remove.config

API version

1.0

Request parameter

Parameter	Data type	Description	Optional
devId	`String`	The ID of the device to be managed.	No
dpId	`Integer`	The first half of the value of `unlockId`.	No
dpValue	`Integer`	The second half of the value of `unlockId`.	No

Sample request

{
  "devId" : "25230882b4e62d61b52a",
  "dpValue":"1-1",
  "dpId":"1"
}

Sample response

{
  "result":true,
  "t":1573024513335,
  "success":true,
  "status":"ok"
}

Create a periodic temporary password

Description: The new version applies to new all-in-one apps of residential lock pro.

Operation

tuya.m.device.zigbee.newTempPwd.create

API version

1.0

Request parameter

Parameter	Data type	Description	Optional
devId	`String`	The ID of the device to be managed.	No
name	`String`	The name of the password.	No
effectiveTime	`String`	The time when the password takes effect.	No
invalidTime	`String`	The time when the password expires.	No
password	`String`	The password to be created.	No
schedule	`String`	The schedule that is configured for the password.	Yes
countryCode	`String`	The country code.	Yes
phone	`String`	The mobile phone number.	Yes
oneTime	`Integer`	Specifies whether a one-time password is created. Valid values: `0`: no `1`: yes	No
sendMsg	`Integer`	Specifies whether to send an SMS message. Valid values: `0`: no `1`: yes	No

Sample request

{
  "devId": "vedosoeerjfneweinqw",
  "name" : "Name",
  "password" : "123456",
  "phone" : "12345678901",
  "countryCode" : "86",
  "effectiveTime" : "1601519817000",
  "invalidTime" : "160161817000",
}

Sample response

{
  "result": "resultDO": {
		"deliveryStatus": 1,
		"devId": "123",
		"id": 111,
		"name": "testLock",
		"oneTime": 1,
		"operate": 124,
		"password": "123456",
		"phase": 1,
		"phone": "86-13575791025",
		"scheduleList": [{
			"allDay": false,
			"effectiveTime": 967,
			"invalidTime": 1270,
			"timeZoneId": "",
			"workingDay": 81
		}],
		"sendMsg": 1,
		"status": true,
		"timeZone": "",
		"tyNumber": 998,
		"uid": "0"
	},
	"success": true
}

Create a periodic temporary password

Note: The earlier versions only apply to the earlier all-in-one apps of business locks and residential locks.

Operation

tuya.m.zigbee.lock.temppwd.create

API version

1.0

Request parameter

Parameter	Data type	Description	Optional
devId	`String`	The ID of the device to be managed.	No
name	`String`	The name of the password.	No
phone	`String`	The mobile phone number.	Yes
effectiveTime	`String`	The time when the password takes effect.	No
invalidTime	`String`	The time when the password expires.	No
password	`String`	The password to be created.	No
oneTime	`Integer`	Specifies whether a one-time password is created. Valid values: `0`: no `1`: yes	No
createLimit	`Integer`	If the number of custom passwords is limited, set this parameter. User settings must follow this upper limit.	Yes

Sample request

{
  "devId": "6c4ff4cbc8022cabe134rq",
  "password": "95657EE8B6EEF10E035642F017A79B60",
  "phone": "12345678901",
  "effectiveTime": "1622179887",
  "name": "768163",
  "invalidTime": "1622262687",
  "oneTime": "0",
  "createLimit": 0
}

Sample response

{
  "result": true,
  "t": 1622179903124,
  "success": true,
  "status": "ok"
}
}

Get a list of temporary passwords

Note: The earlier versions only apply to the earlier all-in-one apps of business locks and residential locks.

Operation

tuya.m.zigbee.lock.temppwd.list

API version

1.0

Request parameter

Parameter	Data type	Description	Optional
devId	`String`	The ID of the device to be managed.	No

Return parameter

Parameter	Data type	Description
id	`Long`	The ID of the primary key.
mobile	`String`	The mobile phone number.
name	`String`	The name of the password.
effectiveTime	`String`	The time when the password takes effect.
invalidTime	`String`	The time when the password expires.
password	`String`	The returned password.
deliveryStatus	`Integer`	The delivery status. Valid values: `1`: pending confirmation `2`: confirmed successfully `3`: failed to confirm `4`: duplicated password `5`: The number of passwords exceeds the upper limit `6`: The validity period overlaps with that of another password
effective	`Integer`	The validity status. Valid values: `1`: to be effective `2`: effective `3`: about to expire `4`: expired
oneTime	`Integer`	Indicates whether a one-time password was created. Valid values: `0`: no `1`: yes
phase	`Integer`	The deletion status. Valid values: `2`: normal `3`: frozen `4`: deleted `5`: failed to delete
gmtCreate	`Integer`	The 13-digit timestamp when the password was created, in milliseconds.

Sample request

{
 "devId" : "25230882b4e62d61b52a",
 "useful" : true,
 "offset" : 0,
 "limit" : 50,
}

Sample response

{
	"result": [{
		"phase": 2,
		"effective": 3,
		"effectiveTime": 1622002358,
		"mobile": "",
		"name": "Name",
		"canDelete": false,
		"invalidTime": 1622009558,
		"id": 4233107,
		"gmtCreate": 1622002396400,
		"oneTime": 0,
		"deliveryStatus": 1
	}, {
		"phase": 2,
		"effective": 2,
		"effectiveTime": 1622001863,
		"mobile": "",
		"name": "Name",
		"canDelete": false,
		"invalidTime": 1653537863,
		"id": 4233106,
		"gmtCreate": 1622001890431,
		"oneTime": 0,
		"deliveryStatus": 2
	}],
	"t": 1622002537414,
	"success": true,
	"status": "ok"
}

Query a list of one-time temporary passwords and periodic temporary passwords

Description: The new version applies to new all-in-one apps of residential lock pro.

Operation

tuya.m.device.lock.temppwd.pagelist

API version

1.0

Request parameter

Parameter	Data type	Description	Optional
devId	`String`	The ID of the device to be managed.	No
useful	`Boolean`	Specifies whether the password is valid.	No
offset	`Integer`	The number of the entry starting from which entries are returned.	No
limit	`Integer`	The maximum number of entries to be returned starting from the offset position.	No

Sample request

{
 "devId" : "25230882b4e62d61b52a",
 "useful" : true,
 "offset" : 0,
 "limit" : 50,
}

Sample response

{
  "resultDO": {
		"datas": [{
			"deliveryStatus": 1,
			"devId": "123",
			"id": 111,
			"name": "testLock",
			"oneTime": 1,
			"operate": 124,
			"password": "123456",
			"phase": 1,
			"phone": "86-13575791025",
			"scheduleList": [{
				"allDay": false,
				"effectiveTime": 967,
				"invalidTime": 1270,
				"timeZoneId": "",
				"workingDay": 81
			}],
			"sendMsg": 1,
			"status": true,
			"timeZone": "",
			"tyNumber": 998,
			"uid": "0"
		}],
		"hasNext": false,
		"totalCount": 0
	},
	"success": true
}

Update a periodic temporary password

Operation

tuya.m.device.zigbee.newTempPwd.update

API version

1.0

Request parameter

Parameter	Data type	Description	Optional
id	`Long`	The ID of the user.	No
devId	`String`	The ID of the device to be managed.	No
name	`String`	The name of the password.	No
effectiveTime	`String`	The time when the password takes effect.	No
invalidTime	`String`	The time when the password expires.	No
password	`String`	The password to be created.	No
schedule	`String`	The schedule that is configured for the password.	Yes
countryCode	`String`	The country code.	Yes
phone	`String`	The mobile phone number.	Yes
oneTime	`Integer`	Specifies whether a one-time password is created. Valid values: `0`: no `1`: yes	No
sendMsg	`Integer`	Specifies whether to send an SMS message. Valid values: `0`: no `1`: yes	No
operate	`Integer`	The type of operation. Valid values: `125`: delete `126`: modify	No

Sample request

{
  "id": 1,
  "devId": "vedosoeerjfneweinqw",
  "name" : "Name",
  "password" : "123456",
  "phone" : "12345678901",
  "countryCode" : "86",
  "effectiveTime" : "1601519817000",
  "invalidTime" : "160161817000",
}

Sample response

{
  "result": "resultDO": {
			"deliveryStatus": 1,
			"devId": "123",
			"id": 111,
		 "name": "testLock",
			"oneTime": 1,
			"operate": 124,
			"password": "123456",
			"phase": 1,
			"phone": "86-13575791025",
			"scheduleList": [{
					"allDay": false,
					"effectiveTime": 967,
					"invalidTime": 1270,
					"timeZoneId": "",
					"workingDay": 81
			}],
			"sendMsg": 1,
			"status": true,
			"timeZone": "",
			"tyNumber": 998,
			"uid": "0"
	},
	"success": true
}

Modify, freeze, and unfreeze a temporary unlocking method

Note: The earlier versions only apply to the earlier all-in-one apps of business locks and residential locks.

Operation

tuya.m.zigbee.lock.temppwd.update

API version

1.0

Request parameter

Parameter	Data type	Description	Optional
id	`Long`	The ID of the user.	No
devId	`String`	The ID of the device to be managed.	No
operate	`Integer`	The type of operation. Valid values: `125`: delete `126`: modify `127`: freeze `128`: unfreeze	No
name	`String`	The name of the password.	No
effectiveTime	`String`	The time when the password takes effect.	No
invalidTime	`String`	The time when the password expires.	No
password	`String`	The password that is used in the unlocking method.	No
phone	`String`	The mobile phone number.	No
oneTime	`Integer`	Specifies whether a one-time password is created. Valid values: `0`: no `1`: yes	No

Sample request

{
  "id": 1,
  "devId": "vedosoeerjfneweinqw",
  "name" : "Name",
  "password" : "123456",
  "operate" : 127,
  "phone" : "12345678901",
  "countryCode" : "86",
  "effectiveTime" : "1601519817000",
  "invalidTime" : "160161817000",
}

Sample response

{
  "result": true,
  "t": 1573024513335,
  "success": true,
  "status": "ok"
}

Modify the name of a one-time password

Operation

tuya.m.device.lock.temppwd.name.update

API version

1.0

Request parameter

Parameter	Data type	Description	Optional
pwdId	`Long`	The ID of the password.	No
name	`String`	The name of the password.	No
devId	`String`	The ID of the device to be managed.	No

Sample request

{
  "devId" : "25230882b4e62d61b52a",
  "name": "Password name",
  "pwdId": 11
}

Update a temporary password name

Operation

tuya.m.device.lock.temppwd.name.update

API version

2.0

Request parameter

Parameter	Data type	Description	Optional
devId	`String`	The ID of the device to be managed.	No
pwdId	`Integer`	The ID of the unlocking method.	Yes
name	`String`	The name of the password.	Yes

Sample request

{
  "devId" : "6cc1483v89yz1t8o",
  "pwdId" : 123123,
  "name" : 'Name',
}

Sample response

{
    "result":true,
    "t":1573024513335,
    "success":true,
    "status":"ok"
}

Resend an SMS notification of a temporary password

Operation

tuya.m.device.zigbee.sms.resend

API version

1.0

Request parameter

Parameter	Data type	Description	Optional
id	`Long`	The ID of the password.	No

Sample request

{
  "devId" : "6cc1483v89yz1t8o",
}

Sample response

{
  "result": true,  // Only a value of `true` indicates that the password is assigned.
  "t": 1550562572623,
  "success": true,
  "status": "ok"
}

Query a list of alerts

Operation

tuya.m.device.lock.alarm.list

API version

1.0

Request parameter

Parameter	Data type	Description	Optional
devId	`String`	The ID of the device to be managed.	No
dpIds	`Integer`	The data point (DP).	No
offset	`Integer`	The number of the entry starting from which entries are returned.	No
limit	`Integer`	The maximum number of entries to be returned starting from the offset position.	No

Sample request

{
  "devId" : "6cc1483v89yz1t8o",
  "dpIds" : [1,2,3,4],
  "offset" : 0,
  "limit" : 50,
}

Sample response

{
  "datas":[
    {
      "devId":"7381641184f3eb715317",
      "dps":[
        {
          "56":"1-2"
        }
      ],
      "avatar":"https://images.tuyacn.com/smart/user_res/avatar/scale/no_body_icon.png",
      "userName":"Cloud",
      "gmtCreate":1567079971000,
      "uuid":"156707000591403D659FAA1D8F951049B2001C9971000",
      "userId":"0",
      "tags":0,
      "status":1
    }
  ],
  "hasNext":true,
  "totalCount":43
}

Query the unlocking history

Operation

tuya.m.scale.history.list

API version

2.0

Request parameter

Parameter	Data type	Description	Optional
devId	`String`	The ID of the device to be managed.	No
dpIds	`Integer`	The DP.	No
offset	`Integer`	The number of the entry starting from which entries are returned.	No
limit	`Integer`	The maximum number of entries to be returned starting from the offset position.	No
startTime	`Integer`	The start time of the time range to be queried.	No
endTime	`Integer`	The end time of the time range to be queried.	No

Sample request

{
  "devId" : "6cc1483v89yz1t8o",
  "dpIds" : [1,2,3,4],
  "offset" : 0,
  "limit" : 50,
  "startTime" : '',
  "endTime" : '',
}

Sample response

{
  "datas":[
    {
      "devId":"7381641184f3eb715317",
      "dps":[
        {
          "4":"0"
        }
      ],
      "avatar":"https://images.tuyacn.com/smart/user_res/avatar/scale/no_body_icon.png",
      "userName":"Cloud",
      "unlockName":"Unlocking method name"
      "gmtCreate":1567079971000,
      "uuid":"156707000591403D659FAA1D8F951049B2001C9971000",
      "userId":"0",
      "tags":0,
      "status":1
    }
  ],
  "hasNext":true,
  "totalCount":43
}

Add an unlocking method

Operation

tuya.m.device.member.opmode.add

API version

2.0

Request parameter

Parameter	Data type	Description	Optional
devId	`String`	The ID of the device to be managed.	No
userId	`String`	The ID of the user.	No
unlockId	`String`	The ID of the unlocking method.	No
unlockName	`String`	The name of the unlocking method.	No

Sample request

{
  "devId" : "25230882b4e62d61b52a",
  "userId" : '9906',
  "unlockId" : '1-2',
  "unlockName" : 'Fingerprint 02',
}

Sample response

{
    "result" : {
      "opModeId" : 47958,
      "unlockName" : "Password 40"
    },
    "t" : 1574503711145,
    "success" : true,
    "status" : "ok"
}

Prev DocWi-Fi Lock API

Next DocBluetooth LE Lock API