云对接自助开发文档

云开发简介

• 涂鸦云端接入的物联网设备，均能以云端 API 的方式进行授权调用。

• 开发者可通过调用 API 的形式实现内部自有业务逻辑的开发。

• 设备状态监听以消息队列的方式进行开放，以满足第三方开发者对设备状态的监听，用于实现不同设备间的联动。

  说明：所有设备都需要使用涂鸦系APP或使用涂鸦 App SDK 构建的APP进行配网。

云开发对接

云开发流程图

云开发项目资源图

云开发产品定价

文档中心（具体以官网文档中心为准）：产品定价

涂鸦IoT平台提供查询云项目使用量情况：

• 用量统计：点击跳转
• API 请求量统计：点击跳转
• 消息订阅统计：点击跳转

云开发文档

涂鸦文档中心向开发者提供产品智能化，App 开发，云开发，以及涂鸦所有业务相关的技术文档，帮助开发者快速入门并熟练使用涂鸦 IoT 平台。

文档中心

文档地址：文档中心

高清图下载

云开发 API 列表

文档地址：云服务 API
高清图下载

云开发方案

。

方案	云开发方式	App/小程序/ SDK	云端 API
方案一	全屋智能项目 SaaS	OEM App	全屋智能API	IoT 核心连接服务+ 通用API
方案二		智能生活 App SDK
方案三		IoT 微信小程序 SDK
方案四	自定义开发项目 PaaS	IoT 设备管理 App / 涂鸦智能配网小程序	行业通用API
方案五		行业 App SDK
方案六		行业微信小程序 SDK

注意：所有设备都需要使用涂鸦系APP、App SDK构建的APP、小程序SDK构建的微信小程序 进行配网激活。

云开发方式对比

全屋智能PaaS对接方式

针对家庭和房间业务体系的全屋智能场景，基于 Powered by Tuya 设备生态和涂鸦智能已构建的全屋智能 PaaS 方案，直接使用涂鸦全屋智能应用生态（公版 App、OEM App、App SDK 和微信小程序等）连接设备，结合全屋智能开放能力，构建全屋智能管理平台。
适用于：

1. 客户面向C端客户，客户可以使用涂鸦生态App进行设备配网激活，可通过涂鸦提供的 OpenAPI 获取设备、用户数据，打造大数据管理平台并使用云对接；
2. 客户已拥有海量的C端用户，涂鸦在全屋智能PaaS对接方案中拥有相同的用户体系，可直接进行相互关联，设备配网激活激活后，归属于用户+用户家庭体系下，可通过涂鸦提供的 OpenAPI 获取设备信息、进行控制；
3. 面向的C端用户需要创建丰富的智能家居场景，例如自动化任务或者家庭多设备联动场景（联动设备均需为涂鸦生态设备）；
4. 适用的云开发客户不仅局限以上3点，更多可查看详细的全屋智能PaaS对接方案，以供挑选您合适的云开发解决方案。

自定义开发SaaS对接方式

适用于各类行业场景（例如智慧校园、智慧公寓、智慧商照）的通用开发方案，支持基于 Powered by Tuya 设备生态和行业通用的资产体系，自定义构建符合各类业务需求的资产结构，通过涂鸦智能提供的配网工具连接设备和 API，输出行业解决方案。
适用于：

1. 所有设备属于公司，可使用资产结构树状进行统一的管理，设备使用上可以灵活地授权给人员使用；
2. 已拥有集成化控制系统，需要对大量设备的统一管理和集成化控制；
3. 可以通过涂鸦提供的 OpenAPI，构建多元化的使用业务场景；
4. 涂鸦提供了SaaS开发框架，可以在此基础上实现前后端的同时开发，降低开发难度。

全屋智能PaaS对接方案

云开发平台全屋智能 PaaS 开发方式主要支持以下三类方案类型：

OEM App + 云开发对接方案

1. 方案特点：
   • 基于涂鸦 OEM App，可按需对接云开发平台，支持通过云开发平台下发指令到设备。
   • 设备和 App 同时接入到云开发平台，设备和 App 所有请求发送到云开发平台。
   • 产生的用户和设备数据都归属于客户，客户可基于涂鸦 API 管理用户数据和设备数据，执行定时、场景设置等操作，并获取分析数据。
2. 涂鸦提供的服务：
   • 公版 OEM App 或 App定制开发方案。
   • 提供基于品类的标准指令集，可控制涂鸦 AI+IoT 开发平台内相同品类下的不同型号设备。
   • 提供标准的 API 管理用户和设备数据，提供消息队列供客户获取设备实时数据。
3. 方案优势：
   • 接入成本低、开发时效快，可快速支持涂鸦方案下的多品类设备的接入。
   • 能充分使用涂鸦 AI+IoT 开发平台的所有功能。
   • 快速将产品推向市场。
   • 可按需从涂鸦 AI+IoT 开发平台获取数据进行各种分析及复杂的场景开发。

Smart Life App SDK + 云开发对接方案

1. 涂鸦提供的服务：
   • 提供完整能力的 IoT App SDK。
   • 提供 API 完成用户对接、设备发现和设备控制等其他功能。
   • 提供基于品类的标准指令集，可按品类或型号控制涂鸦 AI+IoT 开发平台内的设备。
   • 提供消息队列，供客户接收设备实时数据。
2. 方案特点：
   • 基于涂鸦 IoT App SDK 自行开发 App。
   • 拥有独立的账户体系，账户体系数据存储在客户云。
   • 能够充分使用涂鸦 AI+IoT 开发平台的所有功能。
   • 可以按需从涂鸦 AI+IoT 开发平台获取数据进行各种数据分析。

微信小程序 SDK + 云开发对接方案

同App SDK对接方案一致，区别于使用IoT 微信小程序 SDK构建微信小程序

1. 涂鸦提供的服务：
   • 提供IoT 微信小程序 SDK。
   • 提供 API 完成用户对接、设备发现和设备控制等其他功能。
   • 提供基于品类的标准指令集，可按品类或型号控制涂鸦 AI+IoT 开发平台内的设备。
   • 提供消息队列，供客户接收设备实时数据。
2. 方案特点：
   • 基于涂鸦 IoT 微信小程序 SDK 自行开发 微信小程序。
   • 拥有独立的账户体系，账户体系数据存储在客户云。
   • 能够充分使用涂鸦 AI+IoT 开发平台的所有功能。
   • 可以按需从涂鸦 AI+IoT 开发平台获取数据进行各种数据分析。

注意：因微信限制：EZ配网及有线网关无法进行配网操作.

自定义开发SaaS对接方案

IoT 设备管理 App / 涂鸦智能配网小程序 + 云开发对接方案

1. 涂鸦提供的服务：
   • 提供完整能力的公版配网 APP 和小程序，无需配网工具的开发。
   • 提供 API 完成资产创建、用户创建及授权、设备绑定和设备控制等其他功能。
   • 提供基于品类的标准指令集，可按品类或型号控制涂鸦 AI+IoT 开发平台内的设备。
   • 提供消息队列，供客户接收设备实时数据。
2. 方案特点：
   • 基于涂鸦公版设备管理 App，无需开发配网工具APP，可按需创建用户并配网设备，对接云开发平台。 支持通过云开发平台下发指令到设备。
   • 设备接入到云开发平台，设备所有请求发送到云开发平台。
   • 产生的设备数据都归属于客户，客户可基于涂鸦 API 管理设备数据，并获取分析数据。

行业 App SDK/ 行业微信小程序 SDK + 云开发对接方案

1. 涂鸦提供的服务：
   • 提供行业 App SDK /行业微信小程序 SDK，可集成至客户自有APP。
   • 提供 API 完成资产创建、用户创建及授权、设备绑定和设备控制等其他功能。
   • 提供基于品类的标准指令集，可按品类或型号控制涂鸦 AI+IoT 开发平台内的设备。
   • 提供消息队列，供客户接收设备实时数据。
2. 方案特点：
   • 基于涂鸦 SDK 自行开发 APP 或微信小程序。
   • 拥有独立的账户体系，账户体系数据存储在私有云。
   • 能够充分使用涂鸦 AI+IoT 开发平台的所有功能。
   • 可以按需从涂鸦 AI+IoT 开发平台获取数据进行各种数据分析。

云项目菜单介绍

IoT 开发者平台

1. 涂鸦IoT云开发平台地址：https://iot.tuya.com
   • 注册账号并创建并配置云项目是开发 IoT 服务的第一步，在项目配置环节您需要完成以下操作。
   • 新建一个项目：云项目是 IoT 平台资源（设备、API 权限、数据资产等）的集合，不同云开发项目之间的数据资源实现相互隔离。
   • 开通并授权所需云服务：您可以基于业务场景选择涂鸦智能为您开放的云服务，加速您的业务实现。
2. 开发者需开通 IoT 核心连接服务后才可以在创建云项目、获得基础 API 调用和消息订阅的使用量。
   • 操作步骤：左边导航条 -> 云开发 -> 开通IoT核心连接服务。
     

创建云项目

云项目是涂鸦云开发平台管理开发资源的单位，每个云项目的资源和权限相互隔离。开发 IoT 应用前，您需要创建一个云项目。
开通云开发企业版后，创建云项目:

• 操作步骤：左边导航条 -> 云开发 -> 云开发 -> 创建云项目。
  

1. 在创建项目对话框中，配置项目参数后点击 创建：
   

• 项目名称：自定义项目的名称。
• 项目描述：自定义项目的描述。
• 开发方式：不同开发方式特征，参见开发方式 。

具体项目可用资源，参照：云开发项目资源图

• 服务行业：选择您项目的行业类型，便于后期统计分析。
• 可用区域：填入对应您所在区域对应的服务器地址。
2. 批量授权 API 产品：除了默认选择的 API 服务外，可以按需添加服务，具体可以查看我的服务。

我的云项目

创建云项目后，进入我的云项目界面。

概况：

1. 云项目事例：
   • 项目名称：cloud program Demo
   • 项目描述：项目描述：测试
   • 创建时间：2021-11-11 14:27:28
   • 服务行业：全屋智能
   • 可用区域：云端API请求数据中心
   • 授权密钥：云项目参数（API请求头参数）
   • 云应用 IP 白名单：开启 IP 白名单后，不在此列表中的来源 IP 的请求会被拒绝
2. 编辑信息：除非开发方式外，其他信息均可以调整
   

授权：

该授权下的 APP 应用和微信小程序应用，只适用于自定义开发云项目（资产体系）。

注意：全屋智能 PaaS体系的 APP 构建,请在左侧导航条 APP 下创建。

服务API：

已授权至该云项目的服务API，需要新增，点击“新增 API 授权”，可批量授权已开通API服务，若未开通跳转至 我的服务 。

FAQ：若 API 调用时，提示" NO Permissions .This Project is not authoridzed to call this API"时
请确认：调用的 API对应的服务，是否已开通并授权至该云项目。

资产：

自定义云项目的资产设备体系，通过创建资产结构，可以授权节点的权限至 用户 ，并前端界面查看管理设备。

用户：

自定义云项目的用户体系，只适用于自定义开发云项目（资产体系）。

设备：

1. 可以同时查看全屋智能PaaS项目和自定义云开发SaaS项目下的设备，不同数据中心的设备和用户数据隔离；
   

   注意 ：根据各地数据安全法规的规定，数据跨区传输存在违规风险，涂鸦禁止中国和海外跨区API调用和消息订阅行为，请合理部署您的云服务以保障数据安全。

2. 全部设备 界面可以添加虚拟设备，方便进行调试
   添加方式：自定义开发项目为添加至资产结构下，全屋智能PaaS项目为自有APP或公版APP的账号下
   
3. 关联自有APP、关联自有小程序、关联涂鸦APP账号，该三个界面均为全屋智能PaaS项目的设备关联。
   

我的服务

开通服务，授权给当前项目后，就可以使用授权密钥访问对应的 API。

• 可以在API服务详情页查看 API 服务 的概述、定价、 API 列表和已授权的项目等信息
  
• 云项目下的 服务API 即为当前云项目可以调用的API，可以使用在线调试工具进行调试.
  

API 调试

涂鸦云开发平台支持通过在线 API 调试功能对 API 进行调用验证。

• 入口1：云开发 -> API服务 进入
• 入口2：云项目界面 -> 服务API -> 去调试
  

数据统计

开发者可以在 IoT 平台上获取项目资源的用量总计、API 请求统计和消息订阅统计。
可以结合 云开发产品定价 ，查看账单情况。

云项目设备和用户管理

参考文档：设备关联方式;
云开项目对于设备的进行API调用，都需要对设备拥有权限，即：

1. 全屋智能 PaaS需要将创建的APP或涂鸦账号关联至云项目
2. 自定义开发需要设备在该项目的资产节点上进行配网管理。
   

全屋智能设备体系

全屋智能 SaaS下的设备信息均存在 APP 个人账号下，故通过涂鸦智能全屋智能生态应用（包含：OEM App 、 App SDK的 APP 、微信小程序、公版 App等）激活配网设备后，并关联至云开发项目后，才能通过云端 API 管理和控制对应的设备。

全屋智能 SaaS 类型云开发项目提供以下设备关联方式：
• 关联自有 App
• 关联自有小程序
• 关联涂鸦 App 账号

注意1：关联的 OEM APP 或 基于涂鸦SDK 构建的 APP、微信小程序 需与云项目处于同一个IoT账号下。

注意2：同一个 App 最多关联两个项目。如果您需要关联第三个项目，那么您需要先对已关联的 App 进行解除关联。

FAQ：若 API 调用相关 Device_id 设备请求时，提示" Permission deny "时
请确认：
1、API 请求中设备 Device_id 是否正确；
2、设备是否仍绑定在APP下；
3、设备使用的配网APP是否关联至对应的云项目，公版APP是否已扫码授权至云项目。

自定义开发项目设备体系

自定义项目依赖于资产体系，设备属于该云项目资产下。在云项目资产目录下 创建用户 并授权至授权资产后

IoT 设备管理 App

参考文档：通过 IoT 设备管理 App 连接设备

使用公版自定义开发配网工具APP，扫码关联对应云应用后，使用授权至资产的账号进行登录，在对应的资产节点下对设备进行配网操作。

涂鸦智能配网小程序

使用微信扫码登录微信小程序，并登陆授权账号。

注意：IoT管理APP能记住当前登录状态，微信小程序使用时需每次登陆

查询云项目下关联设备

云项目下能通过设备ID查询到对应的设备，才能够有权限进行云端API调用，目前可以全屋和行业均能通过IoT平台进行查询。

管理设备查询

路径：我的云项目 -> 设备 -> 全部设备
可以查看该云开发项目的所有设备：
自有App、自有微信小程序、涂鸦App账号、资产

资产下设备查询

资产目录下，可以点击不同的资产结构，查看到各节点下的设备，点击调试，可以查看设备信息。

用户管理

全屋智能App用户

全屋智能 SaaS下的APP 个人账号 可以在IoT平台 运营 -> 用户管理 查询。

自定义开发 用户

自定义开发（资产） 用户信息创建于 用户（资产标签右侧），且需要授权至资产。只有授权至该资产节点下，才能登陆App进行配网设备和控制设备。

注意：用户只对资产节点有权限，若未对子节点授权，则无法控制子节点的设备。

API调用指南

涂鸦开放多种业务接口，全面覆盖设备配网、全屋管理、设备控制、场景自动化等业务场景。开发者可根据需求按照具体的 API 对接文档规则调用 API，实现应用。

数据中心地址

云开发平台为不同的区域提供不同的接入地址，请根据设备所在区域选择接入地址，缩短调试响应时长。

地域	地址	说明
中国数据中心	https://openapi.tuyacn.com
美西数据中心	https://openapi.tuyaus.com
美东数据中心	https://openapi-ueaz.tuyaus.com
中欧数据中心	https://openapi.tuyaeu.com
西欧数据中心	https://openapi-weaz.tuyaeu.com
印度数据中心	https://openapi.tuyain.com

请求头

参考文档：请求结构

参数名	类型	参数位置	必填	说明
client_id	String	header	是	用户 ID。
sign	String	header	是	采用指定签名算法计算出的签名。
sign_method	String	header	是	签名的摘要算法，固定为 HMAC-SHA256。
t	Long	header	是	13 位标准时间戳。
access_token	String	header	是	token 信息。 说明：获取和刷新 Token 接口不需要此参数。
lang	String	header	否	语言类型。中国区默认 zh，其他区默认 en。
nonce	String	header	否	API调用者生成的UUID。 说明：旧版签名方案无需该参数。
Signature-Headers	String	header	否	开发者自定义需要加入签名的header字段。 说明：旧版签名方案无需该参数。

Sign 签名算法

参考文档：签名机制
向云开发平台发送调用请求时，都需要提供签名（ Sign ）进行身份验证。

签名算法：涂鸦采用 HMAC-SHA256 方法创建摘要

1. 令牌管理 API 签名算法：
   • 适用范围：获取令牌和刷新令牌 API。
   • 签名算法： sign = HMAC-SHA256(client_id + t + nonce + stringToSign, secret).toUpperCase()
2. 业务管理 API 签名算法：
   • 适用范围：令牌管理接口以外的其他 API。
   • 签名算法：
   str = client_id + access_token + t + nonce + stringToSign
   sign = HMAC-SHA256(str, secret).toUpperCase()
3. stringToSign 签名字符串:
   组成部分：

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

4. 调用示例
   参考文档：签名构建示例
5. 验证签名结果
   可使用Postman调用查看Sign的入参及加密结果： 验证签名结果

项目-API服务管理

云开发 API 列表：点击跳转

根据不同的开发类型（全屋、行业），介绍可调用的API服务范围：

• 全屋智能PaaS体系 - API 列表：
  
• 自定义开发(行业 SaaS 体系) - API 列表：
  

Postman 调用实践

参考文档：设置 Postman 环境并调用 API

API 调用顺序

以全屋智能 PaaS项目为例，调用App用户下的设备，并控制下发指令

API API 调用常见问题

1. 设备标准指令集请参考文档：标准指令集。
2. 请求头 headers 中 sign_method 需要必填，否则会导致云端sign校验报错。
3. Signature-Headers 可以为空，则 stringToSign 中 Headers 也为空，但是后面仍存在换行符。
4. stringToSign 中拼接的 url 参数均存在换行符。
5. Content-SHA256 的计算方法是 SHA256 ，不带加密密钥。

消息订阅

消息订阅参考文档：消息队列
云开发项目中的设备相关状态发生变化时（如设备注册、设备数据上报、设备离线等），涂鸦会转发消息。
开放平台消息主要通过 Pulsar 主动推送各种事件数据至外部合作伙伴，以满足合作伙伴对消息实时性和消息持久化的需求。

客户端示例：

Demo开发语言	下载地址	实践文档
Java	下载地址	操作实践文档
Golang	下载地址	操作实践文档
C#	下载地址	操作实践文档
Python	下载地址	操作实践文档
Nodejs	下载地址	操作实践文档

技术支持

云开发常见概念

云开发常用参数，可帮助您快速了解涂鸦生态：常见参数

涂鸦帮助中心

帮助中心提供涂鸦以及开发全链路的常见问题查询及解决方案。

• 涂鸦智能帮助中心：点击跳转

技术工单

如果无法在帮助中心获得您需要的答案，可提交工单。

• 涂鸦会有专业同事向您解答问题。