Integrar con el ERP: lo que el sistema del otro lado decide por ti

"¿Tiene API?" es la pregunta equivocada#

Cuando una empresa contrata un sistema nuevo que va a convivir con el ERP que ya usa, la primera pregunta técnica es casi siempre la misma: "¿tiene API?". La respuesta es sí o no, y ninguna de las dos informa lo que realmente decide el proyecto.

Construimos tres integraciones con sistemas de terceros, todas en producción:

• NextFit, el ERP de una cadena de gimnasios, de donde leemos las ventas que alimentan la meta comercial de la red.
• Altimus, el sistema de inventario de vehículos de un concesionario, de donde leemos los vehículos que entran en una financiación.
• Controlle, el ERP financiero que usa nuestra propia empresa, de donde leemos movimientos y saldos para el panel de los socios.

Los tres respondieron cosas distintas a las preguntas de abajo — y cada respuesta negativa se convirtió en código nuestro.

Ninguna de estas cabe en un "¿tiene API?". Todas cambian el plazo, y algunas cambian el alcance.

Cómo saber que cambió algo del otro lado#

Ninguna de las tres fuentes avisa cuando algo ocurre. No hay webhook en ninguna, así que las tres integraciones son lo que el catálogo Enterprise Integration Patterns, de Gregor Hohpe y Bobby Woolf, llama Polling Consumer: es tu sistema el que pregunta, al ritmo que elige.

A partir de ahí, cada fuente permite un nivel distinto de precisión:

• Cuando la fuente acepta filtrar por fecha de modificación, pides solo lo que cambió desde la última lectura. Es el caso de NextFit.
• Cuando acepta un rango de fechas, trabajas con una ventana móvil y reprocesas el intervalo entero. Es el caso de Controlle.
• Cuando no filtra nada, lees la base completa y comparas registro por registro contra lo que ya tienes guardado. Es el caso de Altimus.

El detalle que suele escaparse aparece en el primer caso. La ventana de NextFit es por fecha, sin hora — así que en cada lectura devuelve el día entero otra vez. Volver a grabarlo todo sería trabajo tirado, así que recortamos localmente lo que cambió desde la última sincronización, con un margen de algunos minutos hacia atrás. Ese margen cubre el desfase de reloj y el registro modificado en el instante exacto en que terminaba la lectura anterior. Releer es inofensivo porque la escritura es idempotente — el mismo registro leído dos veces produce el mismo resultado —, que es el patrón Idempotent Receiver del mismo catálogo.

Y hay un agujero que aparece meses después, cuando nadie está mirando: la sincronización incremental no recupera lo que perdiste. Si un registro antiguo dejó de guardarse por cualquier motivo, su fecha de modificación ya quedó atrás, y ninguna lectura incremental futura lo va a traer de vuelta. Los dos proyectos que usan incremental tuvieron que ganar un hermano: en la cadena de gimnasios, un modo de carga completa del período; en el panel financiero, una recarga total semanal que ignora el incremental y barre meses hacia atrás.

La regla que sacamos de ahí: todo sync incremental necesita un hermano que ignore el incremental. Sin él, el error silencioso es permanente.

Cómo saber que borraron algo del otro lado#

Esta es la pregunta que casi nunca entra en el alcance, y la que más problemas da. Una fuente de datos dice bien lo que existe; casi ninguna dice lo que dejó de existir.

La salida es la reconciliación por ausencia: lo que no vino en la lectura completa se marca como inactivo de tu lado. Así sabemos que un vehículo salió del inventario del concesionario — el sistema de origen nunca envía "eliminado", simplemente deja de mandar ese registro.

Solo que la misma técnica, aplicada sin cuidado, borra lo que no debía:

• Si la lectura es de una ventana, la desactivación tiene que estar acotada a esa misma ventana. En el panel financiero, que un movimiento desaparezca de los últimos meses significa que fue eliminado; que un movimiento de hace tres años no aparezca allí significa solamente que está fuera del recorte. Desactivar por ausencia sin acotar borraría el histórico entero.
• La desactivación solo puede ocurrir después de que la lectura termine completa. Una carga interrumpida a la mitad no puede interpretarse como "desapareció todo lo que falta".

Cuando el ERP no tiene API#

El concesionario usa Altimus para controlar el inventario. Pedimos acceso a la API. Altimus no la tiene, y no la abre — es decisión del proveedor, y no tiene ninguna obligación de cambiarla porque un cliente lo pidió.

Lo que existía era una dirección que devuelve el inventario entero en JSON. Eso no es una API: no filtra por fecha, no avisa de eliminaciones, no tiene contrato publicado. La decisión de trabajar sobre eso se tomó en conjunto con el cliente — modelar algo con sentido sobre lo que existía y sincronizar periódicamente, en vez de esperar una apertura que no iba a llegar.

Lo que esa integración compró fue específico y valioso: se acabó volver a cargar los datos del vehículo. Quien arma una financiación escribe la patente o el número de chasis, y el resto de los datos del vehículo llega ya completo. Dejó de existir el paso de copiar a mano, de un sistema al otro, datos que ya estaban escritos.

Lo que cobró, en código que no existiría si hubiera una API:

• el cálculo de lo que cambió, comparando la fecha de actualización de cada ítem con la que está guardada;
• la reconciliación por ausencia, para descubrir qué salió del inventario;
• las fotos descargadas y rehospedadas en la nube del cliente, porque una dirección de imagen de un tercero está fuera de tu control;
• tolerancia a error por ítem, para que un registro extraño no tumbe la carga entera;
• progreso visible y botón de detener, porque la carga es lo bastante larga como para que alguien necesite interrumpirla.

El "no" que vale registrar: una exportación no es una integración — pero resuelve. El error no es aceptar la exportación; es tratarla como equivalente a una API a la hora de cerrar el alcance.

Cuánto de tu producto decide el ERP#

Esta es la parte cara, y la que casi ningún material sobre integración menciona.

En el concesionario, el plan no era quedarse en el inventario. La integración iba a alcanzar también la base de clientes, y a partir de ahí otros flujos entre los dos sistemas. Se quedó en el inventario, porque el inventario era el único dato que la fuente entregaba. El límite del proveedor se volvió el límite del producto.

Eso todavía se ve en la pantalla: el módulo de inventario se alimenta enteramente de Altimus — no existe alta manual de vehículo ahí dentro. Pero no todo vehículo financiado está en Altimus. Entonces la financiación acepta un vehículo que solo existe dentro de ella, y el atajo a la ficha completa del inventario simplemente no aparece en esos casos. Es la marca, en la interfaz, de una fuente que no cubre todo.

En el otro extremo, la cadena de gimnasios muestra lo que se puede hacer cuando la fuente entrega: como NextFit tiene una API de verdad, fue posible establecer que ninguna venta entra en el sistema nuevo salvo por NextFit. El ERP sigue siendo el dueño del dato, y la plataforma nueva nunca acepta una carga manual de ese dato. Eso es lo que hace que el número deje de depender de quién lo escribió.

Incluso con API, la fuente guarda trampas. En esa integración, una venta de convenio llega marcada con la misma característica que identifica una venta de plan — y el orden en que pruebas las condiciones decide si el convenio entra o no en el cálculo de la meta. Una clasificación escrita en el orden intuitivo habría inflado la meta de todas las unidades, en silencio y para siempre. Descubrir eso no es leer documentación: es abrir los datos reales antes de escribir la regla.

Cómo falla la integración sin tumbar tu sistema#

El sistema del otro lado se va a caer, va a cambiar un campo sin avisar o va a devolver errores durante una hora. Eso no es una hipótesis, es rutina. Lo que se diseña es el comportamiento de tu sistema cuando ocurre:

1. La sincronización nunca tumba el proceso. Registra la falla, guarda el mensaje y devuelve el resultado como "no salió bien" — mientras las pantallas siguen sirviendo el último dato sincronizado.
2. El error se trata por ítem, no por carga. Un registro con formato inesperado se registra y se salta; los otros miles continúan.
3. La alerta se dispara por fallas consecutivas, y una sola vez. En el panel financiero el aviso sale cuando el contador de fallas seguidas alcanza el límite — y no se repite en cada falla siguiente. Una alerta que se repite se vuelve una alerta ignorada.
4. La ejecución huérfana hay que limpiarla. Un proceso que muere a la mitad deja la sincronización marcada como "en curso" para siempre, y el bloqueo que evita ejecuciones simultáneas pasa a bloquear todas las próximas. El panel financiero libera las ejecuciones trabadas al iniciar.
5. Nada de cuerpo de respuesta en el log. Cuando el dato es financiero, el registro guarda ruta, estado y duración — nunca el contenido ni la credencial.

Cada cuánto sincronizar#

No existe "la frecuencia de la integración". Existe una frecuencia por tipo de dato, y el panel financiero lo deja en evidencia con tres ritmos conviviendo:

Dos criterios cierran la elección, y ninguno es técnico.

El primero es el horario de la operación. En la cadena de gimnasios la lectura es cada pocos minutos, pero solo en horario comercial: un gimnasio no vende de madrugada, y barrer toda la noche genera lecturas vacías — trabajo y costo sin información nueva.

El segundo es la naturaleza del dato. El dato financiero tiene futuro: una cuota por vencer y un movimiento previsto existen en el sistema antes de ocurrir. Por eso la ventana del panel financiero mira hacia atrás y hacia adelante, mientras que la ventana de ventas solo mira hacia atrás — una venta futura no existe. No es la API la que define la ventana de tu sync; es la naturaleza de lo que estás leyendo.

Una nota sobre el costo: cuando el acceso a la fuente es pago, la sincronización automática de las dos integraciones viene apagada por defecto y se enciende de forma consciente, en lugar de empezar a consumir sola en el primer despliegue.

Preguntas frecuentes#

¿El sistema nuevo puede reemplazar el ERP que ya uso?#

Puede, pero rara vez compensa. Un ERP consolidado carga años de reglas fiscales, contables y operativas que nadie quiere reescribir. El patrón que funciona es el contrario: el ERP sigue siendo el dueño del dato que ya es suyo, y el sistema nuevo resuelve lo que el ERP no resuelve — la lectura, la meta, el panel, el flujo que el equipo hace por fuera. Cuando cada dato tiene un dueño claro, los dos conviven sin divergir.

¿Y si mi ERP no tiene API?#

Todavía se puede integrar, con menos alcance. Muchos sistemas ofrecen alguna forma de exportación — un archivo, una dirección que devuelve la base entera, un informe programado. Eso no es una API: no avisa qué cambió ni qué se borró, así que ese trabajo pasa a ser tuyo. Funciona bien con datos que cambian despacio y se leen mucho más de lo que se escriben, como un catálogo o un inventario. No funciona para un flujo que necesita respuesta inmediata.

¿Cada cuánto se actualizan los datos?#

Depende del tipo de dato, no de la integración. Dentro de una misma aplicación tiene sentido actualizar catálogos una vez al día, movimientos cada hora y recargar todo una vez por semana. El dato que el equipo mira para decidir en el mismo turno pide minutos; el dato de catálogo pide un ciclo diario. Elegir una única frecuencia para todo desperdicia lecturas de un lado y atrasa del otro.

¿La integración puede sobrecargar mi ERP?#

Puede, y es el riesgo más subestimado. Si cada pantalla del sistema nuevo consulta el ERP en vivo, el pico de uso del sistema nuevo se convierte en un pico de peticiones en el sistema del que depende toda la empresa. La forma segura es replicar: un proceso lee el ERP a un ritmo controlado, guarda una copia local y todas las pantallas leen esa copia. El ERP pasa a recibir un volumen previsible, sin importar cuánta gente abrió el panel.

¿Qué pasa con mi sistema si el ERP se cae?#

Con una arquitectura de réplica, casi nada: las pantallas siguen sirviendo el último dato sincronizado y el sistema registra que la sincronización falló en lugar de romperse. Lo que no puede pasar es que la falla del tercero tumbe tu proceso — ni que se convierta en silencio. Nuestra regla es alertar después de algunas fallas seguidas, una sola vez, para que el aviso siga significando algo.

Fuentes#

• Enterprise Integration Patterns — "Idempotent Receiver", de Gregor Hohpe y Bobby Woolf, sobre recibir el mismo mensaje más de una vez sin efecto colateral — https://www.enterpriseintegrationpatterns.com/patterns/messaging/IdempotentReceiver.html
• Enterprise Integration Patterns — "Polling Consumer", de los mismos autores, sobre el consumidor que decide cuándo buscar — https://www.enterpriseintegrationpatterns.com/patterns/messaging/PollingConsumer.html

Próximo paso#

Antes de cerrar el alcance de cualquier sistema que vaya a convivir con un ERP, hazle las seis preguntas del comienzo de este texto al proveedor de la fuente, y por escrito. Cuestan un correo y deciden semanas de trabajo — incluida la posibilidad de descubrir, como descubrimos, que la respuesta es "no la tenemos y no la vamos a abrir".

Los dos casos citados aquí están publicados: la cadena de gimnasios, cuya meta comercial pasó a venir directo del ERP, y el concesionario, cuya plataforma de financiación lee el inventario del sistema de gestión. Es el tipo de trabajo que tratamos en integraciones y APIs — y, si tu caso es menos "convivir" y más "reemplazar", vale la pena leer cuándo hay que reemplazar un sistema heredado.