Recursos para desarrolladores

Tus dispositivos. Una API.

Conecta tu aplicación con dispositivos mediante IoT Devices. Empieza con una lectura y añade los permisos necesarios.

HTTPS · API versión 1

Empieza por tu instalación.

Solicita una API Key para tu instalación. Cada clave corresponde a un espacio de dispositivos y permisos definidos. Guárdala en tu servidor.

URL basehttps://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'

Usa la cabecera Authorization: Bearer. Las lecturas admiten GET o JSON POST; los cambios requieren JSON POST. Deja un segundo entre solicitudes de la misma instalación.

Los ID y comandos son ilustrativos. Consulta las capacidades del producto y usa los valores de tu instalación.

Solicitar acceso a la API

Permisos de la clave

read: Leer dispositivos, productos, configuración y tareas.
manage: Actualizar la configuración y organización de dispositivos.
control: Enviar comandos y gestionar acciones programadas.
firmware: Solicitar actualizaciones de firmware.

Buscar un endpoint

Endpoints coincidentes: 29 / 29

Dispositivos

GETListar dispositivos/device/list

Permiso requerido: read

Parámetros
Nombre	Obligatorio	Descripción
`q`	No	Buscar por ID o nombre; se ignora si se indica tag.
`product`	No	Filtrar por uno o varios ID.
`tag`	No	Filtrar por uno o varios ID.
`group`	No	Filtrar por uno o varios ID.
`page_index`	No	Número de página, desde 1.
`page_size`	No	Resultados por página: 10, 20, 30 o 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'

GETDetalles del dispositivo/device/info

Permiso requerido: read

Parámetros
Nombre	Obligatorio	Descripción
`device`	Sí	ID de dispositivos separados por comas o barras verticales; máximo 100.

curl 'https://iotdevices.org/api/iot/v1/device/info?device=1001' \
  -H 'Authorization: Bearer YOUR_API_KEY'

POSTActualizar etiquetas de dispositivos/device/tag

Permiso requerido: manage

Indica add, del o ambos; se ignoran las asociaciones repetidas.

Parámetros
Nombre	Obligatorio	Descripción
`device`	Sí	ID de dispositivos separados por comas o barras verticales; máximo 100.
`add`	No	ID de etiquetas que se añadirán.
`del`	No	ID de etiquetas que se quitarán.

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"}'

POSTMover dispositivos a un grupo/device/group

Permiso requerido: manage

Parámetros
Nombre	Obligatorio	Descripción
`device`	Sí	ID de dispositivos separados por comas o barras verticales; máximo 100.
`group`	Sí	ID del grupo de destino; 0 elimina la asignación.

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}'

GETRegistros del dispositivo/device/log

Permiso requerido: read

Parámetros
Nombre	Obligatorio	Descripción
`device`	Sí	ID de un dispositivo.
`date`	No	Fecha en formato YYYY-MM-DD; por defecto, hoy.
`type`	No	Tipos de registro separados por comas: connect, disconnect, subscribe, unsubscribe, register, ota, control, event.
`page_index`	No	Número de página, desde 1.
`page_size`	No	Resultados por página: 10, 20, 30 o 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'

Comandos

POSTEnviar un comando/device/order

Permiso requerido: control

La aceptación confirma el envío. Comprueba el estado o los eventos antes de confirmar la ejecución.

Parámetros
Nombre	Obligatorio	Descripción
`device`	Sí	ID de dispositivos separados por comas o barras verticales; máximo 100.
`order`	Sí	Objeto JSON con comandos compatibles con el modelo.
`gateway`	No	ID de pasarelas cuando se requiera reenvío; máximo 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}}'

Configuración

GETLeer la configuración/config/info

Permiso requerido: read

Parámetros
Nombre	Obligatorio	Descripción
`device`	Sí	ID de un dispositivo.
`type`	Sí	Sección de configuración. `basic · device · network · mode`

curl 'https://iotdevices.org/api/iot/v1/config/info?device=1001&type=basic' \
  -H 'Authorization: Bearer YOUR_API_KEY'

POSTEscribir la configuración/config

Permiso requerido: manage

La aceptación confirma el envío. Comprueba el estado o los eventos antes de confirmar la ejecución.

Parámetros
Nombre	Obligatorio	Descripción
`device`	Sí	ID de dispositivos separados por comas o barras verticales; máximo 100.
`config`	Sí	Propiedades de configuración compatibles con el dispositivo.

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"}}'

Firmware

GETListar firmware disponible/ota/firmware

Permiso requerido: read

Parámetros
Nombre	Obligatorio	Descripción
`device`	Sí	ID de un dispositivo.

curl 'https://iotdevices.org/api/iot/v1/ota/firmware?device=1001' \
  -H 'Authorization: Bearer YOUR_API_KEY'

POSTActualizar firmware/ota

Permiso requerido: firmware

La aceptación confirma el envío. Comprueba el estado o los eventos antes de confirmar la ejecución.

Parámetros
Nombre	Obligatorio	Descripción
`device`	Sí	ID de dispositivos separados por comas o barras verticales; máximo 100.
`firmware`	No	Para un dispositivo, indica name y size de la lista. Varios dispositivos usan la última versión.

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"}}'

Productos

GETBuscar productos/product/list

Permiso requerido: read

Parámetros
Nombre	Obligatorio	Descripción
`q`	Sí	Buscar por ID, nombre o modelo del producto.
`page_index`	No	Número de página, desde 1.
`page_size`	No	Resultados por página: 10, 20, 30 o 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'

GETCapacidades del producto/product/detail

Permiso requerido: read

Parámetros
Nombre	Obligatorio	Descripción
`id`	Sí	ID del producto en la lista de productos.

curl 'https://iotdevices.org/api/iot/v1/product/detail?id=100' \
  -H 'Authorization: Bearer YOUR_API_KEY'

GETProductos de tu instalación/product/list/stock

Permiso requerido: read

No se requieren parámetros.

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

Grupos

GETListar grupos/group/list

Permiso requerido: read

Parámetros
Nombre	Obligatorio	Descripción
`format`	No	Lista plana o árbol anidado. `list · tree`
`page_index`	No	Número de página, desde 1.
`page_size`	No	Resultados por página: 10, 20, 30 o 50. `10 · 20 · 30 · 50`

curl 'https://iotdevices.org/api/iot/v1/group/list?format=tree' \
  -H 'Authorization: Bearer YOUR_API_KEY'

PendienteCrear un grupo

Los parámetros están pendientes de verificación y el endpoint no está habilitado. Contáctanos si lo necesitas.

PendienteActualizar un grupo

Los parámetros están pendientes de verificación y el endpoint no está habilitado. Contáctanos si lo necesitas.

POSTEliminar grupos/group/delete

Permiso requerido: manage

Parámetros
Nombre	Obligatorio	Descripción
`group`	Sí	ID de grupos que se eliminarán; máximo 100. Se conservan los dispositivos.

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"}'

POSTControlar un grupo/group/control

Permiso requerido: control

La aceptación confirma el envío. Comprueba el estado o los eventos antes de confirmar la ejecución.

Parámetros
Nombre	Obligatorio	Descripción
`group`	Sí	ID de un grupo.
`order`	No	Objeto JSON con comandos compatibles con el modelo.
`action`	No	ID de una acción existente.

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}}'

Etiquetas

POSTCrear una etiqueta/tag/create

Permiso requerido: manage

Parámetros
Nombre	Obligatorio	Descripción
`title`	Sí	Hasta 32 caracteres chinos, letras inglesas, dígitos o guiones bajos.
`remark`	No	Nota opcional.

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"}'

PendienteActualizar una etiqueta

Los parámetros están pendientes de verificación y el endpoint no está habilitado. Contáctanos si lo necesitas.

PendienteEliminar etiquetas

Los parámetros están pendientes de verificación y el endpoint no está habilitado. Contáctanos si lo necesitas.

PendienteControlar dispositivos por etiqueta

Los parámetros están pendientes de verificación y el endpoint no está habilitado. Contáctanos si lo necesitas.

Tareas

GETListar tareas/task/list

Permiso requerido: read

Parámetros
Nombre	Obligatorio	Descripción
`device`	No	Filtrar por uno o varios ID de dispositivos.
`stage`	No	Tipos de programación separados por comas o barras verticales.
`page_index`	No	Número de página, desde 1.
`page_size`	No	Resultados por página: 10, 20, 30 o 50. `10 · 20 · 30 · 50`

curl 'https://iotdevices.org/api/iot/v1/task/list?page_size=10' \
  -H 'Authorization: Bearer YOUR_API_KEY'

POSTCrear una tarea/task/create

Permiso requerido: control

Indica commands o action y los campos de programación. Los ejemplos crean tareas pausadas.

Campos: datetime → datetime; minute → second; hour → minute + second; day → time; week → week + time; month → day + time; loop → interval. Confirma la zona horaria antes de programar.

Parámetros
Nombre	Obligatorio	Descripción
`devices`	Sí	ID de dispositivos; usa d_, g_ o t_ al combinar dispositivos, grupos y etiquetas.
`type`	Sí	Tipo de programación. `datetime · minute · hour · day · week · month · loop`
`times`	No	Número de ejecuciones; 0 significa sin límite.
`datetime`	No	Fecha y hora de ejecución, o marca de tiempo Unix.
`second`	No	Segundo del minuto, de 0 a 59.
`minute`	No	Minuto de la hora, de 0 a 59.
`time`	No	Hora del día en formato HH:mm:ss.
`week`	No	Días de la semana separados por comas, de 1 a 7.
`day`	No	Día del mes, de 1 a 31.
`interval`	No	Intervalo en segundos; mínimo 3.
`commands`	No	Objeto JSON con los comandos que se programarán.
`action`	No	ID de una acción existente.
`enable`	No	1 activa la tarea; 0 la mantiene pausada. `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}'

GETDetalles de la tarea/task/detail

Permiso requerido: read

Parámetros
Nombre	Obligatorio	Descripción
`task`	Sí	Uno o varios ID de tareas.

curl 'https://iotdevices.org/api/iot/v1/task/detail?task=10' \
  -H 'Authorization: Bearer YOUR_API_KEY'

POSTActualizar una tarea/task/modify

Permiso requerido: control

Solo cambian los campos enviados. Enviar times reinicia el contador.

Campos: datetime → datetime; minute → second; hour → minute + second; day → time; week → week + time; month → day + time; loop → interval. Confirma la zona horaria antes de programar.

Parámetros
Nombre	Obligatorio	Descripción
`task`	Sí	ID de una tarea.
`devices`	No	ID de dispositivos; usa d_, g_ o t_ al combinar dispositivos, grupos y etiquetas.
`type`	No	Tipo de programación. `datetime · minute · hour · day · week · month · loop`
`times`	No	Número de ejecuciones; 0 significa sin límite.
`datetime`	No	Fecha y hora de ejecución, o marca de tiempo Unix.
`second`	No	Segundo del minuto, de 0 a 59.
`minute`	No	Minuto de la hora, de 0 a 59.
`time`	No	Hora del día en formato HH:mm:ss.
`week`	No	Días de la semana separados por comas, de 1 a 7.
`day`	No	Día del mes, de 1 a 31.
`interval`	No	Intervalo en segundos; mínimo 3.
`commands`	No	Objeto JSON con los comandos que se programarán.
`action`	No	ID de una acción existente.
`enable`	No	1 activa la tarea; 0 la mantiene pausada. `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}'

POSTEliminar tareas/task/delete

Permiso requerido: control

Parámetros
Nombre	Obligatorio	Descripción
`task`	Sí	ID de tareas que se eliminarán; máximo 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"}'

PendienteIniciar o pausar tareas

Los parámetros están pendientes de verificación y el endpoint no está habilitado. Contáctanos si lo necesitas.

Respuestas y errores

La respuesta incluye code, msg y data cuando procede. Las listas pueden incluir page_index, page_count, is_more y total. El objeto o la matriz varían según el endpoint.

La aceptación confirma el envío. Comprueba el estado o los eventos antes de confirmar la ejecución.

Una escritura puede haberse aceptado aunque expire. Comprueba el dispositivo o la tarea antes de repetirla; no hay reintentos automáticos. Esta versión no ofrece callbacks de eventos ni acceso MQTT.

400 / 415: Comprueba los parámetros, los campos obligatorios y el tipo de contenido JSON.
401 / 403: Comprueba la API Key y sus permisos.
429: Espera al menos un segundo antes de repetir una lectura.
501: El endpoint está pendiente de verificación.
502 / 504: El servicio no está disponible o el resultado es desconocido.
503: Falta completar la configuración del servidor.