Saltar al contenido
ES

API de la plataforma EOS IoT

API REST para acceder a los datos de los dispositivos IoT en la plataforma EOS. Esta documentación te guía en el uso de la API para integrar los datos de los dispositivos en tus aplicaciones.

📥 Descarga la especificación OpenAPI y compártela con tu agente de IA para darle el contexto completo de la API.

Descargar eos-openapi.json

Nota: este es un producto nuevo (versión 1.0.0). Agradecemos cualquier comentario que nos ayude a mejorar la API. No dudes en enviarnos tus sugerencias o en informar de cualquier problema que encuentres.

Autenticación

Todas las solicitudes deben incluir la cabecera x-api-key con la API key proporcionada en el registro.

Ejemplo:

curl -H "x-api-key: YOUR_API_KEY" https://p2uyaymt8c.execute-api.eu-south-1.amazonaws.com/v1/integration/devices

Seguridad:

  • ⚠️ No compartas nunca tu API key
  • ⚠️ No la incluyas en el código fuente
  • ✅ Guárdala en variables de entorno

Límite de solicitudes

La API tiene un límite de solicitudes para mantener la estabilidad del servicio. Los límites concretos dependen de tu plan de uso:

Plan estándar:

  • Tasa: 0,5 solicitudes por segundo
  • Ráfaga (burst): 5 solicitudes simultáneas
  • Cuota: 100.000 solicitudes al mes

Planes personalizados: hay otros planes disponibles con límites distintos. Contacta con soporte para más información.

⚠️ Importante: procura no agotar toda tu cuota en los primeros tres días del mes. Planifica el uso de la API para repartir las solicitudes de forma uniforme a lo largo de todo el periodo de facturación y evitar quedarte sin cuota demasiado pronto.

Mediciones múltiples

Algunos dispositivos pueden tener más de un sensor del mismo tipo. Por ejemplo, un dispositivo puede tener:

  • Dos sensores de temperatura (uno interno y uno externo)

En estos casos:

  • El campo measure será el mismo (p. ej. "temperature")
  • El campo sensor_type será distinto (p. ej. "in100-q1-r-rc0i" frente a "sht40-ad1b-r2")

Usa el parámetro sensorType para filtrar un sensor concreto cuando lo necesites.

Formato de fecha

Todas las fechas deben estar en formato ISO 8601 con zona horaria UTC:

  • Formato: YYYY-MM-DDTHH:mm:ssZ
  • Ejemplo: 2026-02-04T15:30:00Z

Granularidad de los datos históricos

El endpoint /devices/{deviceId}/history admite varias granularidades:

  • raw: datos en bruto, sin agregación
  • 15m: datos agregados cada 15 minutos (media, mín., máx.)
  • 1h: datos agregados por hora (media, mín., máx.)
  • 1d: datos agregados por día (media, mín., máx.)

Paginación

El endpoint /devices/{deviceId}/history admite paginación:

  • limit: número máximo de resultados (por defecto: 100, máx.: 100)
  • offset: número de resultados que se omiten (por defecto: 0)
  • La respuesta incluye la información de paginación en el campo pagination

Disponibilidad de los datos

La disponibilidad de los datos históricos depende de la granularidad y de la fecha de instalación del sensor:

  • Fecha de inicio de la disponibilidad: los datos están disponibles desde la fecha de instalación del sensor de cada dispositivo
  • Datos en bruto: disponibles durante 30 días desde la fecha actual
  • Archivos CSV de datos de alta frecuencia: disponibles durante 30 días desde la fecha actual (misma retención que los datos en bruto)

Nota: esta función solo está disponible si tienes dispositivos de alta frecuencia (p. ej. sensores de motor). Si tu tenant/sitio no tiene dispositivos de alta frecuencia, la API devolverá un mensaje de error.

  • Datos agregados cada 15 minutos (15m): disponibles durante 90 días desde la fecha actual
  • Datos agregados por hora (1h): disponibles durante 2 años desde la fecha actual
  • Datos agregados por día (1d): disponibles de forma permanente (sin caducidad)

Recomendaciones:

  • Usa raw para análisis recientes en detalle (últimos 30 días)
  • Usa los archivos CSV de alta frecuencia para descargas masivas de datos recientes (últimos 30 días)
  • Usa 15m para tendencias a medio plazo (hasta 90 días)
  • Usa 1h para análisis a largo plazo (hasta 2 años)
  • Usa 1d para análisis históricos de más de 2 años

Soporte

Para asistencia o dudas, contacta con el soporte técnico.

Códigos de estado HTTP

  • 200 OK: solicitud completada correctamente
  • 400 Bad Request: solicitud mal formada o parámetros ausentes
  • 401 Unauthorized: API key ausente o no válida
  • 403 Forbidden: acceso denegado
  • 404 Not Found: recurso no encontrado
  • 500 Internal Server Error: error interno del servidor

Dispositivos

Operaciones para consultar los dispositivos IoT disponibles.

Estos endpoints te permiten:

  • Obtener la lista de dispositivos
  • Consultar las mediciones disponibles para cada dispositivo

Listar dispositivos

Devuelve la lista de dispositivos disponibles para tu API key.

Comportamiento:

  • Sin parámetros: devuelve todos los dispositivos disponibles
  • Con includeMeasures=true: incluye las mediciones disponibles para cada dispositivo

Rendimiento:

  • Sin includeMeasures: consulta rápida, ideal para listas largas
  • Con includeMeasures=true: consulta más lenta, úsala solo cuando sea necesario

Ejemplos de uso:

  • Lista simple: GET /devices
  • Con mediciones: GET /devices?includeMeasures=true

Autorización: ApiKeyAuth

Parámetros de consulta (query)

includeMeasures boolean · Por defecto: false · Ejemplo: includeMeasures=true

Si es true, incluye las mediciones disponibles para cada dispositivo en el campo available_measures.

Cuándo usarlo:

  • Cuando necesitas saber qué mediciones están disponibles antes de hacer llamadas de datos
  • Cuando quieres mostrar a los usuarios las opciones disponibles

Cuándo NO usarlo:

  • Cuando solo quieres la lista de dispositivos (más rápido)
  • Cuando ya tienes la información sobre las mediciones disponibles

Respuestas

  • 200 · Lista de dispositivos devuelta correctamente
  • 400 · Solicitud no válida. Causas habituales: parámetros ausentes o mal formados, valores fuera de rango, formato de fecha no válido, array vacío o demasiado grande
  • 401 · No autorizado, la autenticación ha fallado. Causas: falta la API key en la cabecera x-api-key, API key no válida o caducada, API key no asociada a un Usage Plan válido
  • 403 · Acceso denegado, permisos insuficientes
  • 500 · Error interno del servidor. Reintenta la solicitud al cabo de unos segundos; si el problema persiste, contacta con soporte e incluye el requestId si lo tienes en tus logs

get /devices

Datos

Operaciones para acceder a los datos de los dispositivos.

Estos endpoints te permiten:

  • Obtener el último valor disponible de un dispositivo
  • Obtener los últimos valores de varios dispositivos en una sola llamada
  • Consultar los datos históricos con distintas granularidades
  • Filtrar por tipo de medición y sensor

Último valor del dispositivo

Devuelve el último valor disponible de un dispositivo concreto.

Comportamiento según los parámetros:

  • Sin parámetros (GET /devices/{deviceId}/last): devuelve todas las mediciones del último timestamp disponible. Formato: objeto con device_id, timestamp y un array data. Útil cuando quieres ver todas las mediciones simultáneas
  • Con measure (GET /devices/{deviceId}/last?measure=temperature): devuelve solo esa medición. Si varios sensores comparten el mismo measure, se devuelven todos. Formato: objeto único o array (si hay varios sensores)
  • Con measure y sensorType (GET /devices/{deviceId}/last?measure=temperature&sensorType=in100-q1-r-rc0i): devuelve solo ese sensor concreto. Formato: objeto único

Ejemplos de uso:

  • Todas las mediciones: GET /devices/aa:bb:cc:dd:ee:ff/last
  • Solo temperatura: GET /devices/aa:bb:cc:dd:ee:ff/last?measure=temperature
  • Sensor concreto: GET /devices/aa:bb:cc:dd:ee:ff/last?measure=temperature&sensorType=in100-q1-r-rc0i

Autorización: ApiKeyAuth

Parámetros de ruta (path)

deviceId required string ^[0-9a-fA-F]{2}(:[0-9a-fA-F]{2}){5}$ · Ejemplo: aa:bb:cc:dd:ee:ff

ID del dispositivo (dirección MAC en formato XX:XX:XX:XX:XX:XX). Separador: dos puntos (:). No distingue mayúsculas de minúsculas.

Parámetros de consulta (query)

  • measure string · Ejemplo: measure=temperature. Filtra por tipo de medición. Valores admitidos: cualquier tipo de medición devuelto por los sensores (p. ej. temperature, humidity, pressure, co2, battery_percentage, battery_voltage, rssi, a_current, b_current, c_current, total_current, a_voltage, b_voltage, c_voltage, a_act_power, b_act_power, c_act_power, total_act_power, etc.) o "all" para devolver todas las mediciones. El valor debe coincidir exactamente con el campo measure devuelto por los sensores (distingue mayúsculas de minúsculas)
  • sensorType string · Ejemplo: sensorType=in100-q1-r-rc0i. Filtra por tipo de sensor. Ejemplos: in100-q1-r-rc0i (sensor de temperatura interno), sht40-ad1b-r2 (sensor de temperatura externo), dht22 (sensor de humedad/temperatura). Nota: debe usarse junto con measure para que tenga efecto

Respuestas

  • 200 · Último valor (o valores) devuelto correctamente
  • 400 · Solicitud no válida
  • 401 · No autorizado, la autenticación ha fallado
  • 403 · Acceso denegado, permisos insuficientes
  • 404 · Recurso no encontrado. Causas: ID de dispositivo inexistente, dispositivo no accesible con tu API key, sin datos disponibles para el dispositivo solicitado. Nota: si el dispositivo existe pero no tiene datos, también recibirás un 404
  • 500 · Error interno del servidor

get /devices/{deviceId}/last

Ejemplo de respuesta (con measure y sensorType, objeto único):

{
  "timestamp": "2026-02-04T15:30:00Z",
  "device_id": "aa:bb:cc:dd:ee:ff",
  "sensor_type": "in100-q1-r-rc0i",
  "measure": "temperature",
  "unit": "C",
  "value": 22.5
}

Últimos valores de varios dispositivos

Devuelve los últimos valores de varios dispositivos en una sola llamada.

Ventajas:

  • Reduce el número de llamadas HTTP necesarias
  • Más eficiente al leer datos de muchos dispositivos
  • Mantiene la misma lógica de filtrado que /devices/{deviceId}/last

Limitaciones:

  • Máximo 100 dispositivos por solicitud
  • Timeout más largo para listas grandes

Comportamiento:

  • Sin measure: devuelve todas las mediciones de cada dispositivo
  • Con measure: devuelve solo esa medición de cada dispositivo
  • Con measure y sensorType: devuelve solo ese sensor de cada dispositivo

Ejemplos de uso:

  • Todos los dispositivos, todas las mediciones: POST /devices/last/bulk con {"deviceIds": [...]}
  • Todos los dispositivos, solo temperatura: POST /devices/last/bulk con {"deviceIds": [...], "measure": "temperature"}
  • Sensor concreto: POST /devices/last/bulk con {"deviceIds": [...], "measure": "temperature", "sensorType": "in100-q1-r-rc0i"}

Autorización: ApiKeyAuth

Esquema del cuerpo de la solicitud (Request Body): application/json

  • deviceIds required Array of strings [ 1 .. 100 ] items · Lista de IDs de dispositivo a consultar. Mínimo: 1 dispositivo. Máximo: 100 dispositivos. Formato: array de strings (dirección MAC)
  • measure string · Filtra por tipo de medición (opcional). Si se omite, devuelve todas las mediciones de cada dispositivo
  • sensorType string · Filtra por tipo de sensor (opcional). Debe usarse junto con measure para que tenga efecto

Respuestas

  • 200 · Últimos valores devueltos correctamente
  • 400 · Solicitud no válida
  • 401 · No autorizado, la autenticación ha fallado
  • 403 · Acceso denegado, permisos insuficientes
  • 500 · Error interno del servidor

post /devices/last/bulk

Ejemplo de solicitud:

{
  "deviceIds": ["aa:bb:cc:dd:ee:ff", "11:22:33:44:55:66", "ff:ee:dd:cc:bb:aa"]
}

Ejemplo de respuesta:

{
  "results": [{}, {}],
  "count": 2,
  "requested": 2
}

Datos históricos del dispositivo

Devuelve los datos históricos de un dispositivo dentro de un intervalo de tiempo especificado.

Granularidades disponibles:

  • raw (por defecto): datos en bruto, sin agregación. Cada fila es una medición individual. Máxima precisión temporal, más datos devueltos
  • 15m: datos agregados cada 15 minutos. Cada fila contiene media, mínimo y máximo. Reduce mucho el volumen de datos
  • 1h: datos agregados por hora. Cada fila contiene media, mínimo y máximo. Aún más compacto
  • 1d: datos agregados por día. Cada fila contiene la media, el mínimo y el máximo del día. Volumen de datos mínimo

Paginación:

  • Usa limit para controlar cuántos resultados obtienes (máx. 100)
  • Usa offset para moverte entre páginas
  • La respuesta incluye pagination.hasMore para indicarte si hay más datos

Filtros:

  • measure: filtra por tipo de medición
  • sensorType: filtra por tipo de sensor (debe usarse con measure)

Ejemplos de uso:

  • Histórico completo: GET /devices/{id}/history?startDate=...&endDate=...
  • Solo temperatura: GET /devices/{id}/history?startDate=...&endDate=...&measure=temperature
  • Sensor concreto: GET /devices/{id}/history?startDate=...&endDate=...&measure=temperature&sensorType=in100-q1-r-rc0i
  • Datos agregados: GET /devices/{id}/history?startDate=...&endDate=...&granularity=1d

Autorización: ApiKeyAuth

Parámetros de ruta (path)

deviceId required string ^[0-9a-fA-F]{2}(:[0-9a-fA-F]{2}){5}$ · Ejemplo: aa:bb:cc:dd:ee:ff. ID del dispositivo (dirección MAC)

Parámetros de consulta (query)

  • startDate required string <date-time> · Ejemplo: startDate=2026-02-04T00:00:00Z. Fecha/hora de inicio del intervalo (ISO 8601, UTC)
  • endDate required string <date-time> · Ejemplo: endDate=2026-02-04T23:59:59Z. Fecha/hora de fin del intervalo (ISO 8601, UTC). Nota: debe ser posterior a startDate
  • granularity string · Por defecto: "raw" · Enum: "raw" "15m" "1h" "1d". Granularidad de los datos devueltos
  • measure string · Ejemplo: measure=temperature. Filtra por tipo de medición
  • sensorType string · Ejemplo: sensorType=in100-q1-r-rc0i. Filtra por tipo de sensor (debe usarse con measure)
  • limit integer [ 1 .. 100 ] · Por defecto: 100 · Ejemplo: limit=100. Número máximo de resultados a devolver
  • offset integer >= 0 · Por defecto: 0 · Ejemplo: offset=0. Número de resultados que se omiten (para la paginación)

Respuestas

  • 200 · Datos históricos devueltos correctamente
  • 400 · Solicitud no válida
  • 401 · No autorizado, la autenticación ha fallado
  • 403 · Acceso denegado, permisos insuficientes
  • 404 · Recurso no encontrado
  • 500 · Error interno del servidor

get /devices/{deviceId}/history

Ejemplo de respuesta (granularity=raw):

{
  "data": [{}, {}, {}],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 96,
    "hasMore": true,
    "returned": 96
  },
  "granularity": "raw"
}

Datos de alta frecuencia

Operaciones para acceder a los archivos CSV de datos de alta frecuencia de los dispositivos.

Estos endpoints te permiten:

  • Listar los archivos CSV de datos de alta frecuencia disponibles
  • Descargar los archivos CSV mediante URLs prefirmadas de S3
  • Filtrar los archivos por fecha, hora y dispositivo
  • Supervisar las cuotas diarias de descarga

Listar archivos CSV de alta frecuencia

Devuelve una lista de los archivos CSV disponibles con datos de alta frecuencia de los dispositivos, con URLs prefirmadas de S3 para la descarga.

⚠️ Importante: este endpoint solo está disponible si tienes dispositivos de alta frecuencia (p. ej. sensores de motor). Si tu tenant/sitio no tiene dispositivos de alta frecuencia, la API devolverá un mensaje de error NoHighFrequencyDevices.

Sistema de datos de alta frecuencia:

  • Los archivos CSV se crean automáticamente cada hora (en el minuto 10) para la hora anterior
  • Un archivo por dispositivo y hora (solo si hay datos)
  • Los archivos se almacenan en S3 y se organizan por tenant, dispositivo, fecha y hora
  • Solo se incluyen los dispositivos marcados como highfrequency = true

Retención de datos: los archivos CSV de datos de alta frecuencia están disponibles durante 30 días (como los datos en bruto).

Cuotas de descarga:

  • Cada tenant tiene un límite diario de descargas (backup_hf_daily_download_limit)
  • El límite se comparte entre todas las API keys/usuarios del tenant
  • La cuota se restablece a medianoche UTC
  • Cada generación de URL prefirmada cuenta para el límite diario

Comportamiento por defecto (sin deviceId ni hour):

  • Devuelve solo el último archivo disponible de cada dispositivo (para la fecha seleccionada, por defecto: el día UTC actual)
  • Mantiene las respuestas pequeñas y es ideal para clientes de "sincronización diaria"

Modo día completo:

  • Para recuperar todos los archivos del día de todos los dispositivos, usa mode=day

Filtros:

  • date: filtra por una fecha concreta (YYYY-MM-DD). Por defecto: el día actual
  • hour: filtra por una hora concreta (0-23)
  • deviceId: filtra por un dispositivo concreto (debe pertenecer a tu tenant)
  • mode: latest (por defecto) o day

Formato de la respuesta:

  • Los archivos se agrupan por device_id y después por hora
  • Cada hora contiene una URL prefirmada de S3 (válida durante 15 minutos)
  • La información de cuota muestra el límite diario, el uso y las descargas restantes

Casos de error:

  • Si el tenant/sitio no tiene dispositivos de alta frecuencia: devuelve un error "NoHighFrequencyDevices"
  • Si se supera la cuota diaria: devuelve 429 Too Many Requests
  • Si el dispositivo no pertenece al tenant: devuelve 403 Forbidden

Autorización: ApiKeyAuth

Parámetros de consulta (query)

  • date string ^\d{4}-\d{2}-\d{2}$ · Ejemplo: date=2026-02-19. Fecha para la que se consultan los archivos de datos de alta frecuencia (formato YYYY-MM-DD). Por defecto: el día actual (UTC)
  • hour integer [ 0 .. 23 ] · Ejemplo: hour=15. Hora por la que filtrar los archivos (0-23). Ejemplo: 15 para las 15:00
  • deviceId string ^[0-9a-fA-F]{2}(:[0-9a-fA-F]{2}){5}$ · Ejemplo: deviceId=ad:6a:f5:ae:c9:b5. ID del dispositivo por el que filtrar los archivos (formato de dirección MAC). Nota: el dispositivo debe pertenecer a tu tenant
  • mode string · Por defecto: "latest" · Enum: "latest" "day" · Ejemplo: mode=latest. Modo de respuesta: latest (por defecto) devuelve solo el último archivo disponible de cada dispositivo; day devuelve todos los archivos del día completo (puede ser grande)

Respuestas

  • 200 · Lista de archivos de datos de alta frecuencia devuelta correctamente
  • 400 · Parámetros de solicitud no válidos
  • 401 · No autorizado, la autenticación ha fallado
  • 403 · Acceso denegado, falta de permisos o dispositivo que no pertenece al tenant
  • 404 · Dispositivo no encontrado
  • 429 · Cuota diaria de descargas superada
  • 500 · Error interno del servidor

get /backup_files_highfrequency

Ejemplo de respuesta (éxito con archivos):

{
  "files": {
    "ad:6a:f5:ae:c9:b5": {}
  },
  "quota": {
    "dailyLimit": 100,
    "usedToday": 3,
    "remaining": 97,
    "resetAt": "2026-02-20T00:00:00.000Z"
  }
}

Solicita una prueba gratuita

Respondemos en 1 día laborable. Sin compromiso.

Cargando el formulario…

Los datos enviados con este formulario se tratan como se describe en la política de privacidad. El formulario está alojado en Tally.