API de la plataforma IoT: intégrala con tu ERP, BI y GIS

La API de la plataforma IoTITérminoIoT (Internet de las cosas)El IoT (Internet of Things) es la red de objetos físicos con sensores, software y conectividad que recogen e intercambian datos y actúan de forma autónoma.Ver perfil decide si los datos de los sensores se quedan en un panel o llegan al ERP, al BI y al GIS donde tu cliente toma decisiones.

Sofía dirige la operación de una empresa de aguas que da servicio a 60.000 viviendas. Hace dos años, su integrador conectó 9.000 contadores inteligentes y montó unos paneles que gustan en la sala de control. Después llegó la rutina de cada mes. El día 1, alguien de administración exporta una hoja de cálculo con las lecturas y teclea los totales en el ERP. Cada viernes, el equipo de GIS descarga un CSV para actualizar el mapa de fugas.

Los contadores están conectados y la plataforma funciona, pero la integración entre sistemas sigue siendo cosa de dos personas copiando datos a mano.

Esta guía explica qué es una plataforma IoT API-first, los tres patrones para sacar datos de ella y cómo conectarla con el ERP, las herramientas de inteligencia de negocio (BI) y los sistemas de información geográfica (GIS) sin romper ninguno. Está pensada para integradores y fabricantes de equipos que llevan proyectos IoT a empresas que ya usan otro software. Si antes quieres un punto de partida sin código, mira cómo conectar Zapier a una plataforma IoT.

Qué significa que una plataforma IoT sea API-first

Una plataforma API-first expone sus funciones a través de interfaces documentadas a las que otros programas pueden llamar. Las pantallas son un cliente de esas interfaces, y tus integraciones son otro. Todo lo que un usuario hace con clics, un programa lo puede hacer con llamadas.

En la práctica, una API de plataforma IoT útil cubre cuatro áreas:

• Datos. Valores actuales, histórico, alarmas y eventos.
• Configuración. Dispositivos, ubicaciones, usuarios y reglas de alarma.
• Órdenes. Fijar un valor o enviar una instrucción a un equipo.
• Estructura. La jerarquía de clientes, emplazamientos y activos, para que los sistemas externos sepan a qué pertenece cada equipo.

Qué comprobar antes de prometer una integración

Una presentación comercial que dice «API abierta» cuenta poco. Antes de comprometer una integración en una propuesta, busca:

1. Documentación pública con ejemplos, a ser posible en un formato legible por máquinas como la especificación OpenAPI.
2. Autenticación con tokens que se puedan limitar a permisos concretos.
3. Una forma de pedir solo lo que ha cambiado desde la última llamada.
4. Notificaciones de salida, para que la plataforma llame a tu sistema cuando pase algo.
5. Límites claros de tamaño de página y de peticiones.

Para comparar los dos protocolos que más te vas a encontrar, lee MQTT frente a REST para IoT.

Por qué le importa al integrador

El trabajo de integración es donde muchos proyectos IoT ganan su margen después de la instalación. Cada conexión con un ERP, una herramienta de BI o un mapa es un trabajo que el cliente valora y que rara vez quiere hacer solo. Además, es lo primero que pregunta el departamento de TI del cliente en un concurso: ¿cómo llegan los datos a los sistemas que ya pagamos?

Un proyecto con integraciones que funcionan también es más difícil de sustituir. Cuando las lecturas de los contadores entran en la facturación y las alarmas abren órdenes de trabajo, la plataforma forma parte de cómo el cliente lleva su negocio, una posición más sólida que la de un panel que alguien abre una vez por semana.

Tres patrones de integración: consultar, recibir y suscribirse

Cualquier integración con la API de una plataforma IoT usa uno de estos tres patrones, o una mezcla. Elegir el adecuado para cada flujo evita casi todos los problemas de rendimiento.

Consultar sin descargarlo todo

El error más común en las integraciones por consulta es pedir el conjunto completo de datos en cada ejecución. Es mejor una sincronización incremental. La plataforma asigna a cada registro nuevo o modificado un número de secuencia que solo crece. Tu integración guarda el número más alto que ha visto, pide los registros posteriores y repite.

Si la respuesta llega vacía, no hay nada nuevo y la integración espera antes de volver a intentarlo. Si llega llena, procesa la página y vuelve a preguntar enseguida. Los registros borrados o cerrados llegan por el mismo canal con una marca, así que el sistema externo se mantiene coherente sin una recarga completa cada noche.

El bucle cabe en una pizarra:

secuencia = cargar_punto_de_control() # 0 en la primera ejecución
repetir:
lote = pedir_registros(posteriores_a = secuencia)
si lote está vacío:
esperar 60 segundos
continuar
procesar(lote)
secuencia = número de secuencia más alto del lote
guardar_punto_de_control(secuencia)

Guarda el punto de control solo después de procesar la página. Si el proceso se detiene a medias, repetirá una página en lugar de saltársela.

Recibir los eventos que piden acción

Las alarmas son eventos, y deben viajar como eventos. Cuando el nivel de un depósito supera un umbral, la plataforma puede enviar una petición HTTP al sistema de mantenimiento y crear una orden de trabajo en segundos. Consultar las alarmas cada diez minutos añade diez minutos a cada respuesta.

Diseña la URL receptora para que el mismo mensaje procesado dos veces dé el mismo resultado. Las redes fallan, y un reintento tras un tiempo de espera es lo normal.

Un buen mensaje de evento lleva contexto suficiente para actuar sin una segunda llamada: el tipo de evento, los identificadores del equipo y del emplazamiento, el valor que lo disparó, la regla que saltó y la hora en UTC. Añade un identificador único del evento para que el receptor descarte duplicados. Protege la URL receptora con un secreto o un token que solo conozca la plataforma, y rechaza lo que llegue sin él. Si el sistema receptor va a estar parado por mantenimiento, acordad antes si los eventos se encolan, se reintentan durante un tiempo o pasan a un correo, para que nadie se pierda una alarma.

Suscribirse a los datos en directo

Cuando una pantalla tiene que actualizarse cada segundo, una suscripción a un broker funciona mejor que las consultas y que los webhooks. La guía sobre qué es un broker MQTT explica los tópicos, los mensajes retenidos y las sesiones.

Usar la API de la plataforma IoT con un ERP

Un ERP trabaja con pedidos, facturas, activos y centros de coste. No necesita una lectura por minuto. El trabajo de la integración es traducir los datos de los sensores a los registros que el ERP ya entiende.

Enviar registros de negocio, no lecturas en bruto

En la empresa de Sofía, la solución para la facturación mensual pasó por tres decisiones:

1. Asociar cada contador a su registro del ERP. La plataforma guarda el número de contrato del ERP como propiedad del equipo, así que los dos sistemas usan la misma clave.
2. Enviar una lectura por contador y periodo de facturación. Un proceso programado toma la última lectura válida antes de medianoche del último día del mes y la envía al ERP.
3. Marcar las excepciones en vez de adivinar. Los contadores sin lecturas en las últimas 48 horas van a una lista de revisión, donde antes se tecleaban estimaciones.

Administración dejó de teclear 9.000 cifras. La lista de revisión tiene una media de 40 contadores al mes, y cada uno es un problema real que merece una visita.

De la alarma a la orden de trabajo

El segundo flujo que compensa es el de mantenimiento. Una alarma sostenida en una bomba, un compresor o un contenedor de residuos puede abrir una orden de servicio en el ERP o en el sistema de gestión del mantenimiento (GMAO). Un patrón habitual usa automatización robótica de procesos: la alarma activa un bot que crea la orden dentro del ERP con los mismos pasos que seguiría una persona, de modo que la transacción queda registrada y auditada. La guía para implementar IoT industrial muestra dónde encaja esto en un despliegue en planta.

Dónde vive la lógica de integración

La correspondencia entre los datos de la plataforma y los registros del ERP tiene que ejecutarse en algún sitio. Las opciones habituales son una plataforma de integración que el cliente ya tenga, un pequeño servicio escrito por tu equipo, las herramientas de importación del propio ERP o una herramienta de flujos de bajo código como Node-REDNTérminoNode-REDNode-RED es una herramienta de programación visual basada en flujos para conectar dispositivos, APIs y servicios, muy usada en automatización e IoT.Ver perfil. Elijas la que elijas, mantén la correspondencia en un solo sitio, registra cada mensaje con su resultado y da al equipo de TI del cliente una forma de ver los fallos sin llamarte. Una integración que solo sabe depurar quien la escribió acaba siendo un contrato de soporte que nadie presupuestó.

Alimentar herramientas de BI sin saturarlas

Las herramientas de BI están hechas para analizar tablas, y sufren cuando reciben miles de millones de lecturas en bruto por HTTP. Tres reglas mantienen rápidos los informes y controladas las llamadas a la API:

• Agrega antes de analizar. Casi todas las preguntas de negocio necesitan valores por hora o por día: consumo por emplazamiento, horas de funcionamiento por máquina, alarmas por semana.
• Usa una capa intermedia. Un proceso incremental carga los datos nuevos en una base de datos o un almacén de datos, y la herramienta de BI lee de ahí. Si un informe apunta directamente a la API, cada actualización vuelve a llamar a la plataforma.
• Guarda la hora en UTC. Convierte a hora local en el informe. Mezclar husos horarios es la forma más rápida de perder una hora de datos dos veces al año.

Datos que llegan tarde y correcciones

Los equipos con mala conexión a veces envían lecturas con horas de retraso, y los gateways con búfer local las envían en ráfagas. Una sincronización incremental basada en números de secuencia recoge esas lecturas tardías, porque reciben un número nuevo al llegar. Una sincronización basada solo en marcas de tiempo se las salta. Cuando lleguen datos tardíos, recalcula los agregados de los días afectados.

¿Preparas una integración para el equipo de datos de un cliente? La documentación técnica describe en detalle las API de extracción de datos.

Sensores en el mapa: integración con GIS

Ayuntamientos, empresas de servicios y operadores logísticos piensan en mapas. Una integración con GIS coloca cada equipo en su sitio y lo pinta según su estado.

La mayoría de herramientas GIS leen GeoJSON, un formato definido en la RFC 7946 que usa coordenadas WGS 84 en grados decimales. Los servidores GIS más recientes también publican y consumen datos a través de OGC API Features, una interfaz web estándar para objetos geográficos. Una integración suele necesitar:

• Coordenadas fijas para activos estáticos como contadores, contenedores o farolas, guardadas como propiedades del equipo.
• Posiciones en directo para activos móviles como vehículos, actualizadas con las lecturas GPS.
• Geozonas, para que la plataforma lance alarmas cuando un activo entra o sale de un área y el GIS dibuje los mismos límites.

Un mapa que el ayuntamiento usa cada día

Andrés trabaja en una empresa integradora que gestiona los sensores de contenedores de residuos de un municipio de 150.000 habitantes. El equipo de operaciones quería ver el nivel de llenado en el mapa que ya usaba para la limpieza viaria, no en un panel aparte. Su equipo montó un pequeño proceso que consulta el estado de los contenedores cada cinco minutos y lo publica como una capa GeoJSON. El mapa muestra cada contenedor en verde, ámbar o rojo, y el planificador de rutas lee la misma capa.

La ubicación merece cuidado. Cuando una posición se puede asociar a una persona, como el vehículo de un conductor o la tarjeta de un operario, es un dato personal según el RGPD. Limita quién puede ver las posiciones en directo, guarda el histórico solo el tiempo que exija su finalidad y acuerda esas reglas con el cliente antes de publicar el mapa.

En los proyectos de ciudad inteligente en Europa, los concursos públicos suelen pedir compatibilidad con FIWARE. La API de contexto de FIWARE, NGSIv2, y su sucesora basada en datos enlazados, NGSI-LD, permiten que varios sistemas municipales compartan las mismas entidades. La guía de LoRaWAN para ciudades inteligentes cubre la parte de red de esos proyectos.

Lista de seguridad y fiabilidad para integraciones por API

Una integración es una puerta nueva a la plataforma y necesita el mismo cuidado que una cuenta de usuario. El OWASP API Security Top 10 sitúa como primer riesgo de 2023 la autorización rota a nivel de objeto: una API que devuelve un objeto porque quien llama conoce su identificador, sin comprobar si tiene permiso para verlo.

1. Un token por integración. Si se filtra el token del proceso de BI, lo revocas sin parar el flujo del ERP.
2. Mínimo privilegio. El token de BI lee datos. No crea usuarios ni envía órdenes.
3. Tokens en cabeceras, no en URL. El estándar de tokens bearer de OAuth, la RFC 6750, desaconseja enviarlos como parámetros de consulta porque las URL acaban en los registros.
4. Respeta las páginas y los límites. Lee por páginas y reduce el ritmo cuando la plataforma lo pida.
5. Reintentos seguros. El sistema receptor tiene que reconocer un mensaje que ya ha procesado.
6. Vigila la integración. Configura un aviso para cuando la sincronización se retrase o un webhook empiece a fallar. Una integración que calla se parece mucho a un día tranquilo.

Prueba cada integración en un entorno de pruebas con datos realistas antes de que toque producción. Un error de correspondencia que crea 9.000 facturas duplicadas se detecta mejor con registros de prueba que con clientes reales. La guía de ciberseguridad OT para IA industrial e IoT trata la parte de red del mismo problema.

Cómo facilita Cloud Studio IoT la integración por API

Cloud Studio IoT expone su plataforma a través de API que los integradores usan cada día:

• API REST de extracción de datos para valores de endpoints, alarmas, reglas de alerta, geozonas y la jerarquía de clientes y emplazamientos, todas con sincronización incremental por número de secuencia y páginas de hasta 500 registros.
• Servicios de plataforma para gestionar dispositivos, paneles y órdenes.
• Autenticación con tokens que respetan los mismos permisos por rol que la interfaz de usuario, enviados en la cabecera de autorización.
• Acciones que pueden incluir un paso de petición HTTP, para que una alarma llame a un sistema externo en cuanto salta.
• Un broker MQTTBTérminoBroker MQTTUn broker MQTT es el servidor central que recibe los mensajes de los publishers y los distribuye a los subscribers según los temas. Ejemplos: Mosquitto, EMQX, HiveMQ.Ver perfil integrado para dispositivos y datos en directo.
• Compatibilidad con FIWARE, con datos expuestos mediante API NGSI, y un patrón documentado con SAP Build Process Automation que convierte alarmas físicas en transacciones auditadas del ERP.

Los asistentes de IA son otro consumidor de las mismas API. El artículo sobre integración MCP y plataforma IoT muestra cómo un modelo de lenguaje puede consultar los datos de la plataforma. Para los integradores que entregan con su propia marca, estas API funcionan igual en una plataforma IoT white-label.

Lo que conviene recordar

• La API de la plataforma IoT solo sirve si cubre datos, configuración, órdenes y estructura, con documentación y tokens con permisos acotados.
• Usa consultas con sincronización incremental para informes, eventos para lo que pide acción y suscripciones para las pantallas en directo.
• El ERP necesita registros de negocio, como lecturas de facturación y órdenes de trabajo, no lecturas en bruto.
• Las herramientas de BI funcionan mejor con datos agregados en una capa intermedia, la hora en UTC y las lecturas tardías bien tratadas.
• Las integraciones con GIS se apoyan en formatos estándar como GeoJSON y OGC API Features, y en el NGSI de FIWARE en muchos concursos de ciudad inteligente.
• Trata cada integración como un usuario: su propio token, mínimo privilegio y vigilancia.

Si los sistemas de tu cliente esperan los datos que tus equipos ya recogen, mira lo que incluye la plataforma IoT o habla con el equipo y trae la lista de sistemas que necesitas conectar.