配网管理

随着产品配网方式丰富度的提高，云开发平台对主流配网能力进行了迭代，提供了权限管理接口来满足不同配网方式的诉求，例如 Wi-Fi 配网、蓝牙配网、蓝牙 & Wi-Fi 双模配网等方式。

API 列表

请求方式	API	设备类型	接口说明
POST	/v1.0/device/paring/token	普通设备	生成配网令牌。
GET	/v1.0/device/paring/tokens/{token}	普通设备	获取配网设备列表。
PUT	/v1.0/devices/{device_id}/enabled-sub-discovery	Zigbee 设备	开放网关允许子设备入网。
GET	/v1.0/devices/{device_id}/list-sub	Zigbee 设备	获取当前入网的子设备列表。
GET	/v1.0/devices/{device_id}/sub-devices	Zigbee 设备	获取网关下的子设备列表。

生成配网令牌

接口说明

发现设备之前，需要先申请一个临时令牌，经过涂鸦客户端 SDK 进行配网，设备接到配网令牌后可自动完成发现和账号绑定。当前支持 Wi-Fi 配网和 BLE + Wi-Fi 配网方式，更多能力持续拓展中。

说明：BLE 设备需扫描设备二维码获取设备唯一 ID 用于配网。

接口地址

POST /v1.0/device/paring/token

请求参数

参数名	类型	参数类型	必填	说明
paring_type	String	body	是	配网类型，支持 BLE、AP、EZ。
uid	String	body	是	用户唯一标识。
time_zone_id	String	body	是	用户所在时区 ID。
home_id	String	body	否	家庭 ID，不填则为用户默认家庭。
extension	Object<extension>	body	否	扩展信息，配网类型是 BLE 时需传入设备 UUID。

extension 说明

参数名	类型	参数类型
uuid	String	设备唯一 ID

返回参数

参数名	类型	说明
code	Integer	响应码，详见 错误码 。
success	Boolean	判断请求是否成功。 true：成功 false：失败
msg	String	请求失败返回的信息，成功则返回空值。
result	Object<result>	返回结果。

result 说明

参数名	类型	说明
expire_time	Long	令牌过期时间
region	String	当前可用区，当前支持：AY、EU、US
token	String	配网令牌
secret	String	密钥
extension	Object<extention>	扩展信息

说明：使用涂鸦配网 SDK 时，您需要组装 result 参数，将 region、token、secret 作为 authToken 用于涂鸦配网 SDK 初始化。设备收到后会自动拆解 authToken，您再使用 token 查询配网结果。

extension 说明

参数名	类型	说明
encrypt_key	String	加密 key
random	String	加密字符串

请求示例

POST /v1.0/device/paring/token

{
    "uid": "ay155xxxxxxxx2G0fA",
    "time_zone_id":"Asia/Shanghai",
    "paring_type":"BLE",
    "extension":{
    	"uuid":"5682bceac872cfe7"
    }
}

返回示例

{
    "result": {
        "expire_time": 300,
        "extension": {
            "encrypt_key": "101xxxxxxx189f",
            "random": "fa2fxxxxxxxxcb38c"
        },
        "region": "AY",
        "secret": "pr_0",
        "token": "H73H8u7A"
    },
    "success": true,
    "t": 1591257455025
}

错误码

以下为该接口常见的业务异常，更多的异常错误，请参考 全局错误码。

错误码	说明
500	系统错误
1106	权限非法

轮询配网结果

接口说明

由于设备配网是一个异步流程，根据网络质量的不同，设备成功入网的时间不定，故需要开发者轮询该接口直至查询到设备列表或到超时停止轮询（轮询周期为 1 秒一次，超时时间建议为 100 秒）。

接口地址

GET /v1.0/device/paring/tokens/{token}

请求参数

参数名	类型	参数类型	必填	说明
token	String	URI	是	设备配网令牌

返回参数

参数名	类型	说明
code	Integer	响应码，详见 错误码。
success	Boolean	判断请求是否成功 true：成功 false：失败
msg	String	请求失败返回的信息，成功则返回空值
result	Object<result>	返回结果

result 说明

参数名	类型	说明
success	Array	配网成功设备列表
success.device_id	String	设备 ID
success.product_id	String	产品 ID
success.name	String	设备名称
success.category	String	设备类型
failed	Array	配网失败设备列表
failed.device_id	String	设备 ID
failed.code	String	失败错误码
failed.msg	String	失败错误说明
failed.name	String	设备名称

请求示例

GET /v1.0/device/paring/tokens/23sdsrsdgfd

返回示例

{
    "result":{
        "failed":[

        ],
        "success":[
            {
                "category":"td",
                "device_id":"6c4b088a4116ae16c****",
                "name":"华硕",
                "product_id":"sfclyxhrfnys****"
            }
        ]
    },
    "success":true,
    "t":1591872112140
}

错误码

以下为该接口常见的业务异常，更多的异常错误，请参考 全局错误码。

错误码	说明
500	系统错误
1106	权限非法

开放网关允许子设备入网

接口说明

由于子设备不具备直接的联网能力，故而添加子设备需要网关加入。网关进入允许入网状态后，子设备可以加入网关的本地网络，通过网关完成入库。

接口地址

PUT /v1.0/devices/{device_id}/enabled-sub-discovery

请求参数

参数名	类型	参数类型	必填	说明
device_id	String	URI	是	设备 ID。
duration	Int	URL	否	网关发现时间。 取值范围：0~3600 秒。取值 0 秒为停止发现，默认值为 100 秒。

返回参数

参数名	类型	说明
code	Integer	响应码，详见 错误码。
success	Boolean	判断请求是否成功。 true：成功 false：失败
msg	String	请求失败返回的信息，成功则返回空值。
result	Boolean	返回结果 。

请求示例

PUT /v1.0/devices/23sdsrsdgfdxxxxxx/enabled-sub-discovery?duration=100

返回示例

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

错误码

以下为该接口常见的业务异常，更多的异常错误，请参考 全局错误码。

错误码	说明
500	系统错误
1106	权限非法

获取入网子设备列表

接口说明

子设备配网是一个异步流程，配网时会根据设备数量以及网络情况陆续将子设备加入网关。因此需要根据初次发现时间轮询此接口获取子设备列表，可结合自身业务结束发现流程，建议每次轮询 1 秒直至 100 秒结束。

接口地址

GET /v1.0/devices/{device_id}/list-sub

请求参数

参数名	类型	参数类型	必填	说明
device_id	String	URI	是	网关 ID
discovery_time	Long	URL	是	网关发现子设备时间，精确到秒

返回参数

参数名	类型	说明
code	Integer	响应码，详见 错误码。
success	Boolean	判断请求是否成功。 true：成功 false：失败
msg	String	请求失败返回的信息，成功则返回空值。
result	Object<result>	返回结果。

result 说明

参数名	类型	说明
id	String	设备编号
name	String	名称
owner_id	String	设备拥有者 ID
active_time	Long	设备激活时间
update_time	Long	设备更新时间
category	String	产品类别
product_id	String	产品 ID
online	Boolean	设备在线状态

请求示例

GET /v1.0/devices/23sdsrsdgfd******/list-sub?discovery_time=1566973348

返回示例

{
    "result":[
        {
            "active_time":1566973357,
            "update_time":1566973363,
            "owner_id":"5583425******",
            "product_id":"tob46aoq******",
            "name":"烟雾报警器",
            "online":true,
            "id":"xxxxx",
            "category":"ywbj"
        }
    ],
    "t":1566973373639,
    "success":true
}

错误码

以下为该接口常见的业务异常，更多的异常错误，请参考 全局错误码。

错误码	说明
500	系统错误
1106	权限非法

获取网关下的子设备列表

接口说明

通过网关设备 ID，获取子设备列表。

接口地址

GET /v1.0/devices/{device_id}/sub-devices

请求参数

参数名	类型	参数类型	必填	说明
device_id	String	URI	是	设备 ID

返回参数

参数名	类型	说明
code	Integer	响应码，错误码。
success	Boolean	判断请求是否成功。 true：成功 false：失败
msg	String	请求失败返回的信息，成功则返回空值。
result	Object<result>	返回结果。

result 说明

参数名	类型	说明
id	String	ID
product_id	String	产品 ID
owner_id	String	设备拥有者 ID
online	Boolean	设备在线状态
name	String	设备名称
update_time	Long	设备状态更新时间
active_time	Long	设备上次配网时间
category	String	分类

请求示例

GET /v1.0/devices/6ca345543******6875z88d/sub-devices

Java SDK 示例

TuyaClient client = new TuyaClient(clientId, secret, RegionEnum.CN);
BatchDevices batchDevices = client.gatewaySubList(devIds);

System.out.println("批量获取设备详细信息: ");
System.out.println(JSONObject.toJSONString(batchDevices));

返回示例

{
    "success":true,
    "t":1565917936198,
    "result":[
        {
            "active_time":1565857222,
            "update_time":1565857227,
            "owner_id":"52****57",
            "product_id":"Mco****jXh",
            "name":"mcs",
            "online":false,
            "id":"6cac4bd83****6875z88d",
            "category":"mcs"
        },
        {
            "active_time":1565857222,
            "update_time":1565857227,
            "owner_id":"52****57",
            "product_id":"ez****rjm",
            "name":"海曼XX传感器",
            "online":false,
            "id":"6caabb588****0db3d7gbl",
            "category":"sj"
        }
    ]
}

错误码

以下为该接口常见的业务异常，更多的异常错误，请参考 全局错误码。

错误码	说明
500	系统错误
1106	权限非法