API REST, webhooks y CSV en Captia Connect: las tres vías de integración IT

Cómo habla Captia Connect API REST, webhooks y CSV

Estas tres vías cubren todo lo que entra o sale de la plataforma sin pasar por un bus de campo: el ERP, el MES, el CRM, el laboratorio, la báscula, el portal cloud del fabricante de una máquina y la aplicación heredada que nadie quiere tocar. Connect las trata como adquisición, igual que trata OPC UA o Modbus: cada una es un conector que corre en el nodo edge, dentro de su contenedor Docker, escribe en la base de series temporales local y sincroniza hacia la plataforma por el enlace saliente de Tailscale. Lo que cambia entre ellas no es el destino, es quién inicia la conversación y qué garantías trae el dato al llegar.

La diferencia de fondo con un protocolo de planta es que aquí no hay una variable muestreándose de forma continua. Hay registros y eventos de negocio con una clave, un instante y unos campos, y la mayoría de los problemas de una integración de este tipo no son de red: son de identidad, de huso horario y de esquema.

API REST: Connect como cliente que consulta

En REST el que pregunta es Connect. El conector se configura contra una URL base sobre HTTPS en el puerto 443, con verificación de certificado, y ejecuta un ciclo de consulta cuya cadencia se decide por el negocio, no por la técnica: si el ERP cierra órdenes de fabricación cada turno, sondear cada quince segundos solo añade carga al ERP y no adelanta ninguna decisión. La horquilla útil va del minuto a la hora, y hacia arriba para maestros que cambian poco (referencias, centros de coste, calendarios de turno).

La autenticación se resuelve de tres formas, por orden de frecuencia real en instalaciones industriales. Clave de API en cabecera, que es lo más común y lo más frágil, porque no caduca y suele venir con más permisos de los que hacen falta. OAuth 2.0 con flujo de credenciales de cliente, donde Connect pide un token, lo guarda en memoria y lo renueva antes de que expire en lugar de esperar al primer 401. Y autenticación básica sobre TLS, que aparece en sistemas antiguos y obliga a extremar el cuidado con la cuenta. El criterio de partida es siempre el mismo: usuario dedicado, permisos de lectura, y ámbito limitado a los recursos que la integración necesita.

La paginación es donde se pierden datos sin que nadie se entere. Una respuesta que devuelve doscientos registros cuando hay mil no da ningún error. Connect recorre las páginas hasta agotar el conjunto, y el modo depende de lo que ofrezca el origen: cursor o token de continuación, que es el mecanismo fiable porque no se descoloca si llegan registros nuevos durante el recorrido, o desplazamiento y límite, que sí se descoloca y obliga a ordenar por un campo estable. Se fija además un tope de páginas por ciclo para que una carga inicial de años de histórico no monopolice el conector.

La consulta es incremental. Connect guarda una marca de agua con el instante del último registro traído y en el ciclo siguiente pide solo lo posterior, con un solapamiento deliberado de la ventana hacia atrás. Ese solapamiento existe porque los sistemas de gestión escriben con retraso: un albarán con fecha de las 10:00 puede aparecer en la base de datos a las 10:04, y una ventana sin solape lo dejaría fuera para siempre. El precio del solape es traer registros repetidos, y por eso el control de duplicados no es opcional: cada registro se identifica por su clave natural en el sistema origen combinada con su instante, y la reingesta de esa misma clave sobrescribe en lugar de añadir. Sin esa regla, cada solape infla los totales y el primer informe de producción sale mal.

Ante fallo, el conector distingue. Un 429 con cabecera de reintento se respeta tal cual, un 5xx se reintenta con espera exponencial y algo de aleatoriedad para no sincronizar todos los conectores contra el mismo servidor, y un 4xx que no sea 429 no se reintenta nunca: es un error de configuración o de permisos y lo que corresponde es avisar, no insistir. Mientras tanto la adquisición de planta sigue, porque estos conectores son independientes entre sí.

Webhooks: Connect como receptor de eventos

En webhooks se invierte el sentido: el sistema de negocio empuja el evento en cuanto ocurre y Connect expone un receptor HTTPS que lo recibe. Se gana latencia, del orden de segundos en lugar del ciclo de sondeo, y se pierde control, porque el que decide si el dato llega es el emisor. Todo el trabajo de ingeniería está en devolverle ese control al receptor.

Verificación de origen. Una URL de webhook es pública por definición, así que cualquiera que la conozca puede enviarle un cuerpo. Connect valida la firma HMAC que el emisor calcula sobre el cuerpo crudo con un secreto compartido, comparándola en tiempo constante y sobre los bytes recibidos antes de deserializar, porque volver a serializar el objeto cambia el orden de las claves y rompe la firma. La firma incluye una marca de tiempo, y las peticiones fuera de una ventana corta se descartan para que una petición legítima capturada no pueda reenviarse más tarde. Cuando el emisor lo soporta se añade TLS mutuo o una lista de direcciones de origen permitidas. Lo que no se hace nunca es aceptar un webhook sin verificación porque el emisor no ofrezca firma: en ese caso la vía correcta es el sondeo REST.

Reintentos e idempotencia. Los emisores serios reintentan cuando no reciben un 2xx, y ese comportamiento tiene una consecuencia directa en el diseño del receptor: Connect acusa recibo en cuanto ha validado y persistido el evento, y hace el procesamiento después. Si el receptor procesa en línea y tarda más que el tiempo de espera del emisor, el emisor da la entrega por fallida y la repite, con lo que el mismo evento se cuenta dos veces aunque el primer intento hubiera terminado bien. Por eso cada evento se registra con el identificador que trae el emisor y los identificadores ya vistos se retienen durante una ventana suficiente para cubrir toda la política de reintentos del origen. La entrega es «al menos una vez»; la idempotencia del receptor es lo que la convierte en «exactamente una» a efectos del histórico.

Dónde vive el receptor. No se publica un puerto entrante en la red de planta para recibir webhooks. El receptor se expone en el lado plataforma y el evento baja al nodo edge por el mismo enlace Tailscale que ya usa la sincronización, o bien el receptor corre en el nodo y solo es alcanzable dentro de la red privada del enlace. La red industrial no gana ninguna superficie expuesta a internet por integrar un webhook.

CSV: ingesta programada de ficheros

El CSV sigue vivo porque es la única salida que ofrecen muchos sistemas de laboratorio, muchos indicadores de pesaje y casi todos los programas heredados. Connect lo recoge de una ubicación acordada, normalmente un directorio SFTP o una carpeta de red, con una frecuencia programada, y lo trata como un lote, no como un flujo.

Antes de leer una sola fila hay que fijar cinco cosas del formato, y ninguna se puede adivinar de forma fiable. El separador, que en exportaciones de hoja de cálculo hechas en un equipo con configuración regional española es punto y coma y no coma. La codificación, donde conviven UTF-8, UTF-8 con marca de orden de bytes (que si no se retira convierte el nombre de la primera columna en algo que no coincide con el esquema) y las páginas de código heredadas que rompen las eñes y los acentos. El separador decimal, coma o punto, que combinado con el separador de campo produce el clásico fichero donde 1.234,5 y 1,234.5 significan cosas opuestas. El formato de fecha, donde 03/04 es ambiguo hasta que alguien declara si es marzo o abril, y donde la ausencia de zona horaria es el error más caro. Y el fin de línea junto con el entrecomillado, porque un campo de texto con un salto de línea dentro y comillas mal escapadas descuadra el resto del fichero.

El fichero que un día cambia de columnas. Este es el modo de fallo real del CSV y merece tratarse aparte, porque no falla de forma ruidosa, falla en silencio. Alguien actualiza el informe de origen, inserta una columna nueva en tercera posición y a partir de ese lote la columna que se leía como peso pasa a contener el número de lote. Si el conector se apoya en la posición, sigue ingiriendo sin protestar y el histórico se contamina hasta que alguien mira una gráfica y no cuadra. Connect lo evita apoyándose en la cabecera declarada, no en el índice de columna: el esquema del lote se compara con la primera fila del fichero antes de procesar nada. Si aparece una columna nueva que no se usa, se ignora y se registra. Si desaparece o cambia de nombre una columna que sí se usa, el lote entero se rechaza y se avisa; nunca se ingiere un fichero a medias. Esa política, y la conversación con el responsable del sistema origen que la acompaña, es lo que el recurso de contratos de datos industriales desarrolla en general.

Quedan dos detalles operativos que evitan la mayoría de las incidencias. El primero es la atomicidad: un fichero que se está escribiendo no debe leerse, así que el origen escribe con nombre temporal y renombra al terminar, o deposita un fichero marcador al cerrar, y el conector solo toma lo que está completo. El segundo es la idempotencia del lote: cada fichero procesado se identifica por nombre y por huella de su contenido, de modo que reprocesar la misma exportación, algo que pasa cada vez que alguien vuelve a dejar el fichero de ayer, no duplica ni una fila.

Qué sistemas se integran por estas vías

Aquí no hay equipos con bornas ni cables apantallados. Hay software, y conviene separarlo por familias porque el trabajo de integración cambia mucho de una a otra.

Los sistemas de gestión son el caso mayoritario: ERP, MES, CRM y las suites corporativas tipo SAP. Aportan el eje de contexto que la planta no tiene: la orden de fabricación, la referencia que se está produciendo, el lote, el turno, el cliente y el coste. Casi todos ofrecen API REST, y los más modernos también webhooks para los cambios de estado. Es la integración que convierte una curva de consumo en un consumo por unidad producida, y el servicio que la implanta es integración con ERP.

Los sistemas de laboratorio y calidad entregan resultados de ensayo con varias horas de retraso respecto al proceso que los generó. Muchos exportan CSV a una carpeta y poco más. El dato es de baja frecuencia y alto valor, y su integración es casi siempre por fichero.

Los instrumentos con salida de fichero o de línea: básculas y sistemas de pesaje, tituladores, analizadores de banco y equipos de ensayo. Emiten un ticket o una línea por medida, a menudo por un puerto serie que un concentrador vuelca a fichero. Se integran como CSV, con la particularidad de que el fichero crece por el final y hay que llevar la cuenta de hasta dónde se leyó.

Los sistemas heredados sin protocolo industrial: la aplicación de gestión de almacén escrita hace veinte años, el programa de mantenimiento del que ya no queda soporte. Suelen tener una base de datos detrás y, con suerte, una vista o un procedimiento que alguien puede exponer como API delgada o volcar a fichero de forma programada. Si no tienen ni eso, ver la sección de límites.

Los servicios externos por API: la comercializadora eléctrica y el precio horario de la energía, la previsión meteorológica que alimenta el pronóstico de generación fotovoltaica, los portales cloud de fabricantes de maquinaria que publican la telemetría de sus propios equipos. Aquí Connect es cliente de un tercero y no controla ni la disponibilidad ni los límites de tasa, lo que hace del control de reintentos algo más que un detalle.

Fuera de estas familias está lo que sí es planta, y para eso están las otras vías: PLC y controladores por OPC UA, variadores, analizadores de red y autómatas por Modbus, sensórica y pasarelas que publican por su cuenta por MQTT.

De registro de negocio a serie temporal

Un nodo de un PLC entrega un valor con su tipo y su instante. Un registro de un ERP entrega una fila con veinte campos de los que Connect necesita identificar tres cosas: cuál es el instante, cuál es la identidad y cuáles son las magnitudes con su unidad. Ese es todo el mapeo, y hacerlo mal en cualquiera de los tres puntos produce un histórico que parece correcto y no lo es.

El instante. Se toma el campo de fecha declarado por el sistema origen, no el momento en que Connect recibió el registro, exactamente por la misma razón que en un protocolo de planta: un lote que llega con retraso o un webhook reintentado quedarían agrupados en el instante de llegada y falsearían la dinámica. El campo se normaliza a un instante con zona horaria explícita. Cuando el origen entrega hora local sin zona, y es lo habitual en un CSV, la zona se declara en la configuración del conector: sin esa declaración, el cambio de hora de octubre produce una hora que aparece dos veces y el de marzo una hora que no existe, y ambas cosas rompen los agregados de consumo justo en el turno de noche.

La identidad. Cada registro necesita una clave estable en el sistema origen: el número de orden, el identificador del evento, el código de lote. Esa clave es la que hace la ingesta idempotente y es también la que permite el cruce con la planta. Si el ERP dice que la orden 48213 se fabricó entre las 06:12 y las 09:40, esa clave es lo que convierte la curva de potencia de esa línea en el consumo de esa orden.

Las magnitudes y su unidad. Ni un JSON ni un CSV declaran unidades. Un campo llamado energia puede venir en Wh o en kWh y la diferencia son tres órdenes de magnitud que nadie detecta si la escala del gráfico se ajusta sola. La unidad se fija en el mapeo, se documenta y se valida con un rango plausible, de forma que un valor imposible levante un aviso en lugar de entrar en la serie.

Hay además una diferencia de naturaleza que conviene explicitar. Muchos de estos datos no son muestras de una señal continua, son estados con validez: la orden en curso, el turno activo, la referencia que se está produciendo. Se modelan como escalones que valen hasta el siguiente cambio, no se interpolan, y esa distinción es la que evita gráficas rampantes entre dos eventos que nunca fueron una rampa. El trabajo general de dar contexto a la señal está en la guía de contextualización de datos industriales, y el marco general de captura, en la de sistema de adquisición de datos.

Cuándo estas vías no son las adecuadas

Las integraciones estándar son cómodas y por eso se usan de más. Estos son los casos en los que hay que decir que no.

El dato es una señal de proceso de un equipo de planta. Es el error más frecuente y el más caro. Si lo que se quiere es la potencia de una línea, la temperatura de un horno o el estado de una máquina, la vía no es una API intermedia sino el equipo directamente, por OPC UA, Modbus o MQTT. Sondear una API cada minuto no equivale a una suscripción: se pierde todo lo que ocurre entre consultas, se hereda la agregación que aplicó el sistema intermedio y se depende de que ese sistema esté vivo. Un pico de arranque de dos segundos no existe en una API que se consulta cada minuto.

Se necesita latencia de segundos y solo hay REST. Bajar la cadencia de sondeo tiene un techo impuesto por el sistema origen, que empieza a devolver 429 o sencillamente a ir lento para todo el mundo. Si el origen ofrece webhook, esa es la vía. Si no lo ofrece y la latencia es de verdad un requisito, la conclusión honesta es que ese dato hay que tomarlo en otro sitio.

Se necesita entrega garantizada y solo hay webhook. Un webhook que no llega no deja rastro en ningún sitio: si el emisor no reintenta, o agota sus reintentos durante una ventana de mantenimiento, el evento simplemente no existió. Para cualquier dato que luego se vaya a facturar, auditar o declarar, el webhook no puede ser la única fuente; se acompaña de una reconciliación periódica por REST que compara lo recibido con lo que el origen dice haber emitido.

El CSV lo genera una persona a mano. Una exportación manual se olvida en vacaciones, se guarda con otro nombre, se abre en una hoja de cálculo que reformatea las fechas al guardarla y termina cambiando de columnas. Si el sistema origen tiene API o acceso de lectura a su base de datos, ese camino cuesta más al principio y menos cada mes. El CSV automático depositado por un proceso programado es otra cosa y sí es una vía sólida.

El fichero completo crece sin parar. Un CSV que reenvía todo el histórico en cada ciclo obliga a comparar cada vez contra todo lo ingerido y termina dominando el tiempo de proceso del conector. Cuando el volumen crece, hay que pedir al origen exportación incremental o pasar a API.

El sistema origen no ofrece ni API ni exportación. Aplicaciones cerradas sin interfaz de datos y sin acceso a su base. Aquí no hay integración estándar posible por ninguna de las tres vías, y presentarla como si la hubiera es engañar al cliente. Lo que procede es un desarrollo específico contra ese sistema, que es trabajo de integración OT e IT, no una configuración de conector.

Y el límite que no es técnico, que es el que de verdad rompe estos proyectos: sin un acuerdo sobre el esquema no hay integración estable. Alguien del lado del sistema origen tiene que ser responsable de avisar antes de cambiar un campo, una unidad o un formato de fecha. Cuando ese acuerdo no existe, la integración no falla el día uno, falla el día en que alguien actualiza un informe, y la única defensa posible es la que se describe en contratos de datos industriales: validar el esquema en cada lote y rechazar en vez de ingerir a ciegas.

Convivencia con el resto de la instalación

Estas tres vías no compiten con los protocolos de planta, se cruzan con ellos. La planta aporta el eje temporal, denso y de alta frecuencia; los sistemas de negocio aportan el eje de contexto, escaso y cargado de significado. Connect adquiere por ambos lados en paralelo y los deja en el mismo modelo de series temporales, que es lo que permite que una pregunta como cuánta energía costó fabricar esta referencia tenga respuesta sin que nadie exporte nada a mano. Ese cruce es el objeto de la convergencia OT e IT.

En una misma instalación es normal que las tres vías convivan entre sí, y no por desorden: cada sistema ofrece lo que ofrece. El ERP corporativo se consulta por REST cada quince minutos, el sistema de gestión de almacén empuja un webhook cuando se cierra una expedición y el laboratorio deja un CSV cada noche. Connect ejecuta los tres conectores de forma independiente, así que un origen caído no arrastra a los demás ni detiene la adquisición de planta.

El camino de madurez habitual recorre las tres en este orden. Se empieza por CSV, porque es lo que se puede montar en una tarde y demuestra el valor sin pedir nada a nadie. Se pasa a REST en cuanto el fichero manual empieza a fallar o el volumen molesta, y ese salto suele coincidir con el momento en que el departamento de sistemas se sienta en la mesa. Y se añaden webhooks al final, solo donde la latencia lo justifica, manteniendo el sondeo REST por debajo como red de reconciliación. Sustituir el sondeo por el webhook, en vez de superponerlos, es el atajo que se paga con el primer evento perdido.

Sobre esa base ya trabajan los módulos de la plataforma, el catálogo completo de vías está en el índice de protocolos de Connect y el proyecto de ingeniería que conecta planta y gestión es integración con ERP.