Un cliente 3PL en Fontana cerró noviembre y encontró que su gasto de fletes de octubre estaba casi $4,000 por encima del plan. Tardaron dos semanas en encontrar la causa: 45 días antes, la transportista había cambiado en silencio sus reglas de recargo por zona remota. Nadie actualizó el TMS, el motor de tarifas del WMS seguía cotizando con las reglas viejas y la factura llegó 45 días tarde. El flete se movió bien. El dinero se filtró en silencio.
Ese incidente cambió mi forma de revisar cada proyecto WMS-TMS. Primero reviso la ruta de los callbacks, no el envío hacia afuera. Cualquiera puede empujar un embarque al TMS. Todo se rompe en el camino de regreso.
La cadena es simple: el WMS envía los datos del embarque al TMS o a la transportista, la transportista recoge, mueve y entrega, y las actualizaciones de estado y las facturas suben por la cadena. Los tres puntos de fallo viven en esos viajes de vuelta.
El callback murió, y la orden está "en tránsito" para siempre
La escena clásica: el paquete se entregó hace dos días, el cliente llama pidiendo el comprobante de entrega, y el representante mira en el WMS — sigue "en tránsito". El webhook del TMS nunca se disparó, o el POD de la transportista nunca regresó. La orden queda atascada, el inventario sigue reservado, y a fin de mes hay un montón de registros "enviados" flotando en el limbo mientras finanzas los concilia a mano, un número de rastreo a la vez.
La causa raíz casi siempre es una máquina de estados dibujada demasiado gruesa. La mayoría de las integraciones modelan dos estados — enviado y completado — y mapean cada estado del TMS (en tránsito, en reparto, entregado) a "completado". Las excepciones (devuelto, anulado, dañado) ni siquiera tienen su propio canal de callback. Lo que yo uso ahora: el estado del embarque en el WMS se divide en al menos cinco — enviado, recogido, en tránsito, entregado y excepción. Cada código de estado del TMS tiene un mapeo explícito, y todo lo que no encaja va a una bandeja de excepciones para revisión humana.
Mi tabla de mapeo es así: TMS picked_up y departed se mapean a recogido; in_transit, arrived_at_hub y out_for_delivery se mapean a en tránsito; delivered se mapea a entregado; exception, returned_to_sender, voided, damaged y lost van todos a la bandeja de excepciones — nunca se les permite fluir automáticamente hacia entregado. Esa última línea es la línea roja. Una vez que una excepción se etiqueta mal como entregada, atención al cliente, finanzas e inventario están todos mal a la vez, y desenredarlo cuesta el triple de trabajo.
Luego agrega cinturón y tirantes: webhooks para tiempo real, más un pull programado como respaldo. El trabajo de respaldo corre cada hora y consulta activamente al TMS por cualquier cosa atascada "en tránsito" más de 24 horas. Es un pedazo de código pequeño y el parche de mayor ROI que conozco en este espacio. Un monitor más: alerta si el receptor de webhooks pasa 30 minutos con cero callbacks. Las cadenas de callback mueren en silencio. Nadie mirando significa tres días de silencio.
La factura llega tarde con campos que no coinciden, y el fin de mes queda desviado por miles
Las facturas de las transportistas llegan rutinariamente de 30 a 45 días después de los hechos, y las tablas de recargo de combustible y las reglas de zona remota cambian sin ceremonia. Cuando la estimación del WMS no coincide con la factura, finanzas siempre asume primero que el WMS está mal. La mayoría de las veces, una versión de regla nunca se sincronizó.
Primero clava la lista de verificación de mapeo de campos. Esta es la base contra la que todo lo demás se concilia:
| Campo WMS | Campo de factura TMS / transportista | Notas |
|---|---|---|
| Shipment ID | tracking number / PRO number | La clave única en toda la cadena, la llave primaria de la conciliación |
| Billed weight | billed weight | Cuidado con la regla del mayor entre peso real y dimensional |
| Destination zone | zone | Conserva versiones cuando cambien las tablas de zonas |
| Service level | service level | ground / 2-day / overnight, etc. |
| Fuel surcharge | fuel surcharge | Iguala la versión de la tarifa con la fecha de la factura |
| Accessorial detail | accessorial charges | Zona remota, sobredimensión, residencial — línea por línea |
| Quoted at ship time | quoted amount | La estimación al momento de licitar |
| Invoiced | invoiced amount | Lo que la transportista realmente factura |
| Invoice date | invoice date | Determina qué versión de tarifa aplica |
Yo nunca codifico tarifas específicas — las tablas de tarifas de las transportistas y las políticas de recargo cambian año con año, así que trata la política publicada más reciente de la transportista como la fuente de verdad. Lo que el sistema necesita es una tabla de versiones de reglas: cada regla de tarificación lleva una fecha de vigencia, y la conciliación iguala la versión de la regla contra la fecha de la factura. Los $4,000 del cliente de Fontana murieron por la tabla de versiones de reglas que faltaba.
Luego corre dos ventanas de conciliación en lugar de una sola carrera de fin de mes. Siete días después de la fecha de embarque, corre la conciliación de la estimación: estimación del WMS contra el costo devuelto por el TMS, y marca cualquier desviación de más del 5%. Luego corre la conciliación final dentro de los tres días siguientes a la llegada de la factura. Dividir las ventanas significa que los embarques problemáticos aparecen en la semana uno en lugar del día 45.
La ventana de estimación tiene un beneficio lateral: detecta la deriva sistémica en el motor de tarifas. Si un nivel de servicio — digamos overnight — sale 8% o más por debajo del costo devuelto durante dos semanas seguidas, casi seguro te falta un accesorio en las reglas de tarificación. Arréglalo temprano y el ahorro se compone. La conciliación final tiene otro trabajo: factura contra costo devuelto, línea por línea, y todo lo que no cuadre va directo al proceso de disputa con la transportista. Las ventanas de corrección de facturas de las transportistas son limitadas — una vez que la ventana se cierra, el dinero pagado de más se pierde para siempre, así que revisa la política vigente de cada transportista.
Reintentos sin idempotencia: el mismo embarque empujado tres veces
La red falla, el WMS no recibe el acuse del TMS, y la lógica vieja reintenta el envío. Excepto que el TMS sí recibió la primera solicitud — solo se perdió la respuesta. Ahora el mismo embarque existe tres veces en el TMS, y algunas transportistas felizmente generan tres etiquetas. Peor, el reintento a veces sobrescribe la primera cotización, así que la factura no coincide con nada.
Dos arreglos, y ambos son no negociables. Envía un ID de solicitud globalmente único con cada envío; el TMS y la transportista deduplican por ese ID, y un ID repetido devuelve el primer resultado sin re-ejecutar la acción de negocio. Usa reintentos de intervalo fijo más retroceso exponencial — digamos 5 minutos, 30 minutos, 2 horas — y lo que pase del límite va a una cola manual. Nunca reintentes para siempre. Y revisa el "registro de enviados" local antes de cada envío: una solicitud con entrada en el registro nunca se reenvía. La idempotencia cuesta medio día de diseño y ahorra tres días de contabilidad forense.
Un detalle que la gente pasa por alto: nunca regeneres el ID de solicitud en el reintento. Cada reintento del mismo embarque debe llevar el mismo ID de solicitud, o la deduplicación del TMS es decorativa. El ajuste de timeouts también importa. Las APIs de las transportistas se vuelven lentas en temporada alta; un timeout de 5 segundos dispara reintentos constantemente, mientras que 30 segundos más retroceso reducen drásticamente los reintentos falsos.
Mi veredicto sobre qué escala merece integración profunda
Aquí va la versión corta. Menos de 300 órdenes al día con una o dos transportistas: la conciliación con CSV basta. Exporta el detalle de costos del TMS cada semana, úneló contra los registros de embarque del WMS, y medio día de trabajo manual cierra el mes. Construir integración en tiempo real para ese volumen — el costo de desarrollo y mantenimiento casi seguro excede lo que ahorra. No vale la pena.
Más de 500 órdenes al día, o tres o más transportistas con niveles de servicio mixtos: la integración profunda con conciliación automatizada es obligatoria. A ese volumen, la mano de obra de conciliación manual y el riesgo de pagar de más/de menos ya exceden el costo de construcción. La banda media — 300 a 500 — puede ir semi-automatizada: envío y callbacks de estado por API, conciliación de facturas vía importación CSV semi-automatizada, y completa el resto cuando crezca el volumen.
Una regla dura sin importar la escala: en la primera semana después del go-live, revisa a mano 20 embarques al día de punta a punta — envío WMS, estado TMS, factura de la transportista, los tres lados. Esa semana de trabajo manual es lo que te compra un año tranquilo.
Lo que puedes hacer mañana: corre esta noche un reporte que liste cada orden del WMS atascada "en tránsito" más de 48 horas, y verifica el estado real de cada una en el TMS. Hasta que esa brecha se cierre, cada conciliación, cada análisis, cada proyecto de ahorro es una casa construida sobre arena. Tapa primero los huecos de los callbacks, y luego habla de optimización.
Traducido del inglés. En caso de discrepancia, prevalece la versión en inglés.
