Integración de Wialon con ERP: arquitectura y errores

La mayoría de los proyectos de Wialon a ERP fracasan por razones poco evidentes: contratos de datos débiles, propiedad difusa y ninguna rutina de conciliación. Esta guía resume una arquitectura que se sostiene bajo carga operativa diaria.

Empiece por los eventos de negocio, no por los endpoints

El error más común en una integración de Wialon con un ERP es abrir la documentación de la Remote API y construir hacia afuera desde el catálogo de endpoints. El equipo inventaría cada llamada disponible — core/search_items, unit/get_messages, report/exec_report — y empieza a extraer datos antes de que nadie haya definido a qué pregunta de negocio responden. El resultado es un pipeline que sincroniza miles de mensajes crudos por hora y nadie en operaciones sabe qué hacer con ellos.

El diseño por eventos invierte el orden. Se empieza nombrando los eventos de negocio que importan: viaje terminado, geocerca cruzada, umbral de ralentí superado, anomalía en el nivel de combustible, turno de conductor iniciado. Cada evento tiene un consumidor claro en el ERP — la actualización del estado de una orden de transporte, un disparador de nómina, una orden de trabajo de mantenimiento. Solo después de nombrar los eventos y mapearlos a la acción que provocan se eligen las llamadas de la API de Wialon y los tipos de mensaje necesarios para detectarlos.

Este enfoque elimina una clase entera de desperdicio. En vez de traer cada mensaje de cada unidad y filtrar después, usted se suscribe a los tipos de notificación concretos o consulta los intervalos de mensajes concretos que producen los eventos definidos. La capa de extracción se achica, la lógica de transformación se vuelve explícita y el ERP recibe registros que efectivamente puede procesar. Cuando alguien pregunte «¿por qué el ERP no actualizó el viaje 4821?», usted puede rastrear desde la definición del evento de negocio hasta la llamada exacta y la ventana de mensajes.

Defina la propiedad de cada campo antes de programar

Toda superficie de integración entre Wialon y un ERP tiene campos compartidos: patente del vehículo, asignación de conductor, lectura de odómetro, capacidad del tanque. Cuando los dos sistemas pueden escribir el mismo atributo, la divergencia no es un riesgo: es una certeza. A las pocas semanas de salir a producción va a encontrar vehículos con odómetros distintos en cada sistema, conductores asignados en Wialon pero no en el ERP, y capacidades de tanque que se separaron después de una edición manual de un lado.

La solución es una matriz de propiedad de campos hecha antes de escribir código. Para cada atributo compartido, un sistema es el maestro y el otro el consumidor. Los metadatos del vehículo (VIN, patente, clase) suelen pertenecer al ERP, porque ahí viven compras y cumplimiento. Los campos de telemetría en vivo (posición GPS, lecturas de sensores, conductor actual por iButton) pertenecen a Wialon, porque ahí entra el hardware. El odómetro es más delicado: Wialon lo calcula desde GPS o desde el bus CAN, pero el ERP puede tener un «último odómetro verificado» de una inspección de mantenimiento. Hace falta una regla de precedencia: use el valor de Wialon para la operación diaria, pero permita que el ERP lo sobrescriba durante un evento de mantenimiento verificado.

Los eventos que llegan tarde crean un segundo problema de propiedad. Si un vehículo termina un viaje a las 23:50 pero el mensaje no llega al pipeline hasta la 01:15 del día siguiente, ¿de qué fecha es ese viaje? Si el ERP cierra su lote diario a medianoche, el viaje se cuenta dos veces o se pierde del todo. Defina la precedencia de marcas de tiempo de forma explícita: el event_time de Wialon manda, el ingestion_time es metadato. Construya el sync hacia el ERP de modo que pueda reabrir o corregir períodos anteriores cuando lleguen eventos tardíos, en lugar de descartarlos en silencio.

• Arme una planilla compartida que mapee cada campo a su sistema propietario, su frecuencia de actualización y su regla de resolución de conflictos.
• Establezca una política de «gana el último que escribe, con traza de auditoría» para los campos que de verdad necesitan actualización bidireccional.
• Defina un período de gracia para eventos tardíos — típicamente de 4 a 6 horas — pasado el cual la conciliación es manual.
• Corra consultas semanales de detección de divergencia que comparen los campos clave entre sistemas y marquen las diferencias para revisión.

Diseñe la capa de contrato de datos

Los payloads JSON débilmente tipados que van de la extracción de Wialon a la ingesta del ERP son una bomba de tiempo. La primera versión funciona bien porque quien escribió el productor escribió también el consumidor. Seis meses después alguien agrega un campo, cambia una unidad de medida de litros a galones, o renombra «driver_id» a «operator_id». El consumidor se rompe a las 2 de la mañana y nadie sabe por qué hasta que el turno de la mañana nota que faltan datos.

Un contrato de datos es una definición de esquema versionada que productor y consumidor aceptan. Especifica nombres de campos, tipos, unidades, si admite nulos y qué rangos de valores son válidos. Para un evento de viaje terminado, el contrato podría definir trip_id como string obligatorio, distance_km como float obligatorio con dos decimales, y driver_code como string opcional que debe respetar un formato definido. Cualquier payload que viole el contrato se rechaza en la ingesta, no se absorbe en silencio.

Versione el contrato de forma explícita. La versión 1.0 tiene la distancia en kilómetros; la 1.1 agrega fuel_consumed_liters como campo opcional; la 2.0 convierte driver_code de opcional en obligatorio. Cada consumidor declara qué versión del contrato soporta. Cuando sale un cambio que rompe, corra las dos versiones en paralelo durante una ventana de migración. Eso evita las fallas en cascada que aquejan a las integraciones donde «solo agregamos un campo y se rompió todo».

Reintentos y conciliación como funciones de primera clase

Las integraciones en producción fallan seguido. Timeouts de red, expiración del token de sesión de Wialon a mitad de un lote, bloqueos en la base del ERP durante el cierre de mes, registros malformados de un rastreador recién dado de alta: son condiciones normales de operación, no casos raros. Si su pipeline trata cualquier falla como fatal y se detiene, va a tener huecos de datos en la primera semana.

Toda operación de escritura tiene que ser idempotente. Use una clave de deduplicación derivada del evento de negocio — por ejemplo, la combinación de unit_id, tipo de evento y marca de tiempo truncada al segundo. Cuando un reintento entrega el mismo evento dos veces, el consumidor hace upsert en vez de insert. La cláusula ON CONFLICT de PostgreSQL lo resuelve directo. Sin idempotencia, los reintentos crean registros duplicados que inflan conteos de viajes, totales de combustible y todos los informes que vienen después.

Los reintentos necesitan estructura: backoff exponencial con jitter, arrancando en 1 segundo, doblando a 2, 4, 8, y con techo en 60 segundos. El jitter — un desplazamiento aleatorio de hasta el 30% de la demora — evita la estampida cuando varios workers reintentan a la vez después de una caída compartida. Pasado un número configurable de reintentos (normalmente 5), mande el registro fallido a una cola de mensajes muertos para inspección manual, en lugar de reintentar para siempre.

La conciliación nocturna es la red que atrapa todo lo que los reintentos no atraparon. Corra una consulta que cruce el log de extracción contra la tabla destino del ERP por la clave de deduplicación. Todo registro presente en el log y ausente en el ERP es un hueco. Todo registro presente en los dos pero con valores distintos es una divergencia. Publique ese informe en un canal compartido cada mañana. Si la cantidad de huecos supera su umbral — nosotros usamos el 0,1% del volumen diario — dispare una alerta antes de que el equipo de operaciones empiece su turno.

Maneje el ciclo de vida de la autenticación

La Remote API de Wialon usa tokens de sesión (el parámetro «sid») obtenidos por el endpoint token/login. Cada sesión tiene un timeout de inactividad — típicamente 5 minutos en Wialon Hosting, configurable en Wialon Local. Si su pipeline tarda más que eso en procesar un lote sin hacer ninguna llamada, la sesión expira en silencio. La siguiente petición devuelve el código de error 1 (sesión inválida) y, si su código no lo trata de forma específica, registra un genérico «falló la petición» y sigue adelante, dejando un hueco en los datos.

El error de autenticación más común es dejar fijo un único token de larga vida compartido por todos los workers. Cuando ese token se revoca — porque un administrador lo regenera, o porque se alcanzó el límite de tokens por usuario de Wialon — todos los workers fallan al mismo tiempo. En su lugar, implemente un pool de tokens: cada worker obtiene su propia sesión vía token/login usando un token de API compartido, administra el ciclo de vida de esa sesión y la refresca antes del timeout de inactividad. Un heartbeat de fondo (llamando avl_evts cada 60 segundos) mantiene viva la sesión durante las pausas largas de procesamiento.

En despliegues multi-inquilino, donde usted se integra con varias cuentas de Wialon, aísle las credenciales por inquilino en un gestor de secretos. Nunca guarde tokens de la API de Wialon en variables de entorno ni en archivos de configuración versionados. Rote los tokens de forma trimestral y ante cualquier incidente de seguridad. Registre cada evento de autenticación — login, refresco, expiración, falla — en una tabla de auditoría dedicada, para poder diagnosticar «¿por qué se detuvo el sync a las 3 de la mañana?» sin adivinar.

Planifique la evolución del esquema

Los dos lados de la integración van a cambiar su esquema con el tiempo. Wialon agrega propiedades de unidad, cambia nombres de columnas de informes entre versiones o deja obsoletos campos de mensajes. El equipo del ERP agrega columnas, cambia relaciones de clave foránea o migra a un módulo nuevo. Si su integración es un mapeo punto a punto rígido, cada cambio de cualquiera de los dos lados obliga a un despliegue sincronizado — y los despliegues sincronizados entre equipos que liberan con calendarios distintos son una ficción.

Construya capas de transformación versionadas entre la extracción cruda de Wialon y el payload listo para el ERP. Cada versión de transformación es una función pura: dada la versión de esquema de entrada X, produce la versión de salida Y. Cuando Wialon cambia su salida, usted agrega un adaptador de entrada nuevo sin tocar el anterior. Cuando el ERP cambia lo que exige de entrada, usted agrega un adaptador de salida. El registro de transformaciones mapea cada par de versiones a la función correcta. Las versiones viejas quedan disponibles para reproceso y depuración.

Use feature flags para desplegar cambios de esquema de a poco. Lleve la transformación nueva a producción pero actívela solo para un subconjunto de vehículos o para una sola unidad de negocio. Compare las salidas vieja y nueva durante 48 horas. Si la nueva produce resultados idénticos en los campos compartidos y llena bien los campos nuevos, promuévala al 100%. Si diverge, usted cazó un bug antes de que afectara a toda la flota. Así desaparece la ansiedad de la «migración de golpe» que hace que los equipos posterguen meses una actualización necesaria.

Lista de verificación operativa

Una integración que anda en desarrollo pero no tiene andamiaje operativo va a fallar en producción dentro del primer mes. Antes de salir en vivo, arme un tablero de monitoreo que muestre cuatro cosas de un vistazo: el retraso del sync (tiempo entre el evento en Wialon y la llegada del registro al ERP), la tasa de error por categoría (autenticación, validación, transformación, red), el caudal de registros (eventos por minuto, con su tendencia en 24 horas) y la cantidad de huecos de conciliación (actualizada cada noche).

Defina reglas de alerta con umbrales que digan algo. Retraso de sync por encima de 15 minutos: advertencia; por encima de 60 minutos: llamada crítica. Tasa de error por encima del 1% del volumen horario: investigación. Huecos de conciliación por encima del 0,1%: revisión antes del turno. Evite la fatiga de alertas ajustando umbrales durante las dos primeras semanas de producción — empiece conservador y apriete a medida que conozca la línea base.

Escriba runbooks para los tres modos de falla más comunes: expiración de sesión de Wialon (revisar el estado del token, forzar re-autenticación, verificar el backfill), bloqueo en la base del ERP (identificar la consulta bloqueante, esperar o escalar al DBA, reanudar el sync) y desajuste de esquema (identificar el campo que cambió, desplegar la transformación actualizada, reprocesar el lote fallido). Cada runbook tiene que poder ejecutarlo un ingeniero de guardia que no construyó la integración. Si hace falta el desarrollador original para arreglarlo, no es un runbook: es conocimiento tribal, y va a fallar justo cuando esa persona esté de vacaciones.

• Asigne la guardia del pipeline de integración de forma explícita — no debería caer por defecto en el equipo de plataforma sin que nadie lo haya acordado.
• Haga un simulacro antes de salir en vivo: provoque expiración de token, partición de red y cambio de esquema para verificar que alertas, reintentos y runbooks funcionan.
• Mantenga un registro de incidentes con causa raíz, resolución y acción preventiva para cada caída de más de 30 minutos.

Los errores de arriba son sobre todo acuerdos, no código: qué significa cada campo, quién es su dueño y cada cuánto se mueve. Eso lo trabajamos como primera fase de un proyecto — vea servicios de integración de Wialon.