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

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.