iotdevices

开发者资源

用一套接口，连接您的设备。

通过 IoT Devices 将应用与设备连接。从读取数据开始，再按业务需要开放权限。

HTTPS · 接口 v1

从您的设备空间开始。

申请设备空间的 API Key。每个密钥绑定一个设备空间及指定权限，请仅保存在应用服务器。

接口根地址https://iotdevices.org/api/iot/v1
请求示例
curl 'https://iotdevices.org/api/iot/v1/device/list?page_index=1&page_size=10' \
  -H 'Authorization: Bearer YOUR_API_KEY'

通过 Authorization: Bearer 请求头传入密钥。读取支持 GET 或 JSON POST，修改必须使用 JSON POST。同一设备空间每次请求间隔至少 1 秒。

示例 ID 和指令仅用于说明，请根据实际产品功能替换为您设备空间中的值。

申请接口接入

密钥权限

read
读取设备、产品、配置及任务。
manage
修改设备配置、分组和标签。
control
下发指令及管理定时任务。
firmware
下发固件升级请求。

匹配接口数: 29 / 29

设备

GET获取设备列表/device/list

所需权限: read

请求参数
参数名称是否必填参数说明
q否按设备 ID 或名称搜索；指定 tag 时忽略此项。
product否按一个或多个 ID 筛选。
tag否按一个或多个 ID 筛选。
group否按一个或多个 ID 筛选。
page_index否页码，从 1 开始。
page_size否每页条数：10、20、30 或 50。
10 · 20 · 30 · 50
请求示例
curl 'https://iotdevices.org/api/iot/v1/device/list?page_index=1&page_size=10' \
  -H 'Authorization: Bearer YOUR_API_KEY'
GET获取设备详情/device/info

所需权限: read

请求参数
参数名称是否必填参数说明
device是设备 ID，多个以逗号或竖线分隔，最多 100 个。
请求示例
curl 'https://iotdevices.org/api/iot/v1/device/info?device=1001' \
  -H 'Authorization: Bearer YOUR_API_KEY'
POST维护设备标签/device/tag

所需权限: manage

传入 add、del 或两者；重复的关联操作会被忽略。

请求参数
参数名称是否必填参数说明
device是设备 ID，多个以逗号或竖线分隔，最多 100 个。
add否要添加的标签 ID。
del否要移除的标签 ID。
请求示例
curl -X POST 'https://iotdevices.org/api/iot/v1/device/tag' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"device":"1001","add":"10"}'
POST维护设备分组/device/group

所需权限: manage

请求参数
参数名称是否必填参数说明
device是设备 ID，多个以逗号或竖线分隔，最多 100 个。
group是目标分组 ID；0 表示取消分组。
请求示例
curl -X POST 'https://iotdevices.org/api/iot/v1/device/group' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"device":"1001","group":10}'
GET获取设备日志/device/log

所需权限: read

请求参数
参数名称是否必填参数说明
device是单个设备 ID。
date否查询日期，格式 YYYY-MM-DD，默认当天。
type否日志类型，以逗号分隔：connect、disconnect、subscribe、unsubscribe、register、ota、control、event。
page_index否页码，从 1 开始。
page_size否每页条数：10、20、30 或 50。
10 · 20 · 30 · 50
请求示例
curl 'https://iotdevices.org/api/iot/v1/device/log?device=1001&page_size=10' \
  -H 'Authorization: Bearer YOUR_API_KEY'

设备指令

POST向设备下发指令/device/order

所需权限: control

接口受理仅表示指令已下发。请核对设备状态或事件后再确认执行成功。

请求参数
参数名称是否必填参数说明
device是设备 ID，多个以逗号或竖线分隔，最多 100 个。
order是JSON 对象，包含该型号支持的指令。
gateway否需要网关转发时指定网关 ID，最多 5 个。
请求示例
curl -X POST 'https://iotdevices.org/api/iot/v1/device/order' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"device":"1001","order":{"power":1}}'

设备配置

GET获取设备配置/config/info

所需权限: read

请求参数
参数名称是否必填参数说明
device是单个设备 ID。
type是配置类型。
basic · device · network · mode
请求示例
curl 'https://iotdevices.org/api/iot/v1/config/info?device=1001&type=basic' \
  -H 'Authorization: Bearer YOUR_API_KEY'
POST向设备下发配置/config

所需权限: manage

接口受理仅表示指令已下发。请核对设备状态或事件后再确认执行成功。

请求参数
参数名称是否必填参数说明
device是设备 ID，多个以逗号或竖线分隔，最多 100 个。
config是设备支持的配置属性。
请求示例
curl -X POST 'https://iotdevices.org/api/iot/v1/config' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"device":"1001","config":{"relay1":"1"}}'

固件升级

GET获取可用固件列表/ota/firmware

所需权限: read

请求参数
参数名称是否必填参数说明
device是单个设备 ID。
请求示例
curl 'https://iotdevices.org/api/iot/v1/ota/firmware?device=1001' \
  -H 'Authorization: Bearer YOUR_API_KEY'
POST设备固件 OTA 升级/ota

所需权限: firmware

接口受理仅表示指令已下发。请核对设备状态或事件后再确认执行成功。

请求参数
参数名称是否必填参数说明
device是设备 ID，多个以逗号或竖线分隔，最多 100 个。
firmware否单台设备需提供固件列表中的 name 和 size；多台设备自动使用最新版。
请求示例
curl -X POST 'https://iotdevices.org/api/iot/v1/ota' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"device":"1001","firmware":{"name":"VERSION_FROM_FIRMWARE_LIST","size":"300.68"}}'

产品

GET获取产品列表/product/list

所需权限: read

请求参数
参数名称是否必填参数说明
q是按产品 ID、名称或型号搜索。
page_index否页码，从 1 开始。
page_size否每页条数：10、20、30 或 50。
10 · 20 · 30 · 50
请求示例
curl 'https://iotdevices.org/api/iot/v1/product/list?q=switch&page_size=10' \
  -H 'Authorization: Bearer YOUR_API_KEY'
GET获取产品功能详情/product/detail

所需权限: read

请求参数
参数名称是否必填参数说明
id是产品列表中的产品 ID。
请求示例
curl 'https://iotdevices.org/api/iot/v1/product/detail?id=100' \
  -H 'Authorization: Bearer YOUR_API_KEY'
GET获取自有产品列表/product/list/stock

所需权限: read

无需请求参数。

请求示例
curl 'https://iotdevices.org/api/iot/v1/product/list/stock' \
  -H 'Authorization: Bearer YOUR_API_KEY'

设备分组

GET获取分组列表/group/list

所需权限: read

请求参数
参数名称是否必填参数说明
format否列表或树形结构。
list · tree
page_index否页码，从 1 开始。
page_size否每页条数：10、20、30 或 50。
10 · 20 · 30 · 50
请求示例
curl 'https://iotdevices.org/api/iot/v1/group/list?format=tree' \
  -H 'Authorization: Bearer YOUR_API_KEY'
待核验创建分组

该接口的参数仍待核验，目前未启用。如项目需要，请联系我们。

待核验修改分组

该接口的参数仍待核验，目前未启用。如项目需要，请联系我们。

POST删除分组/group/delete

所需权限: manage

请求参数
参数名称是否必填参数说明
group是待删除的分组 ID，最多 100 个，保留组内设备。
请求示例
curl -X POST 'https://iotdevices.org/api/iot/v1/group/delete' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"group":"10"}'
POST对分组执行命令或动作/group/control

所需权限: control

接口受理仅表示指令已下发。请核对设备状态或事件后再确认执行成功。

请求参数
参数名称是否必填参数说明
group是单个分组 ID。
order否JSON 对象，包含该型号支持的指令。
action否已存在的动作 ID。
请求示例
curl -X POST 'https://iotdevices.org/api/iot/v1/group/control' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"group":"10","order":{"power":1}}'

设备标签

待核验获取标签列表

该接口的参数仍待核验，目前未启用。如项目需要，请联系我们。

POST创建标签/tag/create

所需权限: manage

请求参数
参数名称是否必填参数说明
title是最多 32 个汉字、英文字母、数字或下划线。
remark否可选备注。
请求示例
curl -X POST 'https://iotdevices.org/api/iot/v1/tag/create' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"title":"room_100"}'
待核验修改标签

该接口的参数仍待核验，目前未启用。如项目需要，请联系我们。

待核验删除标签

该接口的参数仍待核验，目前未启用。如项目需要，请联系我们。

待核验对标签执行命令或动作

该接口的参数仍待核验，目前未启用。如项目需要，请联系我们。

定时任务

GET获取任务列表/task/list

所需权限: read

请求参数
参数名称是否必填参数说明
device否按一个或多个设备 ID 筛选。
stage否任务策略类型，多个以逗号或竖线分隔。
page_index否页码，从 1 开始。
page_size否每页条数：10、20、30 或 50。
10 · 20 · 30 · 50
请求示例
curl 'https://iotdevices.org/api/iot/v1/task/list?page_size=10' \
  -H 'Authorization: Bearer YOUR_API_KEY'
POST创建任务/task/create

所需权限: control

传入 commands 或 action，并提供对应策略字段。示例创建的任务默认暂停。

策略字段对应：datetime → datetime；minute → second；hour → minute + second；day → time；week → week + time；month → day + time；loop → interval。创建前请确认设备空间时区。

请求参数
参数名称是否必填参数说明
devices是设备 ID；混合设备、分组、标签时，分别使用 d_、g_、t_ 前缀。
type是任务策略类型。
datetime · minute · hour · day · week · month · loop
times否执行次数；0 表示不限次数。
datetime否执行日期时间，或 Unix 时间戳。
second否每分钟的第几秒，范围 0–59。
minute否每小时的第几分钟，范围 0–59。
time否当天执行时间，格式 HH:mm:ss。
week否星期几，以逗号分隔，范围 1–7。
day否每月的第几天，范围 1–31。
interval否间隔秒数，至少 3 秒。
commands否包含定时指令的 JSON 对象。
action否已存在的动作 ID。
enable否1 表示启用，0 表示暂停。
0 · 1
请求示例
curl -X POST 'https://iotdevices.org/api/iot/v1/task/create' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"devices":"1001","type":"loop","interval":60,"commands":{"power":1},"enable":0}'
GET获取任务详情/task/detail

所需权限: read

请求参数
参数名称是否必填参数说明
task是一个或多个任务 ID。
请求示例
curl 'https://iotdevices.org/api/iot/v1/task/detail?task=10' \
  -H 'Authorization: Bearer YOUR_API_KEY'
POST修改任务/task/modify

所需权限: control

只修改传入的字段；传入 times 会重置执行计数器。

策略字段对应：datetime → datetime；minute → second；hour → minute + second；day → time；week → week + time；month → day + time；loop → interval。创建前请确认设备空间时区。

请求参数
参数名称是否必填参数说明
task是单个任务 ID。
devices否设备 ID；混合设备、分组、标签时，分别使用 d_、g_、t_ 前缀。
type否任务策略类型。
datetime · minute · hour · day · week · month · loop
times否执行次数；0 表示不限次数。
datetime否执行日期时间，或 Unix 时间戳。
second否每分钟的第几秒，范围 0–59。
minute否每小时的第几分钟，范围 0–59。
time否当天执行时间，格式 HH:mm:ss。
week否星期几，以逗号分隔，范围 1–7。
day否每月的第几天，范围 1–31。
interval否间隔秒数，至少 3 秒。
commands否包含定时指令的 JSON 对象。
action否已存在的动作 ID。
enable否1 表示启用，0 表示暂停。
0 · 1
请求示例
curl -X POST 'https://iotdevices.org/api/iot/v1/task/modify' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"task":"10","enable":0}'
POST删除任务/task/delete

所需权限: control

请求参数
参数名称是否必填参数说明
task是待删除的任务 ID，最多 100 个。
请求示例
curl -X POST 'https://iotdevices.org/api/iot/v1/task/delete' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"task":"10"}'
待核验启停任务

该接口的参数仍待核验，目前未启用。如项目需要，请联系我们。

响应与错误

响应包含 code、msg 和可用的 data。列表可包含 page_index、page_count、is_more、total；不同接口可能返回对象或数组，请按实际结构解析。

接口受理仅表示指令已下发。请核对设备状态或事件后再确认执行成功。

写请求超时后仍可能已被受理，重发前请检查设备或任务。本接口不会自动重试写操作；当前版本暂不提供事件回调或 MQTT 接入。

400 / 415
检查参数名称、必填字段及 JSON 内容类型。
401 / 403
检查 API Key 及其权限。
429
至少等待 1 秒后再重试读取请求。
501
此接口仍待核验。
502 / 504
设备服务暂不可用，或请求结果尚不明确。
503
仍需完成服务器端接入配置。
WhatsApp 联系我们