API IoT - Recepción de Telemetría desde Dispositivos Externos

Introducción

La API IoT de OBUMA ERP permite recibir lecturas provenientes de sensores, medidores, PLC, gateways industriales, sistemas SCADA y cualquier otro dispositivo capaz de realizar solicitudes HTTP POST.

Esta integración ha sido diseñada para ser independiente del fabricante o tecnología utilizada, permitiendo conectar dispositivos como medidores eléctricos, sensores de temperatura, sensores de presión, equipos de monitoreo energético, ESP32, PLC industriales y cualquier otra fuente de telemetría.

Los datos recibidos son procesados por OBUMA ERP para su utilización en reportes, dashboards, alertas, monitoreo operacional y control de consumos asociados a contratos de servicios.

Endpoint

POST /webservices/iot/telemetry

Método

POST

Formato de envío

La API recibe los datos en formato JSON.

Content-Type: application/json

Autenticación

La autenticación se realiza mediante una API Key previamente configurada en OBUMA ERP.

La API Key debe enviarse mediante alguno de los siguientes encabezados:

X-API-Key: TU_API_KEY
X-Ide: ENTREGADO_POR_OBUMA

Estructura del JSON

La API recibe un arreglo de lecturas, permitiendo enviar múltiples sensores en una sola solicitud.

Ejemplo

[
  {
    "device_id":"DDS238",
    "sensor":"potencia",
    "valor":2804,
    "unidad":"W",
    "timestamp":"2026-05-22 15:30:00"
  },
  {
    "device_id":"DDS238",
    "sensor":"temperatura",
    "valor":35,
    "unidad":"°C",
    "timestamp":"2026-05-22 15:30:00"
  }
]

Campos disponibles

Campo	Obligatorio	Descripción
device_id	Sí	Identificador único del dispositivo en OBUMA
sensor	Sí	Nombre de la variable medida
valor	Sí	Valor capturado por el sensor
unidad	No	Unidad de medida
timestamp	Sí	Fecha y hora de la lectura

Ejemplos de sensores

Dependiendo del tipo de dispositivo, pueden enviarse distintos sensores.

Medidor eléctrico

[
  {
    "device_id":"DDS238",
    "sensor":"voltaje",
    "valor":228.4,
    "unidad":"V",
    "timestamp":"2026-05-22 15:30:00"
  },
  {
    "device_id":"DDS238",
    "sensor":"corriente",
    "valor":12.3,
    "unidad":"A",
    "timestamp":"2026-05-22 15:30:00"
  },
  {
    "device_id":"DDS238",
    "sensor":"potencia",
    "valor":2804,
    "unidad":"W",
    "timestamp":"2026-05-22 15:30:00"
  },
  {
    "device_id":"DDS238",
    "sensor":"energia_kwh",
    "valor":1234.56,
    "unidad":"kWh",
    "timestamp":"2026-05-22 15:30:00"
  }
]

Sensor de temperatura

[
  {
    "device_id":"TEMP-001",
    "sensor":"temperatura",
    "valor":35,
    "unidad":"°C",
    "timestamp":"2026-05-22 15:30:00"
  }
]

Sensor de presión

[
  {
    "device_id":"PRESION-001",
    "sensor":"presion",
    "valor":120,
    "unidad":"PSI",
    "timestamp":"2026-05-22 15:30:00"
  }
]

Ejemplo utilizando PHP

    "success": true,
    "message": "Lecturas procesadas correctamente",
    "message_code": "ok",
    "processed": 2
}

Respuesta con error

API Key inválida

{
    "success": false,
    "message": "API Key inválida",
    "message_code": "error_001",

}

Dispositivo no registrado

{
    "success": false,
    "message": "Dispositivo no encontrado",
    "message_code": "error_002",

}

Recomendaciones

Consultar primero con el equipo TI de OBUMA ERP sobre la intención de uso de su proyecto y necesidades.
Registrar previamente los dispositivos en el módulo IoT de OBUMA ERP.
Mantener sincronizada la fecha y hora de los dispositivos.
Utilizar nombres de sensores consistentes para facilitar los reportes.
Agrupar múltiples lecturas en una sola solicitud para optimizar el tráfico de red.
Evitar enviar datos duplicados para una misma fecha y hora.

Casos de Uso

La API IoT puede utilizarse para:

Monitoreo energético.
Control de consumo eléctrico.
Lectura de medidores DDS238.
Monitoreo de temperatura y humedad.
Control de presión en procesos industriales.
Monitoreo de maquinaria.
Control de horas de funcionamiento (horómetros).
Facturación basada en consumo.
Generación de alertas automáticas.
Dashboards operacionales en tiempo real.