Integration with Firefighting Devices

This topic describes the protocol and solution used to integrate smart firefighting devices. Tuya provides the following solution to help brand owners connect smart firefighting devices to the Tuya Developer Platform.

Architecture

• The architecture is shown as follows:

  

• The commands are transferred as follows:

  

Before you start

A Tuya developer account is registered.

Cloud development project

A cloud development project is a collection of resources on the Tuya Developer Platform, including devices, APIs, and data assets. Resources distributed to different projects are isolated from each other. This section briefly describes cloud development projects. For more information about project creation and management steps, see Manage Projects.

1. Open the list of cloud development projects.

   

2. Click your created project and get the Access ID and Access Secret on the Overview tab.

   

3. Link devices.

   

Create a product

Each product created on the platform has a unique product ID (PID). The product contains all the property data of the smart device you deploy in the actual scenario, including the core and basic functional properties defined in product development.

In this step, you can define product functions and get the PID. For more information, see Create Products.

Listener for device messages

A messaging mechanism is used to notify a third-party platform of a list of projects that meet the specified criteria. Therefore, you need to subscribe to Tuya’s message service on the third-party platform. For more information, see Message Queue.

Java SDK

Go to Tuya Java SDK GitHub repository to get tokens and common APIs. You only need to change the URL and parameters.

API specifications

Environment description

• China: https://openapi.tuyacn.com
• America: https://openapi.tuyaus.com
• Europe: https://openapi.tuyaeu.com

Call the interfaces according to your region.

Request method

Request methods supported:

• GET
• PUT
• POST
• DELETE

Set the request header

The following parameters must be added to the header of any API request:

Parameter	Type	Parameter location	Description	Required
client_id	String	header	The client_id.	Yes
lang	String	header	The language. The default language is en.	No
sign	String	header	The signature that is generated by a specified signature algorithm: token-related interfaces and business-related interfaces.	Yes
sign_method	String	header	The signature digest algorithm. Set the value to HMAC-SHA256.	Yes
t	Long	header	The 13-digit standard timestamp.	Yes

Signature method

Tuya currently provides two signature algorithms for different application scenarios.

• Token related interface (v1.0/token&v1.0/token/{refresh_token}):

  sign = HMAC-SHA256(client_id + t, secret).toUpperCase()
  

• Other business interfaces:

  sign = HMAC-SHA256(client_id + access_token + t, secret).toUpperCase()
  

  • client_id: the above-mentioned Access ID.
  • secret: the above-mentioned Access Secret.
  • access_token: see Authorization in the subsequent sections.

The returned result

• The returned result on success:

  {
  	"success": true,
  	"result": {
  		//object
  	}
  }
  

• The returned result on failure:

  {
  	"success": false,
  	"code": 1010,
  	"msg": "Illegal token"
  }
  

Global error codes

Code	Error message
500	System error.
1000	The data does not exist.
1001	The secret is illegal.
1002	The access_token cannot be empty.
1003	The grant_type is illegal.
1004	The signature is illegal.
1005	The client_id is illegal.
1010	The token has expired.
1011	The token is illegal.
1012	The status is illegal.
1013	The request time is illegal.
1100	The input parameter cannot be empty.
1101	The value range is illegal.
1102	The parameter is null.

Features

Feature	Description
Request for authorization	Get authorization from Tuya for data communication.
Bind a third-party device	A third-party device is registered to Tuya’s ecosystem after an API request is made to bind the device. This allows the device to be controlled throughout Tuya’s ecosystem, and the device status and other related information can be visualized.
Unbind a third-party device	Remove a third-party device from Tuya’s ecosystem.
Update a third-party device	Update the information about a third-party device in the cloud.
Go online	Notify Tuya of the third-party device going online.
Go offline	Notify Tuya of the third-party device going offline.
Send alerts	Send alerts of the third-party device to Tuya.

Authorization APIs

Get a token

Before making API requests, you need to get the access_token in the first place and access the business interface using the acess_token. According to the provided client_id and secret signature, the /v1.0/token interface is called to get access_token from the server. When you request a business interface, for the calculation of sign, see Signature algorithm for requesting a business interface.

• sign signature algorithm

  To get a token, the signature is generated based on the following rules:

  sign = HMAC-SHA256(client_id + t + nonce + stringToSign, secret).toUpperCase()
  

  The token is valid for five minutes after it is generated for each request URL. For more information about token management, see Sign Requests.

• API endpoint

  GET /v1.0/token
  

• header parameter

  Parameter	Type	Parameter type	Description	Required
  client_id	String	header	The client_id.	Yes
  sign	String	header	The signature that is generated by the above-mentioned signature algorithm.	Yes
  nonce	String	header	The universally unique identifier (UUID) generated for each API request. Combined with the timestamp, the UUID ensures the uniqueness of API requests.	No
  stringToSign	String	header	The signature string.	Yes
  sign_method	String	header	The signature type. Default value: HMAC-SHA256.	Yes
  t	Long	header	The 13-digit standard timestamp.	Yes

• Request parameter

  Parameter	Type	Parameter type	Description	Required
  grant_type	Integer	URL	The authorization type. Valid values: 1: simple mode. 2: license mode.	Yes

• stringToSign signature string

  String stringToSign=
  HTTPMethod + "\n" +
  Content-SHA256 + "\n" +
  Headers + "\n" +
  Url
  

• Sample request

  GET /v1.0/token?grant_type=1
  

• Sample SDK for Java

  TuyaClient tuyaClient = new TuyaClient(accessId, accessKey, RegionEnum.CN);
  String url = ServerEnum.CN_ONLINE.getUrl() + "/v1.0/token";
  HashMap<String, String> hashMap = new HashMap<String, String>();
  hashMap.put("grant_type", "1");
  tuyaClient.commonHttpRequest(url, HttpMethod.GET, hashMap, null);
  

• Response parameter

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

• Description of result

  Parameter	Type	Description
  access_token	String	The access token.
  expire_time	Integer	The time when the token expires. Unit: seconds.
  refresh_token	String	It is used to refresh the access_token.

• Sample response

  • Returned result on success:

    {
    "success": true,
    "t": 1575699977724,
    "result": {
    	"uid": "ay1573712013719u5***",
    	"access_token": "6a5629b9285703a1f05f667757dd6***",
    	"expire_time": 7200,
    	"refresh_token": "adbc6363ef181dcc244769e4237d9***"
    }
    }
    

  • Returned result on failure:

    {
    	"success": false,
    	"code": 100323,
    	"msg": "Illegal token"
    }
    

Refresh a token

The access_token is valid for 2 hours. After the expiration, you need to call the token refresh interface to get a new access_token, and use the new access_token to access the business interface.

• sign signature algorithm

  To get a token, the signature is generated based on the following rules:

  sign = HMAC-SHA256(client_id + t + nonce + stringToSign, secret).toUpperCase()
  

  The token is valid for five minutes after it is generated for each request URL. For more information about token management, see Sign Requests.

• stringToSign signature string

  String stringToSign=
  HTTPMethod + "\n" +
  Content-SHA256 + "\n" +
  Headers + "\n" +
  Url
  

• API endpoint

  GET /v1.0/token/{refresh_token}
  

• header parameter

  Parameter	Type	Parameter type	Description	Required
  client_id	String	header	The client_id.	Yes
  sign	String	header	The signature that is generated by the above-mentioned signature algorithm.	Yes
  nonce	String	header	The universally unique identifier (UUID) generated for each API request. Combined with the timestamp, the UUID ensures the uniqueness of API requests.	No
  stringToSign	String	header	The signature string.	Yes
  sign_method	String	header	The signature type. Default value: HMAC-SHA256.	Yes
  t	Long	header	The 13-digit standard timestamp.	Yes

• Request parameter

  Parameter	Type	Parameter type	Description	Required
  refresh_token	String	URI	The returned result of /v1.0/token.	Yes

• Sample request

  GET /v1.0/token/35e0dd4b0f9dfb87c320414a4c190***
  

• Sample SDK for Java

  String url = ServerEnum.CN_ONLINE.getUrl() + "/v1.0/token/"+ token;
  TuyaClient tuyaClient = new TuyaClient(accessId, accessKey, RegionEnum.CN);
  tuyaClient.commonHttpRequest(url, HttpMethod.GET, null, null);
  

• Response parameter

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

• Description of result

  Parameter	Type	Description
  access_token	String	The access token.
  expire_time	Integer	The time when the token expires. Unit: seconds.
  refresh_token	String	It is used to refresh the access_token.

• Sample response

  	{
  	"success": true,
  	"t": 1575701937231,
  	"result": {
  		 "uid": "ay1573712013719u5***",
  		 "access_token": "4bbdc25b6f360b8e31125ed1e3653***",
  		 "expire_time": 7200,
  		 "refresh_token": "adbc6363ef181dcc244769e4237d9***"
  	}
  	}
  

Device connection

Bind a third-party device

After the device is paired with the third-party cloud service, call this interface to register the device information with Tuya.

• Enter the product information: Before calling this interface, make sure the product information of the device has been entered on the Tuya Developer Platform, and the product ID (PID) has been generated. For more information, see Create Products.
• Automatically create Tuya’s user ID: When registering the device, you need to specify the username in Tuya’s ecosystem. Tuya will automatically create a user ID and bind it with the third-party device.
• Bind the device: After the device is paired with the third-party cloud service, the cloud service calls this interface to register the device information with Tuya. This interface is used to register a device connected to the third-party cloud without a gateway, as well as a gateway and its sub-devices.

After the device is bound, the app in Tuya’s ecosystem can be used to control the device and view the device status and other related information.

API endpoint

POST /v1.0/3rdcloud/devices/{3rd_cloud_device_id}/bind

header parameter

Parameter	Type	Parameter type	Description	Required
access_token	String	header	The access token.	Yes
client_id	String	header	The client_id.	Yes
sign	String	header	See Signature algorithm for requesting a business interface.	Yes
sign_method	String	header	The signature type. Default value: HMAC-SHA256.	Yes
t	Long	header	The 13-digit standard timestamp.	Yes
Content-Type	String	header	Default value: application/json.	Yes

Request parameter

Parameter	Type	Parameter type	Description	Required
3rd_cloud_device_id	String	URI	The unique ID of a third-party device. 3rd_cloud_device_id can be a unique readable identifier of the device, such as device SN, MAC address, or IMEI.	Yes
tuya_product_id	String	BODY	The ID of a Tuya product.	Yes
app_schema	String	BODY	The identifier of a Tuya application.	No
tuya_username	String	BODY	The unique username in Tuya’s ecosystem to identify a user.	No
properties	Object	BODY	The property of a Tuya device.	No
ext_properties	List	BODY	The extension information depending on the specified business.	Yes

• properties parameter:

  Parameter	Type	Parameter type	Description	Required
  Name	String	BODY	The device name.	No
  lon	Double	BODY	The longitude.	No
  lat	Double	BODY	The latitude.	No
  ip	String	BODY	The IP address.	No

• ext_properties parameter:

  Parameter	Type	Parameter type	Description	Required
  Code	String	BODY	The identifier.	Yes
  value	String	BODY	The value.	Yes

  The ext_properties field is described as follows:

  [{"code":"cid","value":"123123***"},
  {"code":"vendorCode","value":"nite"},
  {"code":"deviceIp","value": "192.168.*.*"},
  {"code":"macAddress","value": "MAC address"},
  {"code":"commType","value":"HTTP"},
  {"code":"lat","value": "30.20***"},
  {"code":"lon","value": "120.21***"},
  {"code":"installLocation","value":"Installation location"},
  {"code":"outProjectId","value":"Community ID"},
  {"code":"deviceDesc","value":"Device description"},
  {"code":"extendData","value":"{\"userTransUnitNum\":\"000.000.000.000.000.155\"}"},
  {"code":"deviceName","value":"Device name"},
  {"code":"isGateway","value":true}
  ]
  

The fields are described as follows:

ext_properties code	Description	Required
cid	The ID of a specified third-party device. It is the same as 3rd_cloud_device_id. It can be a unique readable identifier of the device, such as device SN, MAC address, or IMEI.	Yes
vendorCode	The code of a specified third-party supplier.	Yes
outProjectId	The ID of a specified community where the third-party device is located.	Yes
deviceIp	The IP address of a specified device. Example: 192.168.1.1.	No
macAddress	The MAC address of a specified device.	No
commType	The communication type, such as HTTP, MQTT, and RS-485 electric signal.	No
lat	The latitude.	Yes
lon	The longitude.	Yes
installLocation	The readable installation location.	Yes
deviceName	The readable device name.	Yes
deviceDesc	The readable device description. Example: wireless pressure transmitter.	Yes
extendData	The extension information in form of a JSON string and others.	No
isGateway	A Boolean value indicating whether it is a user data transmission device. Enter true for a user data transmission device. You can enter nothing for other devices.	No

Sample request

POST /v1.0/3rdcloud/devices/27511006b4e62d4bd200/bind
{
    "app_schema":"tencentiot",
    "tuya_username": "0123456***",
    "tuya_product_id": "nr1k9ptidpov***",
    "ext_properties":[{"code":"deviceName","value":"Device name"},{"code":"installLocation","value":"Huace***, Jiangdun Road, Xihu District, Hangzhou"}]

}

Response parameter

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

Description of result

Parameter	Type	Description
tuya_device_id	String	The ID of a Tuya device.
tuya_user_id	String	Tuya user ID.

Sample request

{
    "success": true,
    "t": 1561456817168,
    "result": {
      "tuya_device_id":"",
      "tuya_user_id":""
    }
}

Bind third-party devices in bulk

After the devices are paired with the third-party cloud service, call this interface to register the devices with Tuya in bulk.

• Enter the product information: Before calling this interface, make sure the product information of the device has been entered on the Tuya Developer Platform, and the PID has been generated. For more information, see Create Products.
• Automatically create Tuya’s user ID: When registering the device, you need to specify the username in Tuya’s ecosystem. Tuya will automatically create a user ID and bind it with the third-party device.
• Bind the devices: After the devices are paired with the third-party cloud service, the third-party cloud service calls this interface to register the devices with Tuya in bulk. This interface is used to register multiple devices directly connected to the third-party cloud, as well as gateway devices.

After the device is bound, the app in Tuya’s ecosystem can be used to control the device and view the device status and other related information.

API endpoint

POST /v1.0/3rdcloud/devices/actions/bind

header parameter

Parameter	Type	Parameter type	Description	Required
access_token	String	header	The access token.	Yes
client_id	String	header	The client_id.	Yes
sign	String	header	See Signature algorithm for requesting a business interface.	Yes
sign_method	String	header	The signature type. Default value: HMAC-SHA256.	Yes
t	Long	header	The 13-digit standard timestamp.	Yes
Content-Type	String	header	Default value: application/json.	Yes

Request parameter

Parameter	Type	Parameter type	Description	Required
tuya_product_id	String	BODY	The ID of a Tuya product.	Yes
app_schema	String	BODY	The identifier of a Tuya application.	No
tuya_username	String	BODY	The username in Tuya’s ecosystem. The unique identifier assigned when a third-party device is bound.	No
devices	List	BODY	The property of a Tuya device. Up to 20 devices can be called at one operation.	Yes

• devices properties:

  Parameter	Type	Description	Required
  id	String	The ID of a specified third-party device. It can be a unique readable identifier of the device, such as device SN, MAC address, or IMEI.	Yes
  lon	String	The longitude of a specified device.	No
  lat	String	The latitude of a specified device.	No
  Name	String	The device name.	No
  ip	String	The IP address of a specified device.	No
  ext	String	The extension information about a specified device. See the following table.	Yes

• ext properties:

  Parameter	Type	Parameter type	Description	Required
  Code	String	BODY	The identifier.	Yes
  value	String	BODY	The value.	Yes

  The ext_properties field is described as follows:

  [{"code":"cid","value":"123123***"},
  {"code":"vendorCode","value":"nite"},
  {"code":"deviceIp","value": "192.168.1.*"},
  {"code":"macAddress","value": "MAC address"},
  {"code":"commType","value":"HTTP"},
  {"code":"lat","value": "30.2***"},
  {"code":"lon","value": "120.21***"},
  {"code":"installLocation","value":"Installation location"},
  {"code":"outProjectId","value":"Community ID"},
  {"code":"deviceDesc","value":"Device description"},
  {"code":"extendData","value":"{\"userTransUnitNum\":\"000.000.000.000.000.155\"}"},
  {"code":"deviceName","value":"Device name"},
  {"code":"isGateway","value":true}
  ]
  

The fields are described as follows:

ext_properties code	Description	Required
cid	The ID of a specified third-party device. It is the same as 3rd_cloud_device_id. It can be a unique readable identifier of the device, such as device SN, MAC address, or IMEI.	Yes
vendorCode	The code of a specified third-party supplier.	Yes
outProjectId	The ID of a specified community where the third-party device is located.	Yes
deviceIp	The IP address of a specified device. Example: 192.168.1.1.	No
macAddress	The MAC address of a specified device.	No
commType	The communication type, such as HTTP, MQTT, and RS-485 electric signal.	No
lat	The latitude.	Yes
lon	The longitude.	Yes
installLocation	The readable installation location.	Yes
deviceName	The readable device name.	Yes
deviceDesc	The readable device description. Example: wireless pressure transmitter.	Yes
extendData	The extension information in form of a JSON string and others.	No
isGateway	A Boolean value indicating whether it is a user data transmission device. Enter true for a user data transmission device. You can enter nothing for other devices.	No

Sample request

POST /v1.0/3rdcloud/devices/actions/bind
{
    "tuya_product_id": "wazil4rsq7cl***",
    "devices": [
        {
            "id": "qinfengte***",
            "ext": "[{\"code\": \"cid\",\"value\": \"**********\"},{\"code\": \"vendorCode\",\"value\": \"****\"},{\"code\": \"deviceIp\",\"value\": \"1*********3\"},{\"code\": \"macAddress\",\"value\": \"MAC address\"},{\"code\": \"commType\",\"value\": \"HTTP\"},{\"code\": \"lat\",\"value\": \"30.2084\"},{\"code\": \"lon\",\"value\": \"120.21201\"},{\"code\": \"installLocation\", \"value\": \"Installation location\"},{\"code\": \"outProjectId\",\"value\": \"a***********3\"},{\"code\": \"deviceDesc\",\"value\": \"Test device\"},{\"code\": \"extendData\",\"value\": \"\"},{\"code\": \"deviceName\",\"value\": \"Test device\"}]"
        }
    ]
}

Response parameter

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

Description of result

Parameter	Type	Description
failed_bind_result	List	The list of devices failed in pairing.
success_bind_result	List	The list of paired devices.

• Description of success_bind_result

  Parameter	Type	Description
  3rd_device_id	String	The ID of a specified third-party device.
  tuya_device_id	String	The ID of a Tuya device.

• Description of failed_bind_result

  Parameter	Type	Description
  3rd_device_id	String	The ID of a specified third-party device.
  failed_reason	String	The reason for failure.

Sample request

{
    "result": {
        "failed_bind_result": [],
        "success_bind_result": [
            {
                "3rd_device_id": "",
                "tuya_device_id": ""
            }
        ]
    },
    "success": true,
    "t": 1635845117***
}

Bind a third-party sub-device

After the sub-device is successfully paired with the third-party cloud service, call this interface to register the sub-device information with Tuya.

• Enter the product information: Before calling this interface, make sure the product information of the device has been entered on the Tuya Developer Platform, and the product ID (PID) has been generated. For more information, see Create Products.
• Automatically create Tuya’s user ID: When registering the device, you need to specify the username in Tuya’s ecosystem. Tuya will automatically create a user ID and bind it with the third-party device.
• Bind the sub-device: After the sub-device is successfully paired with the third-party cloud service, this cloud service calls this interface to register the sub-device information with Tuya.

After the device is bound, the app in Tuya’s ecosystem can be used to control the device and view the device status and other related information.

API endpoint

POST /v1.0/3rdcloud/devices/{3rd_cloud_device_id}/sub/bind

header parameter

Parameter	Type	Parameter type	Description	Required
access_token	String	header	The access token.	Yes
client_id	String	header	The client_id.	Yes
sign	String	header	See Signature algorithm for requesting a business interface.	Yes
sign_method	String	header	The signature type. Default value: HMAC-SHA256.	Yes
t	Long	header	The 13-digit standard timestamp.	Yes
Content-Type	String	header	Default value: application/json.	Yes

Request parameter

Parameter	Type	Parameter type	Description	Required
3rd_cloud_device_id	String	URI	The sub-device ID in a third-party cloud.	Yes
tuya_product_id	String	BODY	The ID of a Tuya product.	Yes
app_schema	String	BODY	The identifier of a Tuya application.	No
tuya_username	String	BODY	The username in Tuya’s ecosystem. The unique identifier assigned when a third-party device is bound.	No
properties	Object	BODY	The property of a Tuya device.	No
ext_properties	List	BODY	The extension information depending on the specified business.	No

• properties parameter:

  Parameter	Type	Parameter type	Description	Required
  Name	String	BODY	The name of a specified sub-device.	No
  lon	Double	BODY	The longitude.	No
  lat	Double	BODY	The latitude.	No
  ip	String	BODY	The IP address.	No
  gatewayId	String	BODY	The same as 3rd_cloud_device_id of a user data transmission device.	Yes

• ext_properties properties:

  Parameter	Type	Parameter type	Description	Required
  Code	String	BODY	The identifier.	Yes
  value	String	BODY	The value.	Yes

  The ext_properties field is described as follows:

  [{"code":"cid","value":"123123***"},
  {"code":"vendorCode","value":"nite"},
  {"code":"deviceIp","value": "192.168.*.*"},
  {"code":"macAddress","value": "MAC address"},
  {"code":"commType","value":"HTTP"},
  {"code":"lat","value": "30.2***"},
  {"code":"lon","value": "120.21***"},
  {"code":"installLocation","value":"Installation location"},
  {"code":"outProjectId","value":"Community ID"},
  {"code":"deviceDesc","value":"Device description"},
  {"code":"extendData","value":"{\"userTransUnitNum\":\"000.000.000.000.000.155\",\"fireControlUnitNum\":\"000.000\",\"deviceUnitNum\":\"000.001.001.000\"}"},
  {"code":"deviceName","value":"Device name"}
  ]
  

The fields are described as follows:

ext_properties code	Description	Required
cid	The ID of a specified third-party device. It is the same as 3rd_cloud_device_id. It can be a unique readable identifier of the device, such as device SN, MAC address, or IMEI.	Yes
vendorCode	The code of a specified third-party supplier in English. Enter the fixed value neat.	Yes
outProjectId	The ID of a specified community where the third-party device is located. The unit ID of a third-party manufacturer can be entered.	Yes
deviceIp	The IP address of a specified device. Example: 192.168.1.1.	No
macAddress	The MAC address of a specified device.	No
commType	The communication type, such as HTTP, MQTT, and RS-485 electric signal.	No
lat	The latitude.	Yes
lon	The longitude.	Yes
installLocation	The readable installation location.	Yes
deviceName	The readable device name.	Yes
deviceDesc	The readable device description. Example: wireless pressure transmitter.	Yes
extendData	The extension information in form of a JSON string and others.	No

Sample request

POST /v1.0/3rdcloud/devices/27511006b4e62d4bd200/sub/bind
{
    "app_schema":"tencentiot",
    "tuya_username": "012345***",
    "tuya_product_id": "nr1k9ptidpov***",
    "ext_properties":[
       {"code":"deviceName","value":"Device name"},
       {"code":"installLocation","value":"Huace Center***, Jiangdun Road, Xihu District, Hangzhou"}
    ]
}

Response parameter

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

Description of result

Parameter	Type	Description
tuya_device_id	String	The ID of a Tuya device.
tuya_user_id	String	Tuya user ID.

Sample request

{
    "success": true,
    "t": 1561456817***,
    "result": {
      "tuya_device_id":"",
      "tuya_user_id":""
    }
}

Bind third-party sub-devices in bulk

After the sub-devices are paired with the third-party cloud service, call this interface to register the sub-devices with Tuya in bulk.

• Enter the product information: Before calling this interface, make sure the product information of the device has been entered on the Tuya Developer Platform, and the PID has been generated. For more information, see Create Products.
• Automatically create Tuya’s user ID: When registering the device, you need to specify the username in Tuya’s ecosystem. Tuya will automatically create a user ID and bind it with the third-party device.
• Bind the sub-devices: After the sub-devices are paired with the third-party cloud service, thicloud service calls this interface to register the sub-devices with Tuya in bulk.

After the device is bound, the app in Tuya’s ecosystem can be used to control the device and view the device status and other related information.

API endpoint

POST /v1.0/3rdcloud/sub-devices/actions/bind

header parameter

Parameter	Type	Parameter type	Description	Required
access_token	String	header	The access token.	Yes
client_id	String	header	The client_id.	Yes
sign	String	header	See Signature algorithm for requesting a business interface.	Yes
sign_method	String	header	The signature type. Default value: HMAC-SHA256.	Yes
t	Long	header	The 13-digit standard timestamp.	Yes
Content-Type	String	header	Default value: application/json.	Yes

Request parameter

Parameter	Type	Parameter type	Description	Required
tuya_product_id	String	BODY	The ID of a Tuya product.	Yes
app_schema	String	BODY	The identifier of a Tuya application.	No
tuya_username	String	BODY	The username in Tuya’s ecosystem. The unique identifier assigned when a third-party device is bound.	No
devices	List	BODY	The property of a Tuya device. Up to 20 devices can be called at one operation.	Yes

• properties parameter:

  Parameter	Type	Parameter type	Description	Required
  Name	String	BODY	The name of a specified sub-device.	No
  lon	Double	BODY	The longitude.	No
  lat	Double	BODY	The latitude.	No
  ip	String	BODY	The IP address.	No
  gatewayId	String	BODY	The same as 3rd_cloud_device_id of a user data transmission device.	Yes
  ext	String	BODY	The extension information about a specified device. See the following table.	Yes

• ext parameter:

  Parameter	Type	Parameter type	Description	Required
  Code	String	BODY	The identifier.	Yes
  value	String	BODY	The value.	Yes

  The ext_properties field is described as follows:

  [{"code":"cid","value":"123123***"},
  {"code":"vendorCode","value":"nite"},
  {"code":"deviceIp","value": "192.168.*.*"},
  {"code":"macAddress","value": "MAC address"},
  {"code":"commType","value":"HTTP"},
  {"code":"lat","value": "30.2***"},
  {"code":"lon","value": "120.21***"},
  {"code":"installLocation","value":"Installation location"},
  {"code":"outProjectId","value":"Community ID"},
  {"code":"deviceDesc","value":"Device description"},
  {"code":"extendData","value":"{\"userTransUnitNum\":\"000.000.000.000.000.155\",\"fireControlUnitNum\":\"000.000\",\"deviceUnitNum\":\"000.001.001.000\"}"},
  {"code":"deviceName","value":"Device name"}
  ]
  

The fields are described as follows:

ext_properties code	Description	Required
cid	The ID of a specified third-party device. It is the same as 3rd_cloud_device_id. It can be a unique readable identifier of the device, such as device SN, MAC address, or IMEI.	Yes
vendorCode	The code of a specified third-party supplier in English. Enter the fixed value neat.	Yes
outProjectId	The ID of a specified community where the third-party device is located. The unit ID of a third-party manufacturer can be entered.	Yes
deviceIp	The IP address of a specified device. Example: 192.168.1.1.	No
macAddress	The MAC address of a specified device.	No
commType	The communication type, such as HTTP, MQTT, and RS-485 electric signal.	No
lat	The latitude.	Yes
lon	The longitude.	Yes
installLocation	The readable installation location.	Yes
deviceName	The readable device name.	Yes
deviceDesc	The readable device description. Example: wireless pressure transmitter.	Yes
extendData	The extension information in form of a JSON string and others.	No

Sample request

POST /v1.0/3rdcloud/sub-devices/actions/bind
{
    "tuya_product_id": "123***",
    "devices": [
        {
            "id": "1223***",
            "gatewayId": "123***",
            "lon": "",
            "lat": "",
            "name": "",
            "ip": "",
            "ext":"[{\"code\": \"cid\",\"value\": \"123***\"},{\"code\": \"vendorCode\",                    \"value\": \"123***\"},{\"code\": \"deviceIp\",\"value\": \"\"},{\"code\": \"macAddress\",\"value\": \"MAC address\"},{\"code\": \"commType\",\"value\": \"HTTP\"},{\"code\": \"lat\",\"value\": \"30.2084\"},{\"code\": \"lon\",\"value\": \"120.21201\"},{\"code\": \"installLocation\",\"value\": \"\"},{ \"code\":\"outProjectId\",\"value\": \"a123***\"},{\"code\": \"deviceDesc\",\"value\": \"Test sub-device\"},{\"code\": \"extendData\",\"value\": \"\\\"userTransUnitNum\\\":\\\"000.000.000.000.000.001\\\",\\\"fireControlUnitNum\\\":\\\"000.000\\\",\\\"deviceUnitNum\\\":\\\"000.001.001.000\\\"}\"},{\"code\": \"deviceName\",\"value\": \"Test third-party sub-device\"}]"
        }
    ]
}

Response parameter

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

Description of result

Parameter	Type	Description
failed_bind_result	List	The list of devices failed in pairing.
success_bind_result	List	The list of paired devices.

• Description of success_bind_result

  Parameter	Type	Description
  3rd_device_id	String	The ID of a specified third-party device.
  tuya_device_id	String	The ID of a Tuya device.

• Description of failed_bind_result

  Parameter	Type	Description
  3rd_device_id	String	The ID of a specified third-party device.
  failed_reason	String	The reason for failure.

Sample request

{
    "success": true,
    "t": 156145681***,
    "result": {
      "failed_bind_result":[],
      "success_bind_result":[
      	"3rd_device_id":"123***",
        "tuya_device_id":"123***"
      ]
    }
}

Update a third-party device

After a third-party device is registered, you can update the device information as needed.

API endpoint

PUT /v1.0/3rdcloud/devices/{3rd_cloud_device_id}

header parameter

Parameter	Type	Parameter type	Description	Required
access_token	String	header	The access token.	Yes
client_id	String	header	The client_id.	Yes
sign	String	header	See Signature algorithm for requesting a business interface.	Yes
sign_method	String	header	The signature type. Default value: HMAC-SHA256.	Yes
t	Long	header	The 13-digit standard timestamp.	Yes
Content-Type	String	header	Default value: application/json.	Yes

Request parameter

Parameter	Type	Parameter type	Description	Required
3rd_cloud_device_id	String	URI	The device ID in a third-party cloud.	Yes
tuya_product_id	String	BODY	The ID of a Tuya product.	Yes
properties	Object	BODY	The property of a Tuya device.	No
ext_properties	List	BODY	The extended device properties.	No

• properties parameter:

  Parameter	Type	Parameter type	Description	Required
  Name	String	BODY	The device name.	No
  lon	Double	BODY	The longitude.	No
  lat	Double	BODY	The latitude.	No
  ip	String	BODY	The IP address.	No

• ext_properties parameter:

  Parameter	Type	Parameter type	Description	Required
  Code	String	BODY	The identifier.	Yes
  value	String	BODY	The value.	Yes
  Name	String	BODY	The name.	No

  The ext_properties field is described as follows:

  [{"code":"vendorCode","value":"neat","name":"The code of a specified third-party supplier"},
  {"code":"deviceName","value":"Third-party device name","name":"Third-party device name"},
  {"code":"deviceIp","value": "192.168.1.1","Device ID"},
  {"code":"deviceDesc","value":"Device description","name":"Device description"},
  {"code":"macAddress","value": "MAC address","name":"MAC address"},
  {"code":"commType","value":"HTTP","name":"Communication type (HTTP, MQTT, RS-485 electric signal)"},
  {"code":"installLocation","value":"Installation location","name":"Installation location"},
  {"code":"lat","value": "30.2084","name":"Latitude"},
  {"code":"lon","value": "120.21201","name":"Longitude"},
  {"code":"extendData","value":"Extension information if any","name":"Extension information"}
  ]
  

The fields are described as follows:

ext_properties code	Description	Required
vendorCode	The code of a specified third-party supplier in English. Enter the fixed value neat.	Yes
deviceIp	The IP address of a specified device. Example: 192.168.1.1.	No
macAddress	The MAC address of a specified device.	No
commType	The communication type, such as HTTP, MQTT, and RS-485 electric signal.	No
lat	The latitude.	Yes
lon	The longitude.	Yes
installLocation	The readable installation location.	Yes
deviceName	The readable device name.	Yes
deviceDesc	The readable device description. Example: wireless pressure transmitter.	Yes
extendData	The extension information in form of a JSON string and others.	No

Sample request

PUT /v1.0/3rdcloud/devices/27511006b4e62d4bd200
{
    "properties":{
        "name":"Test device",
        "lon":39.904***,
        "lat":116.407***,
        "ip":"124.156.99.***"
    },
    "ext_properties":[
        {
            "code":"vendorCode",
            "value":"neat",
            "name":"Code of a third-party supplier"
        },
        {
            "code":"installLocation",
            "value":"Huace Center***, Jiangdun Road, Xihu District, Hangzhou",
            "name":"Address"
        }
    ]
}

Response parameter

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

Sample response

{
    "success": true,
    "t": 1561456817***,
    "result": true
}

Unbind a third-party device

Unbind a third-party device from Tuya based on the following scenarios:

• The device is reset.
• The device is removed from an app in Tuya’s ecosystem or third-party cloud service.

API endpoint

DELETE /v1.0/3rdcloud/devices/{third_party_device_id}/unbind

header parameter

Parameter	Type	Parameter type	Description	Required
access_token	String	header	The access token.	Yes
client_id	String	header	The client_id.	Yes
sign	String	header	See Signature algorithm for requesting a business interface.	Yes
sign_method	String	header	The signature type. Default value: HMAC-SHA256.	Yes
t	Long	header	The 13-digit standard timestamp.	Yes
Content-Type	String	header	Default value: application/json.	Yes

Request parameter

Parameter	Type	Parameter type	Description	Required
3rd_cloud_device_id	String	URI	The device ID in a third-party cloud.	Yes

Sample request

DELETE /v1.0/3rdcloud/devices/27511006b4e62d4bd200/unbind

Response parameter

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

Sample request

{
    "success": true,
    "t": 1561456817***,
    "result": true
}

Go online

The third-party cloud service synchronizes the going-online event of a specified device to Tuya based on the network connection of the device. Tuya’s app updates the online status of the device accordingly.

API endpoint

PUT /v1.0/3rdcloud/devices/{3rd_cloud_device_id}/online

header parameter

Parameter	Type	Parameter type	Description	Required
access_token	String	header	The access token.	Yes
client_id	String	header	The client_id.	Yes
sign	String	header	See Signature algorithm for requesting a business interface.	Yes
sign_method	String	header	The signature type. Default value: HMAC-SHA256.	Yes
t	Long	header	The 13-digit standard timestamp.	Yes
Content-Type	String	header	Default value: application/json.	Yes

Request parameter

Parameter	Type	Parameter type	Description	Required
3rd_cloud_device_id	String	URI	The device ID in a third-party cloud.	Yes

Sample request

PUT /v1.0/3rdcloud/devices/27511006b4e62d4bd200/online

Response parameter

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

Sample response

{
    "success": true,
    "t": 156145681***,
    "result": true
}

Go offline

The third-party cloud service synchronizes the going-offline event of a specified device to Tuya based on the network connection of the device. Tuya’s app updates the offline status of the device accordingly.

API endpoint

PUT /v1.0/3rdcloud/devices/{3rd_cloud_device_id}/offline

header parameter

Parameter	Type	Parameter type	Description	Required
access_token	String	header	The access token.	Yes
client_id	String	header	The client_id.	Yes
sign	String	header	See Signature algorithm for requesting a business interface.	Yes
sign_method	String	header	The signature type. Default value: HMAC-SHA256.	Yes
t	Long	header	The 13-digit standard timestamp.	Yes
Content-Type	String	header	Default value: application/json.	Yes

Request parameter

Parameter	Type	Parameter type	Description	Required
3rd_cloud_device_id	String	URI	The device ID in a third-party cloud.	Yes

Sample request

PUT /v1.0/3rdcloud/devices/27511006b4e62d4bd200/offline

Response parameter

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

Sample request

{
    "success": true,
    "t": 156145681***,
    "result": true
}

Report events of a third-party device

When an event occurs in a device of the third-party cloud, this API is called to notify Tuya.

API endpoint

POST /v1.0/3rdcloud/devices/{3rd_cloud_device_id}/status

header parameter

Parameter	Type	Parameter type	Description	Required
access_token	String	header	The access token.	Yes
client_id	String	header	The client_id.	Yes
sign	String	header	See Signature algorithm for requesting a business interface.	Yes
sign_method	String	header	The signature type. Default value: HMAC-SHA256.	Yes
t	Long	header	The 13-digit standard timestamp.	Yes
Content-Type	String	header	Default value: application/json.	Yes

Request parameter

Parameter	Type	Parameter type	Description	Required
3rd_cloud_device_id	String	URI	The device ID in a third-party cloud.	Yes
timestamp	Long	BODY	The time when the third-party device status is changed, which is accurate to seconds.	Yes
status	List	BODY	The data of device status.	Yes

• Description of status

  Parameter	Type	Description
  Code	String	The code of a specified device function.
  value	String	The value of a specified device function.

• status content

  Code	value	Function	Data type	Description
  alarm_trace_id	Unique event ID (productId + snowflake algorithm)	Alarm event ID	String	It is used to update the event processing result alarm_result_content after an alarm is triggered.
  alarm_event_content	Description of content such as smoke concentration exceeding threshold	Alarm content description	String	Describe the content of an alarm.
  fire_alarm_type	Alarm type of firefighting device	Alarm type	Enum	{“range”:[“fire_alarm”,“device_fault”,“device_alarm”,“others”]}. Fire alarm, device failure (low battery), and device alarm.
  alarm_trace_time	13-digit timestamp in milliseconds	Event occurrence time	String	The timestamp when the event occurs. Unit: in milliseconds.
  alarm_result_content	Processed/device failure	Event result	String	Describe the event processing result. The specific content is defined by the third-party platform. This document only provides an example.
  alarm_value	Data type	Event value	float	The value at the time of the alarm. Note: All values need to be multiplied by 10,000 and converted to integers. Example: 36.5 is passed to Tuya as 365,000, and 37.55 is passed to Tuya as 375,500. The value is multiplied by 10,000 and rounded up.) Value range: -1,000,000,000 to 1,000,000,000.
  alarm_unit	Unit description	Event unit	String	The unit of an alarm. It is related to the event value, such as degree Celsius.
  alarm_process_time	13-digit timestamp in milliseconds	Alarm processing time	String	The timestamp when an alarm is processed. Unit: in milliseconds.

Sample request

POST /v1.0/3rdcloud/devices/27511006b4e62d4bd200/status
{
    "timestamp":1592920221,
    "status": [
        {
            "code": "alarm_trace_id",
            "value": "productId+snowflake algorithm"
        },
        {
            "code": "alarm_event_content",
            "value": "Reach temperature threshold"
        },
        {
            "code": "fire_alarm_type",
            "value": "fire_warning"
        },
        {
            "code": "alarm_trace_time",
            "value": "1592722282***"
        },
        {
            "code": "alarm_result_content",
            "value": "Processed"
        },
        {
            "code": "alarm_value",
            "value": 50
        },
        {
            "code": "alarm_unit",
            "value": "Degree Celsius"
        },
        {
            "code": "alarm_process_time",
            "value": "1592722282***"
        }
    ]
}

Response parameter

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

Sample response

{
    "success": true,
    "t": 1561456817***,
    "result": true
}

Definition of testing data dpcode (status content)

Code	value	Function	Data type	Description
monitor_data	Code of test item	Code of test item	String	The code of a specified test item to be defined by the manufacturer. Simple and easy-to-read English words or phrases are preferred.
monitor_name	Name of test item	Name of test item	String	The name of a specified test item in Chinese.
monitor_value	Value of test data	Test value	Int	Valid values: -10000 to 100000. No more than 4 decimal places.
monitor_unit	Unit of test data	Test unit	String	The unit name of a specified test item.
monitor_time_data	13-digit timestamp in milliseconds	Test time	String	The time when the data of a specified test item is generated.

Sample request

POST /v1.0/3rdcloud/devices/27511006b4e62d4bd200/status
{
    "timestamp":1592920221,
    "status": [
        {
            "code": "monitor_data",
            "value": "voltage"
        },
        {
            "code": "monitor_name",
            "value": "Voltage"
        },
        {
            "code": "monitor_value",
            "value": "220"
        },
        {
            "code": "monitor_unit",
            "value": "V"
        },
        {
           "code": "monitor_time_data",
           "value": "1592722282***"
        }
    ]
}

Response parameter

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

Sample response

{
    "success": true,
    "t": 156145681***,
    "result": true
}