Ir al contenido

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.


Devuelve la última métrica conocida de cada sensor del dispositivo.

GET /public/v1/devices/{deviceId}/telemetry/latest
Authorization: Bearer eyJ…

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

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.000Z
Authorization: Bearer eyJ…
Param Requerido Descripción
startDate sí Inicio del rango, ISO-8601
endDate sí Fin del rango, ISO-8601 (posterior a startDate)
  • 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.
{
"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.

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

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.