Primero el veredicto: la solución de problemas de integración API y EDI después del go-live no consiste en arreglar el enlace roto lo más rápido posible. Consiste en no empeorarlo. Los errores más caros que he visto no los causó la falla original. Los causó alguien que entró en pánico, reenvió todo, editó el inventario a mano y reinició la interfaz, convirtiendo una falla rastreable en un desorden que nadie podía conciliar. Así que antes de tocar nada, clasifica la falla. ¿El mensaje nunca llegó? ¿Llegó pero nunca se procesó? ¿Se procesó pero nunca se confirmó? ¿O tres sistemas insisten cada uno en que sus propios números son correctos? Si te equivocas en la clasificación, todo lo que sigue también estará mal. He visto este error tres veces, en tres almacenes distintos, con el mismo guion.

La primera historia es del otoño pasado, en un almacén de terceros de artículos para el hogar a las afueras de Ontario, California. En la tercera semana después del go-live, un martes por la mañana, el minorista informó que más de cuatrocientos pedidos nunca habían llegado al almacén. La persona de turno asumió que la interfaz estaba caída y la reinició dos veces. Nada cambió. La revisión mostró que el minorista había enviado los pedidos y que nuestra pasarela los había recibido, pero estaban atascados en la validación de pedidos porque el minorista había cambiado un sufijo en un código de producto sin avisarnos. Nada estaba roto. Ambas partes simplemente habían asumido que la otra no había cambiado nada. Pusimos los envíos en marcha mapeando temporalmente los códigos antiguos y luego impulsamos el cambio de código mediante un proceso formal de notificación. Desde entonces, reviso el registro de cambios antes que el registro del sistema.

La segunda historia es más dolorosa. Un almacén de pequeños electrodomésticos cerca de Chicago pasó su primer mes después del go-live con el inventario desviado en más de cien unidades al día, a veces por encima, a veces por debajo, y nadie pudo encontrar el patrón durante una semana. Resultaron ser dos problemas superpuestos. El sistema del minorista enviaba dos veces las recepciones de devoluciones, y nuestro lado no tenía control de idempotencia, así que las mismas devoluciones se contabilizaban dos veces. Además, los ajustes de conteo cíclico se introducían directamente en el WMS y nunca se devolvían al minorista. Cada lado seguía editando sus propios números y la brecha seguía creciendo. La solución no fue ingeniosa: deduplicar cada mensaje reenviado por el número de documento comercial y canalizar cada ajuste de inventario a través de la interfaz en lugar de permitir que alguien cambiara una cantidad y se marchara. Esas dos líneas han estado en mi lista de verificación de la noche del go-live desde entonces.

Averías API/EDI: clasifica primero, luego actúa

La clasificación se hace en cuatro frases, y debes hacer coincidir tu falla con una de ellas antes de abrir un archivo de registro. Uno, el mensaje nunca llegó: no se envió, se envió al endpoint equivocado, un certificado caducado, una interrupción de red. Dos, llegó pero nunca se procesó: atascado en la validación, el mapeo o un campo faltante. Tres, se procesó pero nunca se confirmó: el documento comercial se creó, pero la confirmación nunca regresó, así que el remitente asumió que nunca lo recibiste y lo envió de nuevo. Cuatro, todos discrepan: los sistemas de pedidos, envíos e inventario usan definiciones distintas, así que cada lado parece correcto por su cuenta.

Diez minutos de clasificación pueden ahorrar cuatro horas de buscar entre miles de líneas de registro sin saber qué tipo de problema estás buscando. Y una regla: no reinicies una interfaz de producción sin evidencia. Un reinicio borra el estado de los mensajes en tránsito, y un rastro que podías seguir se convierte en un rastro que ya no puedes seguir.

Muchos problemas posteriores al go-live se sembraron durante la selección, cuando nadie definió quién es dueño de los datos maestros ni quién detecta primero una excepción. Si estás revisando esas decisiones, la comparación de selección entre API y EDI es una referencia útil para escribir en tu acuerdo operativo las responsabilidades que omitiste.

Rastreo de mensajes API/EDI: encuentra el mensaje antes de discutir sobre él

Mi rutina de rastreo de mensajes tiene cinco pasos, y funcionan en este orden. Paso uno, lleva el número de documento comercial al sistema del remitente y confirma el registro de envío: ¿se envió, a qué endpoint y qué código de respuesta regresó? Paso dos, revisa el registro de recepción de tu propia pasarela y confirma que el mensaje original quedó almacenado. Paso tres, valida el mensaje original: ¿es un problema de formato, un problema de codificación o una regla comercial que lo bloquea? Paso cuatro, lee el registro de procesamiento comercial para ver exactamente dónde se detuvo y si se detuvo por un error del sistema o por una retención manual. Paso cinco, revisa el registro de confirmación: ¿se envió una confirmación y la aceptó la otra parte?

Esta es la parte contraintuitiva: una respuesta de éxito no significa éxito comercial. Muchas interfaces devuelven un 200 solo para decir "recibido", no para decir que el pedido se creó o que el inventario se descontó correctamente. Una vez vi a dos equipos mostrarse registros 200 durante dos días mientras los pedidos permanecían en una cola de middleware. Juzga por el estado del documento comercial, nunca solo por el código de respuesta. El código de respuesta solo demuestra que la transmisión no se rompió. No demuestra que el negocio se haya hecho bien.

Otra falla clásica: el equipo solo probó el camino feliz en el entorno de pruebas y nunca probó un reenvío, un mensaje fuera de orden o un campo vacío. Esos tres pertenecen a la lista de verificación de la noche del go-live como pruebas separadas. Un reenvío prueba la idempotencia, un mensaje fuera de orden prueba la máquina de estados del documento y un campo vacío prueba si el sistema genera un error visible o descarta el documento en silencio. Los descartes silenciosos son lo peor de los tres, porque un error al menos avisa a alguien, mientras que un descarte silencioso solo se descubre cuando un cliente se queja.

Pedidos atascados: sigue esta lista de verificación, casilla por casilla

Cuando los pedidos se atascan, la solución de problemas de integración API y EDI comienza con una regla: no los crees a mano para salvar el día. Un pedido creado a mano resuelve el envío de hoy y garantiza un problema de conciliación mañana, ya sea un duplicado o un pedido faltante. Sigue esta lista de verificación en su lugar y exige evidencia para cada casilla, una entrada de registro o un estado de documento, no "creo que se envió". ¿Existe el número de documento en el sistema del remitente? ¿Llegó el mensaje a la pasarela? ¿Pasó la validación? ¿Se mapearon los códigos de producto y ubicación? ¿Hay suficiente inventario? ¿Está el documento en una retención manual?

Una vez que encuentres la causa raíz, el orden de la reparación importa. Protege primero los envíos, corrige segundo los datos y discute por último la culpa. Si es un problema de mapeo, pon un mapeo temporal para proteger los envíos de hoy mientras el cambio formal sigue su curso. Si es una escasez de existencias, confirma si la escasez es real o solo datos de inventario desactualizados antes de liberar el pedido; un retraso de datos pide conciliación, una escasez real pide el proceso de escasez, y forzar el pedido no ayuda a nadie. Después de arreglar un pedido, revisa si el resto del lote comparte la misma causa.

Haz las cuentas de por qué las soluciones manuales no escalan. Supón que cuatrocientos pedidos se atascan en un día y que cada uno requiere ocho minutos de revisión y gestión manual. Eso son 3,200 minutos, más de cincuenta horas, y dos personas trabajando horas extra aun así no terminarán. Cuando los pedidos atascados superan cierto volumen, la respuesta correcta es arreglar el enlace y el proceso en bloque, no añadir personas. Añadir personas convierte un problema de sistema en un problema de mano de obra, y solo se vuelve más caro.

Descuadres de inventario: la conciliación en tres pasos

Para los descuadres de inventario, la solución de problemas de integración API y EDI se reduce a tres pasos. Paso uno, concilia los totales: la cantidad disponible en el WMS, la cantidad disponible en el otro sistema y la última cantidad en la que ambos lados estuvieron de acuerdo; luego indica el tamaño de la brecha y la fecha en que apareció por primera vez. Paso dos, concilia los flujos: desde la fecha base hasta hoy, compara recepciones, envíos, devoluciones y ajustes como cuatro categorías separadas y encuentra qué categoría tiene una brecha acumulada igual a la brecha total. Paso tres, concilia los documentos: toma la categoría con la mayor brecha, toma una muestra de algunas transacciones y revísalas una por una en busca de duplicados, omisiones o diferencias de definición.

Las diferencias de definición son la causa más pasada por alto: un lado puede contar el stock en tránsito como disponible mientras el otro no. Los números pueden discrepar sin que nadie esté equivocado, porque los dos lados no están contando lo mismo. Antes de conciliar, escribe qué significan disponible, disponible para la venta y en tránsito, y logra que ambos lados estén de acuerdo. Sin definiciones acordadas, la conciliación termina con cada lado insistiendo en que tiene razón.

Una última regla operativa. Una interfaz no termina el día del go-live. Los primeros treinta días son el periodo de mayor riesgo, cuando la otra parte puede cambiar un código, rotar un certificado o cambiar una frecuencia de envío sin avisarte. Mi práctica ahora es una conciliación semanal durante el primer mes, más la rotación de certificados dos semanas antes de su vencimiento. Las operaciones de interfaz se ganan cumpliendo estas rutinas poco glamorosas.

Por Lin Xiao, Consultor de Implementación de WMS

Traducido del inglés. En caso de discrepancia, prevalece la versión en inglés.