La telemetría son las mediciones que los dispositivos toman y envían a lo largo del tiempo. Los atributos son valores con nombre que describen un dispositivo: lo que informa sobre sí mismo (client), lo que almacena sobre él (server) y lo que quiere que tenga (shared). Esta página enumera las rutas REST de ambos. Las rutas están bajo https://<tu host>/tenant/<tenantId>.
La API REST lee telemetría, pero nunca la escribe. Los dispositivos escriben telemetría por MQTT o HTTP; los flujos escriben valores derivados con Guardar telemetría. Consulta API HTTP de dispositivos y Valores derivados.
Rutas de telemetría
| Método | Ruta | Permiso | Función |
|---|---|---|---|
| GET | /api/telemetry/latest | telemetry.read | El último valor de cada clave de un dispositivo |
| GET | /api/telemetry/series | telemetry.read | Historial de hasta 50 claves en un intervalo |
| GET | /api/telemetry/kinds | telemetry.read | Los tipos de lecturas de tu organización (por ejemplo iot_device) |
| GET | /api/iot/devices/{deviceId}/elements | telemetry.read | Las claves de un dispositivo, declaradas en su perfil o enviadas, como máximo 300 |
Un dispositivo que no puedes leer responde 404, igual que un dispositivo que no existe.
Últimos valores
GET /api/telemetry/latest?kind=iot_device&entityId={deviceId}&keys=temperature,humidity
Omite keys (como máximo 50) para obtener todas las claves.
{
"kind": "iot_device",
"entityId": "6f1c…",
"latest": {
"temperature": { "ts": 1762681200000, "value": 21.5 },
"humidity": { "ts": 1762681200000, "value": 40 }
}
}
Historial
GET /api/telemetry/series?kind=iot_device&entityId={deviceId}&keys=temperature&from=1762594800000&to=1762681200000&bucket=1h&agg=max
| Parámetro | Valores | Por defecto |
|---|---|---|
keys | De 1 a 50, separadas por comas | obligatorio |
from, to | milisegundos desde la época; to posterior a from | obligatorio |
bucket | auto, raw, 1m, 1h, 1d | auto |
agg | avg, min, max, last, sum, count, increase | avg |
limit | puntos por clave, de 1 a 10.000 | 10,000 |
Los cubos diarios son días UTC: para días en su propia zona horaria, lea los cubos horarios y súmelos. Los valores en bruto se conservan como máximo 90 días, y los cubos por minuto como máximo 31 días. Las reglas completas de parámetros, la paginación de valores en bruto y los ejemplos trabajados están en La API de histórico.
Claves de un dispositivo
GET /api/iot/devices/{deviceId}/elements
La respuesta lista los elementos del dispositivo con sus etiquetas y las claves que tiene, declaradas en su perfil o enviadas, como máximo 300. Sin el permiso para leer perfiles de dispositivo, solo se listan las claves que el dispositivo ha enviado.
Rutas de atributos
| Método | Ruta | Permiso | Función |
|---|---|---|---|
| GET | /api/iot/devices/{deviceId}/attributes | iot_device.attributes.read | Lee los atributos de todos los ámbitos |
| POST | /api/iot/devices/{deviceId}/attributes/server | iot_device.attributes.write | Escribe atributos de servidor |
| POST | /api/iot/devices/{deviceId}/attributes/shared | iot_device.attributes.write | Escribe atributos compartidos; el dispositivo los recibe |
| DELETE | /api/iot/devices/{deviceId}/attributes/{scope}?keys=a,b | iot_device.attributes.write | Elimina claves de servidor o compartidas |
Los atributos client solo los escribe el propio dispositivo. Una escritura en client responde 405: “Los atributos client solo los escribe el dispositivo.”
Lectura
GET /api/iot/devices/{deviceId}/attributes?scope=server&keys=maxTempThreshold,site_code
scope es client, shared o server (sin distinguir mayúsculas); omítelo para los tres. keys admite hasta 100 claves.
{
"attributes": {
"client": { "fw_version": { "value": "2.4.1", "updatedAt": 1762594800000 } },
"shared": { "reportInterval": { "value": 60, "updatedAt": 1762500000000 } },
"server": { "maxTempThreshold": { "value": 8, "updatedAt": 1762400000000 } }
}
}
Los ajustes que gestiona la pestaña Settings de un dispositivo (claves cfg.* en dispositivos que aceptan ajustes por secciones) no se muestran aquí; léelos mediante las rutas de ajustes del dispositivo, ver API de firmware y ajustes de dispositivo.
Escritura
POST/tenant/{tenantId}/api/iot/devices/{deviceId}/attributes/server
Un objeto JSON plano de claves y valores: de 1 a 100 claves por solicitud. Un valor puede ser un número, texto, booleano, objeto o lista, pero no null (elimina la clave en su lugar). Solo se almacenan las claves cuyo valor cambió; la respuesta las nombra. Cada cambio llega a los flujos como un mensaje attributes_updated y se escribe en el registro de auditoría (las claves, nunca los valores).
Cuerpo de la solicitud application/json
{
"maxTempThreshold": 8,
"site_code": "IST-04"
}
Ejemplo curl
curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/devices/{deviceId}/attributes/server' \
-H 'Content-Type: application/json' \
-d '{"maxTempThreshold":8,"site_code":"IST-04"}'
Respuestas
200OK
{
"changed": [
"maxTempThreshold",
"site_code"
]
}
400Solicitud incorrecta
{
"message": "One or more attribute keys are invalid or reserved.",
"code": "VALIDATION_ERROR",
"details": {
"reason": "keys_invalid",
"keys": [
{
"key": "fw_title",
"reason": "reserved"
}
]
}
}
404No encontrado
{
"message": "Device not found.",
"code": "NOT_FOUND"
}
Los atributos compartidos se envían al dispositivo de inmediato si está conectado; si no, cuando se conecte. Un valor compartido debe caber en el límite de downlink del perfil del dispositivo: “El valor de un atributo es mayor que el límite de downlink del dispositivo.” (details.reason = value_too_large).
Eliminar
DELETE /api/iot/devices/{deviceId}/attributes/shared?keys=reportInterval,mode
La respuesta es { "deleted": ["mode", "reportInterval"] }, las claves que existían. Se avisa al dispositivo de las claves compartidas eliminadas.
Reglas de claves de atributo
| Regla | Detalle |
|---|---|
| Caracteres | letras, dígitos, _, ., -; de 1 a 128; distingue mayúsculas |
| Nunca | deleted; una clave que empieza por _ |
| Reservadas para la plataforma o el dispositivo | fw_*, current_fw_*, claves que terminan en .state o .reason, y las claves de contabilidad propias del dispositivo (cfg_rejected, cfg_applied_ts, cfg_hash, attr_error, rpc_result, cert_not_after, time_quality) |
cfg.* | Configuración deseada: solo compartida, hasta 128 caracteres. En un dispositivo cuyos ajustes se gestionan en su pestaña Settings, una escritura responde 409 “La configuración (cfg.*) de este dispositivo se gestiona en sus Settings; cámbiala allí.” |
| Otras claves compartidas | como máximo 57 caracteres |
| Tamaño del valor | valores de servidor de hasta 64 KiB de JSON; valores compartidos hasta el límite de downlink del dispositivo; anidamiento de como máximo 8 niveles |
Consulta Atributos para ver para qué sirve cada ámbito, y Claves y atributos reservados para la lista completa.
Usos habituales
- Límites por dispositivo desde un ERP o MES: escribe
maxTempThresholdcomo atributo de servidor; las reglas de alarma pueden compararlo con él. Ver Referencia de condiciones de alarma. - Ajustes deseados para un dispositivo de terceros: escribe una clave compartida que lee el firmware del dispositivo, y observa sus atributos client para ver el resultado.
- Un informe nocturno: lee las
seriespor hora de ayer y guárdalas en tu almacén de datos.

