Fundamentos de la API REST

Esta página explica las convenciones que sigue la API REST de gestión. Las rutas en sí se enumeran por área en las páginas de referencia enlazadas al final.

Rutas

Toda ruta de gestión está delimitada a su organización:

https://<your host>/tenant/<tenantId>/api/<resource>

En las páginas de referencia, las rutas se escriben a partir de /api/...; anteponga /tenant/<tenantId>. Por ejemplo, /api/iot/devices significa https://<su host>/tenant/<tenantId>/api/iot/devices.

Envíe Authorization: Bearer <API key> en cada llamada. Consulte Autenticación.

Peticiones

Los cuerpos son JSON: envíe Content-Type: application/json. La única excepción es la subida de firmware, que usa multipart/form-data.
La mayoría de los cuerpos son estrictos: un campo que la ruta no conoce se rechaza con 400, nunca se ignora en silencio. Revise la ortografía cuando reciba un 400 por un campo que parece correcto.
PATCH cambia solo los campos que envíe. PUT reemplaza todo el conjunto (las reglas de alarma de un perfil, una ubicación o una sección de ajustes).
Un campo establecido a null lo borra, cuando el campo admite null.
Los ids son UUID (6f1c0a2e-…). Un id mal formado en una ruta suele dar un 400 o un 404.

Respuestas

Las respuestas son JSON. Un registro individual llega envuelto en su nombre: { "device": {...} }, { "alarm": {...} }.
Una lista llega como un array más el recuento total. El nombre del array depende de la ruta: { "devices": [...], "total": 42 }, { "items": [...], "total": 7 } o { "data": [...], "total": 3 }. Cada página de referencia muestra el nombre.
Una respuesta que contiene un secreto (un nuevo token de dispositivo, una nueva API key, un secreto de firma de webhook) se envía con Cache-Control: no-store y es el único lugar donde aparece el secreto.

Tiempos

Se usan dos formatos. Cada página de referencia indica cuál.

Formato	Dónde	Ejemplo
Texto ISO 8601, UTC	Campos de registro (`createdAt`, `lastActivityAt`), la mayoría de filtros, cargas de webhooks	`"2026-11-05T10:00:00.000Z"`
Milisegundos desde el 1 de enero de 1970, UTC	Telemetría (`ts`, `from`, `to`), tiempos de alarma (`startTs`, `openedAt`)	`1762336800000`

Los filtros de rango de fechas de la forma createdFrom=2026-10-01&createdTo=2026-10-15 toman días completos, AAAA-MM-DD, en UTC, incluyendo ambos días.

Listas

Las listas se paginan en el servidor. Existen dos estilos de paginación:

Estilo	`page` empieza en	Usado por (ejemplos)
1-based	`1`	Dispositivos, perfiles de dispositivo, alarmas, sitios y activos, API keys, webhooks y sus entregas
0-based	`0`	Gateways y dispositivos LoRaWAN, el historial de comandos de un dispositivo con `page`, trabajos y líneas base de ajustes de dispositivo, aplicaciones conectadas MCP

Las páginas de referencia indican la base de cada lista. Los parámetros comunes:

Parámetro	Significado	Límites
`page`	Número de página	hasta 10.000 o 100.000 según la lista
`pageSize`	Filas por página	por defecto 20, como máximo 100 (algunas listas admiten 200 o 500, según se indique)
`search`	Texto libre, buscado dentro de nombres y campos similares	hasta 128 o 200 caracteres
`sort`	`campo:asc` o `campo:desc`, hasta tres, separados por comas	solo los campos que la ruta lista; cualquier otro da `400`
filtros	Con nombre según la ruta	ver abajo

Varias listas 0-based también aceptan limit como pageSize y q como search, por compatibilidad con clientes antiguos.

Ordenación

GET /api/iot/devices?sort=lastSeen:desc
GET /api/iot/lorawan/gateways?sort=status:asc,name:asc

Un campo desconocido se rechaza con 400, por ejemplo «Cannot sort by «x». Sortable fields: name, connection, lastSeen, createdAt.» En las listas 0-based, los empates se resuelven por id, para que la paginación sea estable.

Filtros

Tipo	Formato	Ejemplo
Uno de un conjunto	lista separada por comas	`status=OPEN,ACKNOWLEDGED`
Ids	lista de UUID separados por comas, como máximo 100	`deviceId=…,…`
Indicador	`true` o `false`	`online=true`
Rango de días	`<nombre>From`, `<nombre>To`	`createdFrom=2026-11-01`
Rango numérico	`<nombre>Min`, `<nombre>Max`	cuando una ruta lo ofrece

Omita un parámetro en lugar de enviarlo vacío: la mayoría de listas ignoran un parámetro vacío, pero algunas lo rechazan.

Leer todas las páginas

// Node.js 18+: read every device, 100 at a time (a 1-based list)
const base = `https://${host}/tenant/${tenant}/api/iot/devices`;
const all = [];
for (let page = 1; ; page++) {
  const res = await fetch(`${base}?page=${page}&pageSize=100&sort=createdAt:asc`, {
    headers: { Authorization: `Bearer ${key}` },
  });
  if (res.status === 429) { await new Promise((r) => setTimeout(r, Number(res.headers.get('Retry-After') ?? 60) * 1000)); page--; continue; }
  const { devices, total } = await res.json();
  all.push(...devices);
  if (all.length >= total || devices.length === 0) break;
}

Ordene por un campo que no cambia (createdAt) cuando pagine una lista que otros están modificando.

Cambios hechos por otra persona

Algunas escrituras comprueban que el registro no cambió desde que lo leyó:

Dónde	Cómo	En caso de conflicto
Perfiles de dispositivo	Envíe la `version` del perfil como `expectedVersion` en el cuerpo del `PATCH`	`409`, `details.reason` = `stale_profile`
Secciones de ajustes de dispositivo	Envíe el `ETag` de la sección en una cabecera `If-Match`	`412`, `details.reason` = `rev_mismatch`; `428` sin `If-Match`

Las reglas de alarma de un perfil no tienen tal comprobación: un PUT reemplaza todo el conjunto, así que lea las reglas justo antes de cambiarlas.

Vuelva a leer, aplique su cambio a la copia nueva y envíelo de nuevo.

No encontrado y no permitido

Un registro de otra organización, o uno que no puede leer, responde 404, igual que un registro que no existe. Una ruta que no puede usar en absoluto responde 403. Consulte Errores y límites de uso para ver el cuerpo de error y todos los códigos de estado.

Permisos

Cada ruta indica el permiso que necesita, el mismo que comprueba la aplicación. Las páginas de referencia lo listan para cada ruta, por ejemplo iot_device.devices.read. Conceda a una clave ese permiso en Permisos de módulo. Un permiso que solo tiene el rol Owner no puede concederse a una clave.

Referencias de rutas

Área	Página
Dispositivos, credenciales, conexión, registro, perfiles de dispositivo	API de dispositivos y perfiles
Últimos valores, historial, atributos	API de telemetría y atributos
Comandos y catálogo de comandos	API de comandos
Alarmas, reglas de alarma, silenciados	API de alarmas
Sitios, activos, ubicación, relaciones	API de sitios y activos
Paquetes de firmware, despliegues, ajustes de dispositivo	API de firmware y ajustes de dispositivo
Gateways LoRaWAN, dispositivos, emparejamiento, tramas	API de LoRaWAN
Webhooks	Webhooks
API keys	Autenticación
Codecs LoRaWAN	API de codecs