Cómo construimos una integración documental resiliente entre un ERP legacy y una contraparte externa

Resumen ejecutivo #

En este proyecto diseñamos e implementamos una plataforma de integración para automatizar el intercambio de documentos comerciales y operativos entre una organización con ERP legacy y una contraparte externa.

El objetivo era reemplazar procesos manuales y frágiles por una integración trazable, auditable y resiliente que pudiera operar documentos críticos del ciclo comercial:

• recepción de órdenes de compra;
• generación de confirmaciones de orden;
• publicación de notificaciones operativas;
• publicación periódica de inventario;
• manejo de errores, reintentos y evidencia operativa;
• integración controlada con un ERP legacy.

El resultado fue una arquitectura basada en mensajes, colas transaccionales, transformaciones estructuradas, workers desacoplados, validaciones de layout, control de duplicados, reintentos, auditoría punta a punta y herramientas de diagnóstico para pruebas, QA y soporte.

Más que una integración puntual, el proyecto terminó convirtiéndose en una base reutilizable para operar documentos B2B de forma ordenada, observable y escalable.

---

Contexto del problema #

El cliente necesitaba conectarse con una contraparte comercial que intercambiaba documentos estructurados. Estos documentos seguían layouts específicos, con campos obligatorios, catálogos, jerarquías, reglas condicionales y estados de negocio.

El problema no era simplemente generar o consumir archivos. El reto real era resolver el ciclo completo de integración:

1. detectar documentos nuevos;
2. descargar el XML correcto;
3. validar estructura y tipo documental;
4. transformar el XML a un modelo canónico interno;
5. persistir información en staging;
6. relacionar documentos con entidades del ERP;
7. generar respuestas EDI;
8. publicar documentos a la contraparte;
9. controlar duplicados;
10. manejar errores temporales y permanentes;
11. dejar evidencia auditable;
12. permitir soporte operativo sin depender de inspecciones manuales desordenadas.

Además, existían restricciones prácticas típicas de una integración B2B real:

• autenticación con token de vida limitada;
• separación entre ambientes de prueba y producción;
• rutas o canales distintos por ambiente;
• tamaño máximo de archivo;
• reglas de publicación por tipo de documento;
• necesidad de trazabilidad por orden;
• ventanas de procesamiento;
• reintentos controlados;
• evidencia para QA y troubleshooting;
• compatibilidad con un ERP legacy con datos distribuidos entre estructuras operativas e históricas.

---

Documentos EDI implementados #

El primer paso fue convertir los layouts del partner en contratos técnicos implementables. Cada documento tenía una función distinta dentro del ciclo operativo.

1. Orden de Compra #

La Orden de Compra es el documento que inicia el flujo. El partner la genera y la empresa la consume.

Una OC puede incluir, entre otros datos:

• número de orden;
• fecha de orden;
• fecha solicitada de entrega;
• estatus de orden;
• número de revisión;
• datos de facturación;
• datos de entrega;
• proveedor;
• comprador;
• líneas de artículos;
• cantidades solicitadas;
• unidades de medida;
• precios;
• importes;
• totales;
• referencias adicionales.

Uno de los puntos importantes fue respetar reglas condicionales. Por ejemplo, cuando una orden llega como modificación o cancelación, la revisión se vuelve obligatoria para mantener control del cambio entre el partner, la plataforma EDI y el ERP.

La OC también funcionó como eje de correlación para documentos posteriores, como la Confirmación de Orden y el Aviso de Embarque.

2. Confirmación de Orden #

La Confirmación de Orden es la respuesta de la empresa al partner.

Este documento indica si la orden fue:

• aceptada completamente;
• aceptada parcialmente;
• aceptada con cambios;
• rechazada;
• cancelada;
• actualizada;
• confirmada con backorder;
• confirmada con fechas alternativas.

También permite responder por línea de artículo, incluyendo:

• SKU o código de artículo;
• cantidad confirmada;
• cantidad no surtida;
• fecha prometida;
• estatus por línea;
• comentarios o referencias;
• unidad de medida;
• precio o condiciones cuando aplican.

La Confirmación de Orden fue clave porque conecta la recepción comercial de la orden con la promesa operativa de cumplimiento.

En la primera fase se priorizó el escenario de confirmación aceptada, dejando la arquitectura lista para extenderse a casos más avanzados: aceptaciones parciales, rechazos, cancelaciones y backorders.

3. Aviso de Embarque #

El Aviso de Embarque comunica que una orden ya fue preparada, liberada o enviada.

Este documento incluye datos logísticos como:

• identificador de embarque;
• orden relacionada;
• fecha de envío;
• fecha estimada de entrega;
• carrier o transportista;
• origen;
• destino;
• referencias de transporte;
• artículos embarcados;
• cantidades enviadas;
• unidad de medida;
• empaque;
• referencias adicionales.

La estructura implementada fue jerárquica:

Embarque
└── Orden
    └── Artículos

Esta jerarquía permitió mantener trazabilidad clara entre lo que el partner solicitó, lo que la empresa confirmó y lo que finalmente se embarcó.

El ASN fue uno de los documentos con mayor sensibilidad porque mezcla información comercial, inventario y logística. Un error en cantidades, fechas o referencias puede generar problemas en recepción física, conciliación y facturación.

4. Inventario #

También se contempló la publicación periódica de inventario.

A diferencia de la Confirmación de Orden o el Aviso de Embarque, el inventario puede funcionar de forma batch, por ejemplo diaria u horaria, dependiendo de la sensibilidad operativa.

El documento de inventario debía publicar una fotografía de existencias por:

• SKU;
• unidad de medida;
• almacén o sitio;
• cantidad disponible;
• cantidad asignada;
• cantidad comprometida;
• cantidad relevante para planeación;
• fecha de corte.

El inventario no sólo sirve como dato operativo; también ayuda a reducir órdenes inviables, mejorar planeación y anticipar faltantes.

---

Principios de diseño #

Desde el inicio se definieron principios técnicos para evitar construir una integración frágil basada en scripts aislados.

Idempotencia #

Cada mensaje debía tener una clave de correlación que evitara duplicados.

Esto era crítico porque una orden puede reaparecer en el monitor, un worker puede reintentar, un operador puede reprocesar manualmente una transacción, o una respuesta puede llegar tarde.

La misma orden no debía generar múltiples confirmaciones o múltiples avisos de embarque por accidente.

Para lograrlo, cada documento outbound se generó con una correlación estable basada en información de negocio como:

• tipo de documento;
• orden relacionada;
• revisión;
• evento de negocio;
• ambiente;
• entidad emisora/receptora.

Trazabilidad #

Cada documento debía conservar metadata suficiente para reconstruir su historia.

La trazabilidad incluyó:

• número de documento;
• tipo de documento;
• dirección del mensaje;
• emisor;
• receptor;
• ambiente;
• propósito de transacción;
• orden relacionada;
• estatus operativo;
• timestamps;
• intentos;
• último error;
• XML original;
• payload canónico;
• XML final;
• respuesta del partner.

Esto permitió contestar preguntas operativas como:

• ¿la orden fue detectada?;
• ¿se descargó el XML correcto?;
• ¿pasó validación?;
• ¿se insertó en staging?;
• ¿se generó confirmación?;
• ¿se publicó?;
• ¿qué respuesta devolvió el partner?;
• ¿por qué falló?;
• ¿se puede reprocesar sin duplicar?

Separación de responsabilidades #

La integración se dividió en workers especializados.

En lugar de tener un solo proceso monolítico que hiciera todo, se separaron responsabilidades como:

• consultar monitor de órdenes;
• descargar XML;
• procesar mensajes inbound;
• extraer eventos desde staging/ERP;
• publicar mensajes outbound;
• aplicar reglas de horario o cutoff;
• enviar notificaciones;
• generar evidencia;
• validar estado operativo.

Esta separación redujo acoplamiento, hizo más sencillo probar cada componente y facilitó el troubleshooting.

Validación antes de publicar #

Antes de enviar cualquier documento al partner, el sistema debía validar:

• estructura XML;
• tipo documental;
• campos obligatorios;
• tamaño máximo;
• presencia de líneas;
• formato de fechas;
• códigos de entidad;
• rutas configuradas;
• payload canónico;
• duplicidad;
• consistencia mínima de negocio.

El objetivo era evitar publicar basura o documentos incompletos que luego fueran difíciles de rastrear.

Operación observable #

Una integración que “corre” no necesariamente está lista para operar.

La plataforma debía permitir ver qué estaba pasando sin depender de abrir código o revisar archivos sueltos.

Para eso se agregaron:

• logs por worker;
• estados por mensaje;
• errores detallados;
• dumps controlados;
• watermarks;
• dashboards operativos;
• scripts de reconciliación;
• preflight de configuración;
• healthchecks;
• exportación de evidencia;
• reportes por orden.

---

Arquitectura general #

La solución quedó organizada como una plataforma EDI modular con cuatro capas principales.

Partner B2B
   │
   │  XML / API / Monitor
   ▼
Capa de entrada
   │
   │  Validación, descarga, sanitización
   ▼
Staging EDI / ERP boundary
   │
   │  Normalización y persistencia
   ▼
Cola EDI transaccional
   │
   │  Estados, reintentos, leases, correlación
   ▼
Capa de publicación
   │
   │  Transformación, autenticación, envío
   ▼
Partner B2B

Capa de entrada #

Esta capa detecta y recibe documentos entrantes.

Para las órdenes de compra, se implementó un flujo de consulta al monitor del partner, resolución del documento correcto y descarga del XML asociado.

Durante las pruebas se descubrió que no todos los identificadores visibles en el monitor servían para descargar el XML final. Por eso se ajustó el flujo para apoyarse en el identificador consistente expuesto por el canal de transacciones.

También se agregó filtrado explícito por tipo documental para evitar procesar como orden algo que no fuera realmente una OC.

Responsabilidades de esta capa:

• consultar monitor;
• aplicar watermark;
• filtrar por emisor/receptor/tipo;
• resolver transacción;
• descargar XML;
• sanitizar XML;
• validar cabecera;
• encolar mensaje inbound;
• registrar evidencia.

Capa de staging #

El staging actúa como frontera entre el mundo EDI y el ERP.

Su función es normalizar la información entrante y dejarla disponible para procesos internos sin acoplar directamente el layout del partner a las tablas del ERP.

En staging se conservaron:

• encabezados de orden;
• líneas de artículo;
• fechas;
• importes;
• códigos de proveedor;
• códigos de comprador;
• cantidades;
• unidades de medida;
• XML crudo;
• datos normalizados;
• estado de procesamiento.

Esta capa fue especialmente útil porque el ERP legacy tenía diferencias entre tablas activas e históricas, además de relaciones no siempre obvias entre compra, recepción, venta, inventario y facturación.

Cola EDI transaccional #

La cola se implementó sobre base de datos.

Cada mensaje contiene información como:

• dirección: inbound u outbound;
• tipo de documento;
• payload;
• estatus;
• número de intentos;
• máximo de intentos;
• último error;
• timestamp de creación;
• timestamp de actualización;
• not_before_ts para reintentos diferidos;
• correlación idempotente;
• ambiente;
• ruta de publicación.

Los estados principales fueron:

NEW    → mensaje nuevo listo para procesarse
RETRY  → mensaje reprogramado después de error temporal
SENT   → documento outbound enviado exitosamente
ACK    → documento inbound procesado exitosamente
ERR    → error permanente o agotamiento de reintentos

La cola se operó mediante procedimientos almacenados para:

• encolar mensajes;
• tomar mensajes con lease;
• completar con éxito;
• marcar error;
• reprogramar con backoff;
• evitar que múltiples workers procesen el mismo mensaje al mismo tiempo.

Capa de publicación #

La publicación hacia el partner se encapsuló en un worker outbound.

Este worker:

1. toma mensajes listos de la cola;
2. resuelve la ruta configurada;
3. obtiene credenciales o token;
4. transforma payload canónico a XML final;
5. valida campos y tamaño;
6. envía el documento;
7. registra respuesta;
8. marca éxito o error;
9. reintenta cuando corresponde;
10. guarda evidencia si está configurado.

Esto permitió que la lógica de negocio no quedara mezclada con detalles de transporte, autenticación o manejo de errores HTTP.

---

Flujo completo de Orden de Compra #

El flujo inbound de una OC quedó así:

Monitor del partner
   ▼
Worker de monitoreo
   ▼
Filtro por tipo documental y watermark
   ▼
Resolución de transacción real
   ▼
Descarga de XML
   ▼
Sanitización y validación
   ▼
Staging de OC
   ▼
ACK inbound
   ▼
Evento para Confirmación de Orden

Paso a paso #

1. El monitor del partner expone metadata de nuevas órdenes.
2. Un worker consulta el monitor periódicamente.
3. El sistema compara fechas y marcas contra un watermark.
4. Se filtra por emisor, receptor y tipo documental.
5. Se resuelve el documento real usando el canal de transacciones.
6. Se descarga el XML de la orden.
7. Se limpia el XML si contiene caracteres problemáticos, prefijos inconsistentes, espacios indebidos o prolog inválido.
8. Se valida que el documento sea realmente una OC.
9. Se verifica que exista la cabecera esperada.
10. Se insertan o actualizan encabezado y líneas en staging.
11. Se registra el XML original para auditoría.
12. El mensaje inbound se marca como procesado.
13. Si la orden está lista, se genera un evento para Confirmación de Orden.

Problema importante descubierto #

Durante la integración se descubrió que el dato visible en el monitor no siempre era suficiente para descargar el XML correcto.

Esto obligó a separar conceptualmente:

• metadata visible en monitor;
• transacción real;
• archivo XML descargable;
• documento de negocio procesable.

Esta separación evitó errores donde el sistema podía intentar descargar documentos usando IDs incorrectos o procesar documentos de otro tipo como si fueran órdenes.

---

Flujo completo de Confirmación de Orden #

La Confirmación de Orden se genera después de que la OC está aceptada o lista para responder al partner.

OC en staging / ERP
   ▼
Extractor de eventos
   ▼
Payload canónico
   ▼
Mensaje outbound
   ▼
Transformación XML
   ▼
Publicación al partner
   ▼
SENT / RETRY / ERR

Paso a paso #

1. El extractor detecta órdenes con estatus interno listo para confirmación.
2. Construye un payload canónico con datos de cabecera, proveedor, fechas y líneas.
3. Calcula el estatus de confirmación.
4. Genera la estructura de Confirmación de Orden.
5. Asigna una clave de correlación idempotente.
6. Encola el mensaje outbound.
7. El publicador toma el mensaje.
8. Transforma el canónico a XML final.
9. Valida campos obligatorios, estructura y tamaño.
10. Envía el XML al partner.
11. Marca el mensaje como SENT si la respuesta es exitosa.
12. Reintenta si el error es temporal.
13. Marca ERR si el error es permanente.
14. Guarda evidencia de payload, XML y respuesta.

Casos contemplados #

La arquitectura quedó preparada para manejar distintos resultados de confirmación:

• aceptación completa;
• aceptación parcial;
• cambios de fecha;
• cambios de cantidad;
• rechazo por artículo;
• rechazo total;
• backorder;
• cancelación;
• actualización posterior.

---

Flujo completo de Aviso de Embarque #

El ASN se dispara cuando la orden está en condición de embarque.

Evento logístico / estado ERP
   ▼
Extractor ASN
   ▼
Canónico de embarque
   ▼
Mensaje outbound
   ▼
XML ASN
   ▼
Publicación al partner
   ▼
SENT / RETRY / ERR

Paso a paso #

1. El ERP o staging marca la orden como lista para ASN.
2. El extractor detecta el estatus correspondiente.
3. Se obtienen datos de orden, artículos, cantidades y referencias logísticas.
4. Si staging no tiene toda la información, el sistema puede apoyarse en historial del ERP.
5. Se construye la estructura jerárquica embarque → orden → artículo.
6. Se agregan fechas de envío y entrega estimada.
7. Se incluyen carrier, origen, destino y referencias.
8. Se asigna correlación idempotente.
9. Se encola el documento.
10. El publicador genera XML final.
11. Se valida estructura y datos mínimos.
12. Se envía al partner.
13. Se guarda evidencia de XML, canónico, respuesta y estado.

Consideraciones especiales #

El ASN requirió especial cuidado porque depende de datos de varias áreas:

• ventas;
• compras;
• inventario;
• logística;
• transporte;
• almacén;
• recepción del partner.

Una cantidad mal enviada o una fecha equivocada puede afectar procesos posteriores como recepción, conciliación o facturación.

---

Flujo de inventario #

El flujo de inventario se diseñó como publicación batch o programada.

ERP / Inventario
   ▼
Extractor de existencias
   ▼
Normalización por SKU / almacén
   ▼
Canónico de inventario
   ▼
XML outbound
   ▼
Publicación al partner

Datos considerados #

• SKU;
• descripción;
• unidad de medida;
• almacén;
• sitio;
• cantidad disponible;
• cantidad asignada;
• cantidad comprometida;
• cantidad en tránsito cuando aplica;
• fecha y hora de corte.

Modalidad de publicación #

El inventario podía correr:

• diario;
• varias veces al día;
• por ventana horaria;
• bajo demanda;
• por cambios relevantes.

La decisión depende del costo de operación y de qué tan sensible sea el negocio a cambios de disponibilidad.

---

Integración con ERP legacy #

Una parte importante del proyecto fue entender cómo mapear los documentos EDI contra el ERP.

El ERP no exponía necesariamente un modelo simple y moderno. Había que considerar tablas de trabajo, tablas históricas, relaciones indirectas y procesos que cambian de estado a medida que los documentos avanzan.

Áreas analizadas #

Se revisaron tablas y relaciones relacionadas con:

• compras;
• ventas;
• recepciones;
• inventario;
• unidades de medida;
• proveedores;
• clientes;
• cuentas por pagar;
• documentos históricos;
• vínculos entre documentos;
• cantidades recibidas;
• cantidades facturadas;
• existencias por almacén.

Work vs History #

Uno de los puntos importantes fue distinguir entre documentos activos e históricos.

En muchos ERP legacy, un documento cambia de tabla o de estado cuando pasa por ciertos hitos operativos. Por ejemplo:

• una orden abierta puede vivir en tablas de trabajo;
• una recepción completada puede moverse a histórico;
• una factura puede tener relación indirecta con la recepción;
• una cantidad puede existir en varios lugares dependiendo del estado.

Por eso se prepararon consultas SQL de validación para revisar:

• existencia de columnas esperadas;
• conteos por tabla;
• documentos recientes;
• relación entre orden y recepción;
• relación entre recepción y factura;
• relación entre artículos y unidades de medida;
• relación entre inventario y almacén;
• consistencia entre staging y ERP.

Toolkit SQL #

Se construyó un toolkit SQL para inspección y soporte.

El toolkit permitió:

• listar tablas relevantes por módulo;
• validar columnas esperadas;
• revisar top-N documentos recientes;
• comparar work vs history;
• identificar relaciones entre documentos;
• validar cantidades;
• diagnosticar diferencias entre ERP y staging;
• apoyar reconciliaciones por orden.

Este toolkit fue importante porque, en una integración ERP, conocer el layout EDI no basta. Hay que saber cuál es la fuente de verdad para cada campo.

---

Modelo de mensajes y estados #

La cola EDI fue el centro operativo de la solución.

Cada mensaje representa una unidad de trabajo auditable.

Campos conceptuales #

Un mensaje puede incluir:

message_id
business_key
correlation_id
direction
document_type
environment
sender
receiver
payload
status
attempt_count
max_attempts
not_before_ts
created_ts
updated_ts
last_error_code
last_error_msg
published_ts
ack_ts

Estados #

NEW

Mensaje creado y listo para procesarse.

RETRY

Mensaje que falló por causa temporal y fue reprogramado.

SENT

Documento outbound enviado exitosamente.

ACK

Documento inbound recibido y procesado exitosamente.

ERR

Mensaje con error permanente o que agotó reintentos.

Lease de procesamiento #

Para evitar que dos workers tomaran el mismo mensaje al mismo tiempo, se usó un patrón de lease.

El worker toma temporalmente un mensaje, lo procesa y luego lo completa. Si el worker muere o no termina, el lease puede expirar y permitir reprocesamiento controlado.

---

Workers implementados #

La plataforma se dividió en workers especializados.

Worker de monitoreo de órdenes #

Responsable de consultar el monitor del partner, identificar nuevas órdenes y aplicar filtros iniciales.

Funciones principales:

• consultar monitor;
• aplicar watermark;
• filtrar por tipo documental;
• detectar candidatos;
• registrar metadata;
• evitar reprocesamiento.

Worker de descarga de órdenes #

Responsable de resolver la transacción real y descargar el XML.

Funciones principales:

• resolver ID de transacción;
• descargar archivo;
• validar respuesta;
• guardar XML crudo;
• encolar inbound.

Worker inbound #

Responsable de procesar documentos entrantes.

Funciones principales:

• sanitizar XML;
• parsear estructura;
• validar tipo documental;
• extraer encabezado y líneas;
• insertar o actualizar staging;
• marcar ACK;
• registrar errores.

Worker extractor #

Responsable de detectar eventos internos que deben generar documentos outbound.

Funciones principales:

• detectar órdenes listas para confirmación;
• detectar órdenes listas para ASN;
• extraer inventario;
• construir payload canónico;
• encolar mensajes outbound.

Worker outbound #

Responsable de publicar documentos al partner.

Funciones principales:

• tomar mensajes outbound;
• transformar canónico a XML;
• validar estructura;
• resolver autenticación;
• enviar documento;
• manejar respuesta;
• marcar SENT, RETRY o ERR;
• guardar evidencia.

Worker de reglas o cutoff #

Responsable de aplicar ventanas operativas.

Funciones principales:

• respetar horarios de procesamiento;
• diferir mensajes fuera de ventana;
• evitar publicaciones en horarios no permitidos;
• soportar operación batch.

Worker de notificaciones #

Responsable de alertar sobre errores o estados relevantes.

Funciones principales:

• detectar mensajes en error;
• generar resúmenes;
• notificar eventos críticos;
• apoyar monitoreo operativo.

---

Transformaciones XML #

La plataforma manejó dos tipos de representación:

1. XML del partner.
2. Payload canónico interno.

El payload canónico permitió desacoplar reglas de negocio de detalles específicos del layout XML.

Ventajas del canónico #

• facilita pruebas unitarias;
• reduce dependencia del layout externo;
• permite reutilizar lógica;
• simplifica validaciones;
• permite generar evidencia intermedia;
• facilita debugging;
• prepara la plataforma para nuevos partners o versiones de layout.

Sanitización XML #

Se centralizó la limpieza de XML para manejar casos como:

• caracteres invisibles;
• prolog inconsistente;
• espacios antes de la declaración XML;
• prefijos inesperados;
• encoding incorrecto;
• caracteres no válidos;
• contenido vacío;
• namespaces problemáticos.

Centralizar esta lógica evitó que cada worker tuviera su propia forma de limpiar XML.

---

Manejo de errores #

El manejo de errores se diseñó pensando en operación real.

No todos los errores deben tratarse igual.

Errores temporales #

Ejemplos:

• timeout;
• error 503;
• error 502;
• rate limit;
• problema temporal de red;
• token expirado con posibilidad de renovación;
• dependencia momentáneamente no disponible.

Comportamiento esperado:

• registrar error;
• incrementar intento;
• calcular backoff;
• mover a RETRY;
• reintentar después de not_before_ts.

Errores permanentes #

Ejemplos:

• XML inválido;
• campos obligatorios faltantes;
• ruta no configurada;
• tipo documental desconocido;
• payload vacío;
• orden sin líneas;
• error de transformación;
• credenciales mal configuradas;
• documento no publicable.

Comportamiento esperado:

• marcar ERR;
• guardar mensaje de error claro;
• conservar evidencia;
• evitar reintentos inútiles;
• permitir diagnóstico por soporte.

Errores de autenticación #

Los errores de autenticación se trataron con cuidado especial.

Un token expirado puede resolverse renovando credenciales, pero una credencial inválida o una URL incorrecta no debería disparar reintentos indefinidos.

Por eso se agregaron preflights para validar configuración antes de correr flujos completos.

---

Backoff y reintentos #

Los reintentos se manejaron con una combinación de:

• contador de intentos;
• máximo de intentos;
• not_before_ts;
• clasificación de error;
• actualización de estado;
• registro del último error.

El objetivo era evitar dos problemas comunes:

1. perder mensajes por errores temporales;
2. saturar el sistema o al partner con reintentos agresivos.

Un error temporal se reprograma. Un error permanente se detiene y se documenta.

---

Hardening técnico #

Después de los primeros ciclos de integración se ejecutó una fase de blindaje.

Hallazgos relevantes #

Durante las pruebas aparecieron hallazgos típicos de integraciones reales:

• el endpoint de archivos requería formato multipart;
• el endpoint correcto de login debía configurarse por ambiente;
• el monitor podía devolver documentos que no eran órdenes de compra;
• algunos identificadores visibles no servían para descargar el XML correcto;
• existía drift entre scripts SQL y código Python;
• algunos mensajes sin detalle podían romper workers si no se manejaban defensivamente;
• rutas legacy competían con el flujo oficial;
• era necesario validar configuración antes de ejecutar corridas completas.

Mejoras aplicadas #

El hardening incluyó:

• sanitización XML centralizada;
• filtro explícito por tipo documental;
• validación de cabecera esperada;
• desactivación por defecto de rutas legacy;
• preflight de configuración;
• reconciliación por orden;
• healthcheck de workers;
• dashboard de cola;
• exportación de evidencia;
• corrida multiorden con run id;
• control de dumps;
• validación de tamaño;
• manejo defensivo de payloads vacíos;
• clasificación de errores.

---

Herramientas operativas construidas #

Además del código principal, se preparó un conjunto de herramientas para QA, soporte y auditoría.

Preflight de configuración #

Valida que la configuración esté completa antes de ejecutar flujos.

Revisa, por ejemplo:

• ambiente;
• URLs requeridas;
• credenciales;
• rutas de publicación;
• límites de tamaño;
• variables de entorno;
• conectividad básica;
• presencia de tablas o procedimientos esperados.

Reconciliación por orden #

Permite revisar el estado completo de una orden:

• si fue detectada;
• si se descargó;
• si entró a staging;
• si generó confirmación;
• si generó ASN;
• si ambos documentos fueron enviados;
• si hubo errores;
• qué evidencia existe.

Trazabilidad por PO #

Permite seguir una orden de punta a punta, desde el monitor hasta el estado final de mensajes outbound.

Healthcheck de workers #

Permite validar si los workers están activos, si pueden conectarse a dependencias y si tienen configuración mínima válida.

Dashboard de cola #

Permite observar:

• mensajes por estado;
• mensajes por tipo documental;
• errores recientes;
• mensajes atorados;
• próximos reintentos;
• edad de mensajes;
• volumen procesado.

Exportación de evidencia #

Cada corrida podía generar una carpeta de evidencia con:

• stdout;
• logs;
• XML inbound;
• XML outbound;
• payload canónico;
• respuesta del partner;
• snapshot de cola;
• resumen de corrida;
• errores clasificados.

Esto fue clave para QA porque permitió entregar evidencia reproducible y no depender de capturas dispersas.

---

Pruebas realizadas #

La validación combinó varias capas.

Pruebas unitarias #

Se probaron componentes aislados:

• sanitización XML;
• parseo;
• generación de payload canónico;
• transformación a XML;
• validaciones de campos;
• clasificación de errores;
• cálculo de correlación;
• helpers de fecha;
• lógica de reintento.

Pruebas de transformación #

Se validó que los documentos generados respetaran la estructura esperada:

• Confirmación de Orden;
• Aviso de Embarque;
• Inventario;
• cabeceras;
• líneas;
• jerarquías;
• campos obligatorios.

Pruebas de cola #

Se validaron operaciones como:

• encolar;
• tomar con lease;
• completar exitosamente;
• marcar error;
• reintentar;
• evitar duplicados;
• respetar not_before_ts.

Smoke tests #

Se prepararon pruebas rápidas para validar que el ambiente estuviera en condiciones mínimas:

• conexión a base de datos;
• variables de entorno;
• endpoints configurados;
• workers inicializables;
• rutas de publicación;
• tablas necesarias.

Pruebas end-to-end #

Se realizaron corridas funcionales de punta a punta con órdenes de prueba.

El flujo validado incluyó:

1. detección de órdenes;
2. descarga de XML;
3. inserción en staging;
4. generación de Confirmación de Orden;
5. publicación de Confirmación de Orden;
6. generación de ASN;
7. publicación de ASN;
8. descarga o validación de evidencia;
9. revisión de estados finales.

En una corrida multiorden se validó que varias órdenes pudieran procesarse y que sus documentos relacionados quedaran enviados exitosamente.

---

Estrategia de despliegue QA #

Se documentó una ruta de despliegue para ambiente QA sobre una VM Linux.

Componentes propuestos #

• API operativa interna;
• workers ejecutados como servicios controlados;
• reverse proxy;
• archivos de configuración por ambiente;
• logs por servicio;
• directorios controlados para dumps y evidencia;
• endpoints de monitoreo;
• endpoints operativos protegidos;
• scripts de verificación.

Servicios contemplados #

• API;
• worker inbound;
• worker outbound;
• worker extractor;
• worker de reglas/cutoff;
• worker notifier;
• worker de monitoreo OC;
• worker de descarga de archivos cuando aplica.

Separación de ambientes #

Se documentó explícitamente que QA debía operar contra ambiente de prueba del partner, aunque la máquina o el despliegue se llamara QA.

Esto evitó confusión entre:

• nombre interno del ambiente;
• endpoint real usado;
• credenciales;
• partner environment;
• base de datos;
• rutas de publicación.

---

Observabilidad y troubleshooting #

La operación diaria se diseñó para contestar tres preguntas:

1. ¿Qué mensaje falló?
2. ¿Por qué falló?
3. ¿En qué etapa falló?

Fuentes de diagnóstico #

• cola EDI;
• staging de órdenes;
• XML crudo;
• payload canónico;
• XML outbound;
• logs por worker;
• errores en base de datos;
• respuestas del partner;
• watermarks;
• rutas configuradas;
• dumps de evidencia;
• dashboard operativo.

Diagnóstico por orden #

Una orden puede revisarse de forma completa siguiendo:

PO detectada
   ▼
XML descargado
   ▼
Staging actualizado
   ▼
Confirmación generada
   ▼
Confirmación enviada
   ▼
ASN generado
   ▼
ASN enviado

Si algo falla, la investigación se reduce a ubicar en qué punto se interrumpió la cadena.

Modos de evidencia #

Se definieron modos de dumping:

• guardar siempre;
• guardar sólo en error;
• no guardar;
• guardar por corrida;
• guardar por orden.

Para operación normal se recomendó guardar evidencia sólo en error. Para QA o troubleshooting se podía activar evidencia completa.

---

Seguridad y configuración #

Aunque el proyecto se enfocó en integración, se consideraron prácticas básicas de seguridad operativa.

Secretos #

Los secretos no debían estar hardcodeados.

Se manejaron mediante configuración de ambiente o mecanismos equivalentes, incluyendo:

• usuario;
• contraseña;
• tokens;
• endpoints;
• rutas sensibles;
• claves de ambiente.

Tokens #

La autenticación con token obligó a manejar:

• expiración;
• renovación;
• errores 401;
• errores 403;
• separación por ambiente;
• validación previa de credenciales.

Logs #

Los logs debían ser útiles sin exponer información sensible.

Se evitó registrar:

• tokens completos;
• contraseñas;
• headers sensibles;
• secretos;
• datos personales;
• URLs internas no necesarias.

---

Decisiones técnicas relevantes #

Usar cola SQL #

La cola en SQL permitió una implementación pragmática, cercana al ERP y fácil de auditar.

Ventajas:

• transaccionalidad;
• consultas operativas simples;
• facilidad de soporte;
• integración con procedimientos almacenados;
• trazabilidad;
• menor infraestructura adicional.

Trade-off:

• requiere cuidar locks, leases e índices;
• no reemplaza necesariamente a un broker especializado si el volumen crece mucho.

Separar canónico de XML final #

Esta decisión redujo acoplamiento.

El canónico representa el evento de negocio. El XML final representa el contrato específico del partner.

Esto permite cambiar layout sin reescribir toda la lógica de negocio.

Guardar XML crudo #

Guardar XML crudo fue importante para auditoría y debugging.

Cuando hay una diferencia entre lo que el partner dice que envió y lo que el sistema procesó, el XML crudo permite reconstruir la verdad técnica.

Preflight antes de correr #

El preflight evitó perder tiempo con errores previsibles:

• URL faltante;
• credencial incorrecta;
• ruta no configurada;
• tabla inexistente;
• variable de entorno ausente;
• endpoint incorrecto.

---

Lecciones aprendidas #

Una integración EDI no es sólo XML #

La lección principal fue que una integración EDI robusta no se construye únicamente transformando XML.

El verdadero trabajo está en los bordes:

• validación;
• idempotencia;
• reintentos;
• correlación;
• staging;
• auditoría;
• soporte;
• operación;
• troubleshooting;
• despliegue;
• evidencia.

El monitor no siempre es la fuente final #

El monitor del partner puede mostrar metadata útil, pero no siempre contiene todo lo necesario para procesar el documento.

Fue necesario distinguir entre:

• documento listado;
• transacción;
• archivo descargado;
• XML válido;
• documento de negocio.

La operación necesita herramientas propias #

Los scripts de soporte, dashboards, preflights y exportadores de evidencia fueron tan importantes como los workers principales.

Sin estas herramientas, cada error se convierte en una investigación manual.

El ERP es parte del diseño #

No se puede diseñar una integración EDI sin entender bien el ERP.

Hay que saber:

• dónde vive cada dato;
• cuándo cambia de tabla;
• qué documento es fuente de verdad;
• cómo se relacionan orden, recepción, factura e inventario;
• cómo se manejan unidades de medida;
• qué ocurre en escenarios históricos.

La idempotencia no es opcional #

En B2B siempre puede haber reintentos, reprocesos, mensajes duplicados o errores de red.

Sin idempotencia, un reintento legítimo puede convertirse en un duplicado operativo.

---

Resultado del proyecto #

Al cierre de la fase técnica quedó construida una base reutilizable para operar documentos EDI.

El alcance cubrió:

• recepción de Orden de Compra;
• generación de Confirmación de Orden;
• generación de Aviso de Embarque;
• publicación de Inventario;
• integración con ERP legacy;
• cola transaccional;
• workers desacoplados;
• validaciones XML;
• manejo de errores;
• reintentos;
• idempotencia;
• trazabilidad;
• pruebas automatizadas;
• pruebas end-to-end;
• preflights;
• dashboards;
• runbooks;
• evidencia para QA;
• estrategia de despliegue.

La arquitectura quedó preparada para crecer hacia:

• cancelaciones;
• devoluciones;
• catálogos;
• más partners;
• más documentos;
• reglas avanzadas de negocio;
• dashboards SLA;
• alertamiento más completo;
• monitoreo centralizado;
• analítica operativa.

---

Conclusión #

Una integración B2B exitosa no se mide únicamente por enviar o recibir archivos.

Se mide por la capacidad de explicar, reproducir y auditar cada paso del documento: desde que nace una orden, hasta que se confirma, se embarca y se refleja en operación.

En este proyecto, el mayor valor no fue sólo automatizar XML, sino construir una plataforma que pudiera operar bajo condiciones reales: errores, reintentos, duplicados, diferencias entre ambientes, datos incompletos, particularidades del partner y complejidad del ERP.

La solución final dejó una base sólida para seguir escalando el ecosistema EDI del cliente sin depender de procesos manuales ni integraciones frágiles.

---