×

开发文档

API 文档、SDK 指南和常见问题

API 文档 SDK 指南

API 文档

SDK 文档

常见问题

API 概览

IOI Robot API 提供以下相关能力：

  • 用户管理：用户体系、与 App 用户的关联与打通等
  • 设备管理：从设备的维度对整个设备进行管理
  • 状态同步：同步设备状态
  • 数据服务：设备激活信息
  • 统计服务：电量、睡眠等统计数据
  • 国家码服务：国家码数据
  • 定时管理：对设备的定时进行增删改查
  • 全屋管理：房间管理、家庭管理等
  • 家庭分享管理：添加家庭成员
  • 场景管理：对场景进行增删改查
  • 自动化管理：对自动化进行增删改查
  • 天气服务：获取天气相关数据
  • 通用服务：查询设备日志、恢复出厂设置、固件升级等

调用方式

IOI Robot API 统一通过云函数调用，其调用的方式如下所示：

import { fetch } from '@ray-js/wechat';
const data = {
    // action 为对应的接口名，具体接口可以参考 API 文档
    action: "hello",
    // params 接口参数
    params: {
        hello: 'world'
    }
};

// 使用 @ray-js/wechat 中提供封装的 API fetch 调用接口
// 调用接口，通过 Promise 方式调用，也可以用 async、await 来调用

fetch(data).then(res =>{
    console.log('res', res);
}).catch(err => console.log('err', err))

认证方式

API 调用需要进行身份认证，目前支持以下认证方式：

  • API Key + Secret：通过在请求头中携带 API Key 和 Secret 进行认证
  • Token 认证：通过获取访问令牌进行认证，适用于需要用户登录的场景

速率限制

为了保证 API 的稳定性和公平使用，我们对 API 调用实施速率限制：

  • 普通开发者：每秒 10 次请求
  • 企业开发者：每秒 50 次请求

错误码

API 调用可能返回以下错误码：

  • 400：请求参数错误
  • 401：未授权
  • 403：禁止访问
  • 404：资源不存在
  • 500：服务器内部错误

SDK 安装指南

本指南将帮助您快速安装和配置 IOI Robot SDK。

步骤 1：安装依赖

使用 npm 或 yarn 安装 SDK：

npm install @ioi-robot/sdk
# 或
yarn add @ioi-robot/sdk

步骤 2：初始化 SDK

在您的项目中初始化 SDK：

import { init } from '@ioi-robot/sdk';

init({
    appKey: 'your_app_key',
    appSecret: 'your_app_secret'
});

使用示例

以下是 SDK 的基本使用示例：

import { device } from '@ioi-robot/sdk';

// 获取设备列表
device.getDeviceList().then(devices => {
    console.log('设备列表:', devices);
});

// 控制设备
device.controlDevice(deviceId, {
    power: true,
    brightness: 80
}).then(result => {
    console.log('控制结果:', result);
});

SDK 更新日志

2026 年 4 月更新：

  • 新增设备状态实时同步 API
  • 优化 SDK 性能
  • 增加多语言支持

API 相关问题

如何获取 API Key？

要获取 API Key，请按照以下步骤操作：

  1. 登录 IOI Robot 开发者平台
  2. 进入「应用管理」页面
  3. 创建或选择现有应用
  4. 在「API 管理」中查看您的 API Key 和 Secret

API 调用失败怎么办？

如果 API 调用失败，请检查以下几点：

  • 检查请求参数是否正确
  • 检查认证信息是否有效
  • 检查网络连接是否正常
  • 查看错误码和错误信息，根据提示进行修复

SDK 相关问题

SDK 支持哪些平台？

IOI Robot SDK 目前支持以下平台：

  • Web 浏览器
  • Node.js
  • 微信小程序
  • iOS
  • Android

如何升级 SDK？

使用 npm 或 yarn 升级 SDK：

npm update @ioi-robot/sdk
# 或
yarn upgrade @ioi-robot/sdk

故障排查

设备连接失败怎么办？

如果设备连接失败，请检查以下几点：

  • 检查设备是否通电
  • 检查设备是否处于联网状态
  • 检查网络连接是否正常
  • 尝试重启设备

API 响应时间过长怎么办？

如果 API 响应时间过长，请尝试以下方法：

  • 检查网络连接是否稳定
  • 减少单次请求的数据量
  • 合理使用缓存
  • 避开高峰期调用 API
× 二维码