Vamos al grano desde el principio: cuando faltan etiquetas de envío, el transportista casi nunca tiene la culpa. El pedido murió en algún punto de tu propia cadena de integración, entre el WMS y la API de etiquetas del transportista. No empieces llamando al transportista. Depura en este orden: despacho del WMS → capa de API/cola → respuesta del transportista → escritura de estado → estación de impresión. Dondequiera que se detenga el pedido, ahí vive tu problema. Si te equivocas de orden, quemarás tres días sin encontrar nada.
Por qué los pedidos "se esfuman"
Una solicitud de etiqueta viaja por cinco eslabones antes de llegar al paquete:
- El WMS genera una solicitud de envío.
- La capa de integración (o middleware) la envía a la API del transportista.
- El transportista devuelve los datos de la etiqueta y un número de seguimiento.
- El WMS escribe el número de seguimiento en el pedido y lo mueve a "listo para imprimir".
- La estación de empaque imprime la etiqueta y el operario la pega en la caja.
Cada eslabón puede tragarse un pedido: la solicitud nunca sale, se pudre en una cola sin consumir, tu lado agota el tiempo antes de leer la respuesta del transportista, la escritura falla, la impresora está desconectada. Los errores son el caso fácil — al menos puedes verlos. Lo letal es el fallo silencioso: tu WMS cree que envió la solicitud, el transportista cree que nunca llegó, y el pedido queda en el hueco, reclamado por nadie. Por eso el almacén grita "pedidos perdidos" mientras TI insiste en que "los registros se ven bien".
Lo he visto tres veces: dos historias de guerra
La primera, el pasado noviembre, en un almacén 3PL de ropa en el este de China que usaba la API de etiquetas de UPS. Cada día faltaban de veinte a treinta etiquetas, y el transportista juraba que su backend nunca recibió las solicitudes. Una tarde de investigación lo encontró: el tiempo de espera (timeout) era de 5 segundos, y en temporada alta la API del transportista respondía en 8 a 10. Cada timeout hacía que el WMS marcara el pedido como "etiqueta fallida" — mientras el transportista ya había generado la etiqueta y el número de seguimiento. Dos historias, un pedido: el WMS mostraba fallos esperando reimpresión manual, la facturación del transportista ya había cobrado las etiquetas. Peor aún, el almacén veía "fallido" y pulsaba reintentar, y el reintento producía un segundo número de seguimiento para el mismo pedido. Dos etiquetas candidatas por paquete — elige la equivocada y es un paquete perdido más un cliente furioso.
La segunda, este marzo, en un almacén de comercio electrónico transfronterizo en el sur de China que usaba la API de un transportista internacional. Los pedidos realizados entre la medianoche y las 2 AM desaparecían en masa; de día todo funcionaba perfectamente. Causa raíz más desagradable: la API del transportista tenía una ventana de mantenimiento nocturna que devolvía "servicio no disponible", y la capa de integración del WMS no tenía ninguna cola de fallos. Las solicitudes fallidas simplemente se descartaban — sin reintento, sin alerta, sin registro. Dos horas de pedidos no dejaron rastro en el sistema, los pedidos quedaron en "esperando etiqueta", y el almacén asumió que el sistema iba con retraso y esperó hasta la mañana. Los registros mostraron la verdad: dos horas completas de solicitudes ni siquiera se enviaron. La capa de integración se las comió.
Síntomas distintos, misma causa raíz: nadie estaba conciliando la cadena de etiquetas. El dinero se concilia. El inventario se concilia. ¿Las etiquetas? Trabajo de nadie.
El manual: una cadena de depuración de cinco eslabones
Esta es mi lista de verificación de la noche de lanzamiento. Hago que los clientes marquen cada casilla antes del lanzamiento.
Paso 1: Revisa el registro de despacho del WMS. Confirma que cada pedido enviable tenga un registro de solicitud de despacho con número de pedido, peso y dimensiones del paquete, y producto de servicio. Si el pedido nunca generó una solicitud dentro del WMS, el problema es interno — una máquina de estados del pedido atascada, un programador de despacho muerto. Sáltate la API.
Paso 2: Revisa la cola de la capa de integración. Para despacho asíncrono, mira el rezago de la cola, si los consumidores están vivos, y qué se acumula en la cola de mensajes muertos (dead-letter queue). Para llamadas síncronas, mira la configuración de timeout y reintentos. El timeout nunca debe ser menor que el techo de respuesta del SLA del transportista — y en temporada alta, duplícalo con margen. El timeout de 5 segundos del almacén de ropa se detectó justo aquí.
Paso 3: Revisa la respuesta del transportista. Cada solicitud necesita un registro emparejado solicitud-respuesta: qué se envió, con qué marca de tiempo, qué llegó de vuelta, y el número de seguimiento. Registrar la solicitud sin la respuesta es lo mismo que no registrar nada — el peor sistema que he visto solo almacenaba las palabras "llamada exitosa", ni siquiera el número de seguimiento.
Paso 4: Revisa la escritura de estado. Después de que el transportista devuelva un número de seguimiento, el WMS debe escribirlo en el pedido y avanzar el estado a "listo para imprimir". Una escritura fallida debe ir a una cola de reintentos, nunca saltarse en silencio. La escritura es la zona de más bajas — en muchos sistemas la solicitud y la escritura son dos transacciones independientes. La solicitud tiene éxito, la escritura muere, y el pedido flota en el limbo: el transportista lo tiene, el WMS no.
Paso 5: Revisa la impresora. La impresora de la estación de empaque se desconecta, se queda sin papel, el controlador falla, la etiqueta no sale, y el operario hace clic en "reimprimir". La reimpresión debe seguir el flujo de reimpresión — el mismo número de seguimiento existente, papel nuevo. Nunca emitas una solicitud de etiqueta nueva, o un pedido se convierte en dos números de seguimiento y la conciliación de fin de mes se vuelve tu pesadilla personal.
Paso 6: Concilia la cadena completa. Después del corte diario, ejecuta una conciliación cuádruple: conteo de despacho del WMS = conteo de solicitudes de la capa de integración = conteo de éxitos del transportista = conteo impreso. Cualquier diferencia son tus etiquetas perdidas, cuantificadas. Este script de conciliación debe existir el día uno del lanzamiento — no después del primer incidente. Escríbelo tarde y ni siquiera podrás responder "¿cuántos perdimos?".
Paso 7: Claves de idempotencia. Cada solicitud de etiqueta lleva una clave de idempotencia globalmente única. Usa número de pedido más secuencia de paquete — nunca el número de pedido solo, porque los pedidos multipaquete colisionarán. Tanto el lado del transportista como tu propia capa de integración deben deduplicar por la clave. Esta es la única defensa contra "el reintento imprime una etiqueta duplicada". No hay una segunda.
| Eslabón | Síntoma típico | Acción de depuración |
|---|---|---|
| Despacho del WMS | Pedidos atascados en "esperando etiqueta", sin registro de solicitud | Revisa la máquina de estados del pedido, el programador de despacho |
| Cola de la API | Latencia creciente, cola de mensajes muertos acumulándose | Revisa la salud de los consumidores, alertas de profundidad de cola |
| Respuesta del transportista | Timeouts frecuentes, fallos esporádicos | Verifica la configuración de timeout, página de estado del transportista, registros emparejados |
| Escritura de estado | Existe el número de seguimiento pero el estado del pedido no cambia | Revisa la transacción de escritura, la cola de reintentos |
| Estación de impresión | Los operarios reportan "no imprime nada" | Revisa el estado de la impresora, usa el flujo de reimpresión, nunca re-solicites |
Puntos de fallo comunes (autoevaluación antes del lanzamiento)
- Timeout demasiado corto. Siempre explota en temporada alta. Lo he visto tres veces, y cada vez la historia empieza con "funcionaba bien hasta la gran venta".
- Fallos descartados en lugar de encolados. Una ventana de mantenimiento de medianoche o un 500 aleatorio del transportista se convierte en "pedido no encontrado".
- Reintentos sin claves de idempotencia. Reintentar se siente bien; la conciliación de fin de mes es la resaca — el transportista cobra por cada etiqueta duplicada.
- Conciliar dinero e inventario pero no etiquetas. Finanzas cuadra, inventario cuadra, y nadie nota unas docenas de etiquetas perdidas hasta que los clientes reportan paquetes que nunca llegaron.
- Tratar "llamada exitosa" como "etiqueta creada". Un 200 de la API del transportista no significa que se generó una etiqueta. Lee el código de estado de negocio dentro del cuerpo de la respuesta — los transportistas envuelven rutinariamente un fallo de negocio en un HTTP 200.
La parte contraintuitiva
El modo de fallo más peligroso no es un error — es el falso éxito. Un error dispara una alerta y alguien mira. Pero "solicitud enviada, el WMS muestra éxito, el transportista nunca la recibió" puede estar tranquilo durante semanas, y luego detonar la mañana de tu mayor venta. Una regla defiende contra esto: el número de seguimiento devuelto por el transportista es la única fuente de verdad. Cualquier pedido sin uno se trata como nunca enviado. Alinéalo con el almacén y servicio al cliente antes del lanzamiento, o los tres lados discutirán sobre esto después del incidente — con TI cargando la culpa.
Un compromiso merece honestidad: llamadas síncronas frente a cola asíncrona. Síncrono es simple — el operario hace clic en imprimir y conoce el resultado — pero una respuesta lenta del transportista bloquea toda la línea de empaque. Asíncrono da rendimiento y absorbe picos, pero la cadena se alarga y la depuración se vuelve el doble de difícil. Mi regla: por debajo de 5,000 pedidos al día, ve síncrono con timeouts cortos y una cola de revisión manual para fallos. Por encima, ve asíncrono — pero solo después de que la conciliación de cadena completa y las alertas de arriba estén en su lugar. Asíncrono no es una bala de plata; convierte "error en tu cara" en "conciliación después del hecho". Una conciliación débil hace que las pérdidas asíncronas sean más difíciles de encontrar que las síncronas.
Las APIs de etiquetas parecen tranquilas hasta las 3 AM del día de la venta. Imprime esta lista y pégala junto a la estación de empaque. Supera a cualquier panel.
Por Lin Xiao, Consultor de Implementación WMS
Traducido del inglés. En caso de discrepancia, prevalece la versión en inglés.
