La etiqueta se imprimió. El paquete nunca se envió. Nueve de cada diez veces, el pedido murió en algún punto de la cadena de API.
Durante la temporada alta de 2023, un 3PL de Los Ángeles me llamó. Estaban procesando 12,000 pedidos al día, con las impresoras de etiquetas trabajando sin parar — pero cada noche, el conteo real de recogidas del carrier salía corto en más de 300 paquetes frente al conteo de enviados del sistema. Reclamaciones, reembolsos, reenvíos: varios miles de dólares quemados cada día. El picking estaba bien. La impresión estaba bien. Cada pedido perdido había muerto en la cadena entre el WMS y la API de etiquetas del carrier.
Mi veredicto por adelantado: las etiquetas perdidas casi nunca mueren en la impresora. Los verdaderos asesinos son tres: la solicitud nunca salió de tu edificio, un reintento por timeout creó etiquetas duplicadas, o nadie estaba conciliando. Esta cadena de diagnóstico viene de años integrando API de etiquetas de carriers. Síguela en orden y encontrarás el punto de ruptura.
Paso uno: ¿la solicitud salió alguna vez de tu edificio?
La forma más tonta de perder un pedido es que tu WMS nunca envíe la solicitud — o que la envíe, no reciba nada de vuelta, y asuma que todo salió bien.
Mi primer movimiento es siempre el log local de solicitudes. No el estado del pedido en el WMS — los registros de llamadas de la puerta de enlace de salida. Para este pedido, ¿hay un registro de una llamada de "solicitud de etiqueta al carrier"? Si no lo hay, deja de leer documentación de API y de ajustar timeouts. El problema está de tu lado. Los sospechosos habituales: un consumidor de cola de mensajes caído con la cola acumulándose en silencio, un job programado que nunca arrancó, o un pedido atascado en una transición de estado — el OMS pasó el pedido, pero el WMS seguía esperando la liberación de la wave, así que la solicitud de etiqueta nunca se disparó. Lo he visto más de una vez: caos de temporada alta, una política de wave mal configurada, y unos cientos de pedidos sentados en silencio en "pendiente de liberación" mientras la solicitud de etiqueta ni siquiera se había enviado.
Hay una variante más traicionera: la solicitud salió, pero el log no la capturó. Algunos sistemas solo registran los éxitos. Otros rotan los logs con tanta agresividad que los minutos que importan ya desaparecieron. Mi regla permanente para los clientes: registra cada llamada a la API de etiquetas en completo — qué se envió, cuándo, qué devolvió, cuánto tardó. Cuando discutes con un carrier una discrepancia de facturación o gestionas una reclamación de un cliente, el log es tu única evidencia. Con logs incompletos, nadie puede ayudarte a encontrar la ruptura.
Así que el veredicto del paso uno es simple: sin registro en el log, el problema está dentro de tus propias paredes — arregla primero la cadena interna. Si hay registro, sigue adelante.
Los timeouts son el verdadero asesino: puede que el carrier ya haya creado la etiqueta
Esta es la forma más letal y más injusta de perder un pedido.
La escena: el WMS llama a la API de etiquetas del carrier, el carrier tarda demasiado, la llamada supera el timeout (cada carrier es distinto — sigue su documentación), así que el WMS la marca como agotada y reintenta automáticamente. La segunda llamada tiene éxito, la etiqueta llega, todos celebran — excepto que la primera solicitud ya había creado la etiqueta del lado del carrier. La respuesta simplemente nunca volvió. Ahora este pedido tiene dos etiquetas y dos números de seguimiento.
Dos consecuencias. Primera: pagas dos veces: algunos carriers facturan por etiqueta creada, y su proceso de anulación es lo bastante doloroso como para que los almacenes pequeños nunca se molesten en anular una por una — el dinero se fuga en silencio. Segunda: el almacén solo pega una etiqueta en un paquete y lo envía. La otra se convierte en una etiqueta fantasma — creada en el sistema, rastreable por el cliente, pero el paquete nunca mostrará un escaneo de recogida. El servicio al cliente la busca: número de seguimiento válido, cero eventos de rastreo. Nadie puede explicarlo. Asumes el costo y reenvías. Lo enloquecedor: el WMS se ve bien, el rastreo del carrier se ve "bien" — ambos lados normales, y la mercancía nunca se movió.
La solución son dos palabras: idempotencia y política de reintentos.
Idempotencia significa que cada solicitud de etiqueta lleva una clave única de negocio — número de pedido más secuencia de paquete, por ejemplo — y la API del carrier devuelve la misma etiqueta ante solicitudes repetidas con la misma clave. Confírmalo con el carrier durante la integración. Algunas API no activan la idempotencia por defecto; hay que pedirla en el contrato o en la configuración. Enviar reintentos sin ella es plantar tu propia mina. Que quede escrito en el contrato durante la negociación, no después de que algo se rompa.
Política de reintentos significa nunca reenviar a ciegas tras un timeout. Mi enfoque: ante el primer timeout, consulta primero al carrier — usa la referencia del pedido o del paquete para verificar si la etiqueta ya se creó. Si se creó, usa la existente. Reenvía solo si no se creó. Una consulta cuesta mucho menos que limpiar una pila de etiquetas fantasma. Limita tus reintentos, espácialos, y no insistas mientras el sistema del carrier ya está sufriendo. En temporada alta la API del carrier ya va lenta — los reintentos ciegos solo la hacen más lenta, un círculo vicioso.
¿Y la impresora? Rara vez pierde pedidos. Una etiqueta impresa pero nunca aplicada, o aplicada al paquete equivocado — eso es gestión de piso, se resuelve con cámaras y registros de picking, no es un problema de API. De los pedidos que mueren en la cadena de API, nueve de cada diez mueren en la palabra "timeout".
Ejecuta la conciliación cada día y deja que atrape todo lo demás
Los dos primeros pasos son "cómo investigar cuando algo se rompe". Este es "cómo saber de inmediato cuando algo se rompe".
Por sólida que sea la cadena, insisto en que los clientes ejecuten un job diario de conciliación. La lógica son tres líneas: toma el conteo de etiquetas creadas del carrier (vía su API de conciliación o descarga de facturación), toma el conteo real de enviados del WMS, emparéjalos por pedido o número de seguimiento, y la diferencia son tus pedidos perdidos. Cuidado con las definiciones: excluye las etiquetas anuladas, concilia cada carrier por separado — no cuentes las etiquetas del carrier A contra el carrier B — y ejecútalo a una hora fija cada día. Yo suelo recomendar temprano en la mañana, fuera de la ventana de liquidación del carrier.
¿Cómo fijas el umbral de alerta? Mi regla práctica: alerta cuando la brecha supere el 0.5% del volumen del día; llama al teléfono de alguien cuando supere el 2%. No alertes por cualquier diferencia — los carriers a veces crean etiquetas en lotes, como corridas de liquidación nocturnas, así que una etiqueta creada hoy puede no aparecer en el archivo de facturación hasta mañana. La tolerancia cero solo entrena a todos a ignorar las alertas, y luego nadie mira cuando de verdad importa. Un umbral está para usarse, no para venerarse — si lo pones demasiado sensible es lo mismo que no tener ninguno.
Ese 3PL de Los Ángeles sobrevivió gracias a este job de conciliación. Antes de que existiera, ni siquiera podían decir cuántos pedidos perdían al día — esa es la parte más aterradora, no saber el tamaño del problema. Después de ponerlo en marcha, los pedidos perdidos bajaron de más de 300 al día a un solo dígito, y los pocos restantes eran paquetes mal etiquetados en el piso — nada que ver con la API. Cada mañana, operaciones empieza el día con el reporte de conciliación. Cualquier brecha se investiga el mismo día. Los problemas no pasan la noche.
Recuerda esta cadena: primero los logs, luego los timeouts, luego la impresora — y concilia todos los días.
Traducido del inglés. En caso de discrepancia, prevalece la versión en inglés.
