Telemetría (pull)
La forma principal de consumir telemetría desde tu backend es consultar la API (pull). No hay webhook de telemetría por dispositivo en tiempo real.
Scope requerido: telemetry.read
Path param: deviceId = UUID del dispositivo (id de GET /public/v1/devices).
Si el dispositivo no existe o no pertenece a tu organización → 404.
Última lectura
Sección titulada «Última lectura»Devuelve la última métrica conocida de cada sensor del dispositivo.
GET /public/v1/devices/{deviceId}/telemetry/latestAuthorization: Bearer eyJ…Respuesta 200
Sección titulada «Respuesta 200»Array (puede estar vacío si aún no hay lecturas):
[ { "slug": "temp_cabinet", "displayName": "Temperatura gabinete", "unit": "°C", "value": 4.2, "ts": "2026-09-22T15:40:12.000Z", "status": "OK", "icon": "thermometer" }, { "slug": "door_open", "displayName": "Puerta abierta", "unit": "", "value": 0, "ts": "2026-09-22T15:40:12.000Z", "status": "OK", "icon": "door" }]| Campo | Tipo | Descripción |
|---|---|---|
slug |
string | Identificador del sensor |
displayName |
string | Nombre para mostrar |
unit |
string | Unidad (puede ser "") |
value |
number | Último valor |
ts |
string | null | Timestamp ISO-8601 de la lectura |
status |
string | Estado de la métrica (p. ej. OK) |
icon |
string | Ícono asociado al sensor |
Histórico
Sección titulada «Histórico»Serie temporal por sensor en un rango de fechas.
GET /public/v1/devices/{deviceId}/telemetry/history?startDate=2026-09-20T00:00:00.000Z&endDate=2026-09-22T23:59:59.000ZAuthorization: Bearer eyJ…Query params
Sección titulada «Query params»| Param | Requerido | Descripción |
|---|---|---|
startDate |
sí | Inicio del rango, ISO-8601 |
endDate |
sí | Fin del rango, ISO-8601 (posterior a startDate) |
Límites
Sección titulada «Límites»- Rango máximo: 7 días.
- Más costoso que
latest: usalo con cuidado (comparte el rate limit de/public/v1). - Según la duración del rango, el backend puede aplicar downsampling (agregación temporal) para reducir volumen.
Respuesta 200
Sección titulada «Respuesta 200»{ "deviceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "startDate": "2026-09-20T00:00:00.000Z", "endDate": "2026-09-22T23:59:59.000Z", "sensors": { "temp_cabinet": { "readings": [ { "idTelemetryReading": "3fa85f64-…:sensor-uuid:2026-09-20T12:00:00.000Z", "ts": "2026-09-20T12:00:00.000Z", "value": "4.1", "status": "OK", "device": { "idDevice": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Heladera San Martín #01", "did": "11111111-2222-3333-4444-555555555555", "hardwareId": "AABBCCDDEEFF" }, "deviceSensor": { "idDeviceSensor": "d0e1f2a3-b4c5-6789-0123-456789abcdef", "slug": "temp_cabinet", "displayName": "Temperatura gabinete", "unit": "°C", "icon": "thermometer" }, "rawJson": null } ], "min": -20, "max": 10 } }, "summary": { "startDate": "2026-09-20T00:00:00.000Z", "endDate": "2026-09-22T23:59:59.000Z", "totalReadings": 1, "sensorsCount": 1 }}| Campo | Descripción |
|---|---|
sensors |
Mapa slug → { readings, min, max }. min/max son límites de hardware del sensor si existen; si no, null. |
sensors.*.readings[].value |
String numérico (así se serializa la lectura histórica). |
summary |
Totales del rango consultado. |
Si no hay puntos en el rango, sensors puede ser {} y summary.totalReadings = 0.
Errores de validación
Sección titulada «Errores de validación»| Código | Motivo |
|---|---|
400 |
Fechas inválidas, endDate no posterior a startDate, o rango mayor a 7 días |
404 |
Dispositivo inexistente / otra organización |
403 |
Sin scope telemetry.read |
Push opcional (flota completa)
Sección titulada «Push opcional (flota completa)»Si necesitás un resumen periódico de toda la flota en un solo POST a tu servidor, usá el digest de webhooks. Eso no reemplaza el pull puntual por dispositivo.