La conclusión primero: cuando integras una API de seguimiento de transportistas en tu WMS u OMS, conseguir una respuesta exitosa a una consulta es solo alrededor del 30 % del trabajo. He participado en más de 30 salidas a producción de WMS, y las integraciones de seguimiento nunca fallan porque «la consulta no funcionara». Fallan porque los estados se tradujeron mal, las actualizaciones dejaron de llegar en silencio o el transportista limitó tus consultas. Los seis errores que siguen son los que he visto más de una vez, y al final hay una lista de verificación para la noche del go-live. Imprímela y marca cada casilla.
Primero, define el problema real que resuelve la API de seguimiento
Tu WMS u OMS tiene que responder tres preguntas al cliente: ¿se envió?, ¿dónde está? y ¿se recibió? La API del transportista habla otro idioma: docenas de códigos de estado, actualizaciones que llegan tarde y alguna que otra caída. Tu trabajo es traducir y respaldar. Este error lo he visto tres veces — un equipo trató «la API devolvió 200» como «integración completada», y dos semanas después del go-live empezaron a llegar los tickets de soporte: «Dice entregado, pero nunca me llegó nada». Nadie había construido la tabla de mapeo de estados.
Un caso de 2023: un almacén 3PL en Ontario, California, que enviaba unos 6,000 pedidos al día. Su montaje era un trabajo programado que barría cada número de seguimiento en tránsito cada 15 minutos y consultaba la API de seguimiento de cada transportista uno por uno. Funcionaba bien — hasta que la temporada alta empujó el volumen por encima de los 9,000 pedidos diarios. El volumen de consultas se duplicó con ello, chocó contra el límite de consultas del transportista y la cuenta quedó limitada. Las actualizaciones de seguimiento se detuvieron durante dos días completos. Los teléfonos de atención al cliente se colapsaron mientras operaciones comprobaba los números de seguimiento manualmente en los sitios web de los transportistas. Cuando entramos a arreglarlo, lo primero que hicimos fue eliminar el sondeo completo: cambiamos a callbacks por webhook para el envío de estados y dejamos el sondeo solo como red de seguridad para los envíos sin actualización en más de 24 horas. Dos semanas después, el seguimiento estaba sano de nuevo y el volumen de consultas había caído a menos de una décima parte.
Integración de la API de seguimiento: polling frente a webhooks — decide esto primero
Este es el error número uno, y el más caro. Ningún patrón es universalmente mejor, pero elegir mal significa parches para siempre.
| Polling | Webhooks | |
|---|---|---|
| Actualidad | Depende del intervalo, normalmente 15–60 min de retraso | Casi en tiempo real, se envía al actualizarse |
| Carga de API | Alta — los barridos completos chocan rápido con los límites | Ligera — solo los envíos que cambiaron |
| Fiabilidad | Estable, tú controlas el ritmo | Depende del envío del transportista; los callbacks perdidos los tienes que detectar tú |
| Ideal para | Red de seguridad, relleno, conciliación | Pipeline principal |
Aquí está la parte contraintuitiva: los webhooks no son una «mejora» del polling. Son socios. La arquitectura correcta es webhooks como pipeline principal más polling programado de respaldo como seguro. Este error lo he visto tres veces — un equipo apostó todo a los webhooks, el servicio de envío del transportista se cayó medio día y nadie de su lado lo notó porque todo «se veía bien».
Paso a paso:
- Confirma si cada transportista que integres soporta realmente webhooks. Las políticas varían; guíate por la documentación publicada más reciente del transportista.
- Si lo soporta: construye el receptor de callbacks con tres elementos no negociables — verificación de firma, idempotencia y almacenamiento del payload en bruto. La verificación bloquea envíos falsificados, la idempotencia maneja envíos duplicados (los transportistas reenvían todo el tiempo) y el almacenamiento en bruto permite conciliar después.
- Si no lo soporta: haz polling, pero limita el sondeo a los envíos que están en tránsito y no tienen actualización desde hace N horas. Nunca barras todo.
- En cualquier caso, ejecuta un trabajo de respaldo: barre todos los envíos en tránsito sin actualización en 24 horas, una vez al día, para detectar cualquier envío webhook perdido.
Los códigos de estado del transportista sin traducir son minas terrestres
El error número dos. Cada empresa de paquetería y de transporte por carretera tiene su propio sistema de códigos de estado. «Delivered» significa prueba de entrega en un transportista y «entregado en un punto de recogida» en otro. Pasar los códigos en bruto a los clientes es delegar el trabajo de traducción a tu equipo de soporte.
En 2024, un vendedor de comercio electrónico transfronterizo en Shenzhen, que enviaba unos 4,000 pedidos al día, integró APIs de seguimiento de tres transportistas. Su lógica de mapeo era simple: todo lo que contuviera «deliver» pasaba a ser «Delivered». Un lote de envíos en EE. UU. fue entregado en puntos de recogida de agentes («delivered to agent»), y el sistema los marcó todos como entregados. Más de 200 compradores dijeron que nunca recibieron nada, y las disputas más los reembolsos explotaron juntos. Cuando reconstruimos la tabla de mapeo, «entregado a agente» pasó a ser su propio estado — «listo para recoger» — y soporte contactó proactivamente a los compradores. El volumen de disputas cayó en una semana.
Paso a paso:
- Construye una tabla de mapeo de estados: código de estado en bruto del transportista → un estado canónico interno (recogido / en tránsito / en reparto / entregado a agente / entregado / excepción / devuelto).
- Mapea fino, no grueso. «Entregado a agente», «entrega fallida» y «dirección incorrecta» deben ser sus propias categorías — nunca plegadas dentro de «entregado» o «en tránsito».
- Para cada transportista nuevo, ejecútalo dos semanas en modo sombra: registra los resultados del mapeo sin mostrarlos a nadie, revisa manualmente 100 envíos y luego libera.
- Versiona la tabla de mapeo para poder rastrear cuándo un transportista cambia sus códigos.
Límites de consultas, caché y alertas: estos tres siempre explotan juntos
Los errores tres y cuatro van juntos porque siempre explotan juntos. Casi todos los feeds de seguimiento de transportistas tienen límites de consultas — los números exactos varían por transportista, así que consulta la política publicada más reciente — y excederlos hace que te limiten o te corten. Hay exactamente una forma de mantener bajo el volumen de consultas: la caché.
Paso a paso:
- Cachea los resultados de seguimiento por número de seguimiento. Los envíos entregados se cachean durante 7 días — el estado nunca volverá a cambiar, así que basta con una consulta.
- Los envíos en tránsito se cachean durante 15–30 minutos. Tu frontend y tu equipo de soporte leen de la caché, nunca directamente de la API del transportista.
- Deduplica las consultas concurrentes: las consultas repetidas del mismo número en 5 minutos disparan exactamente una petición real.
- Configura tres niveles de alertas: (1) un envío sin actualización de seguimiento durante más de 24 horas → operaciones hace seguimiento; (2) una regresión de estado — p. ej., pasar de «en reparto» de vuelta a «en tránsito» → alerta inmediata, suele ser la primera señal de un envío perdido o devuelto; (3) fallos consecutivos de la API durante más de 10 minutos → alerta de ingeniería, probablemente te están limitando o el servicio del transportista está caído.
Segunda llamada contraintuitiva: los clientes pueden vivir con un seguimiento que retrasa 30 minutos. No pueden vivir con un «entregado» erróneo. La actualidad es un extra agradable; la precisión es cuestión de vida o muerte. Gasta tu presupuesto y tu energía primero en el mapeo y las alertas, y después habla de tiempo real.
Errores cinco y seis: «entregado» no es prueba, y necesitas un simulacro de fallo
«Entregado» es lo que dice el transportista, no lo que dice el cliente. La conciliación es tu última línea de defensa:
- Concilia semanalmente: para los envíos marcados como entregados, revisa aleatoriamente los registros de prueba de entrega o las confirmaciones de los clientes.
- Los pedidos de alto valor requieren que se devuelva el POD, no solo un código de estado. Pon tu propio umbral — por ejemplo, envíos de más de $500.
- Si un cliente reporta no haber recibido dentro de las 48 horas posteriores a un estado «entregado» → márcalo automáticamente como excepción y activa el flujo de soporte. No esperes a que vengan a buscarte.
Lista de verificación de la noche del go-live (imprímela, marca cada casilla):
- El receptor de callbacks tiene verificación de firma, idempotencia y almacenamiento del payload en bruto
- Trabajo de polling de respaldo configurado — relleno automático para envíos sin actualización en 24 horas
- La tabla de mapeo de estados cubre todos los transportistas integrados; el modo sombra corrió durante dos semanas
- «Entregado a agente» y «entrega fallida» son sus propios estados, no plegados dentro de «entregado»
- Caché activa: envíos entregados cacheados 7 días, en tránsito cacheados 15–30 minutos
- Alertas de tres niveles configuradas y probadas: sin actualización en más de 24h, regresión de estado, fallos consecutivos de la API
- Simulacro de fallo hecho: se cortó el webhook para verificar que el polling de respaldo se pone al día; se simuló limitación para verificar degradación elegante en lugar de una caída
- Conciliación programada; pipeline de retorno de POD funcionando para pedidos de alto valor
Un último consejo: integración completada no es el final. Los transportistas cambian los códigos de estado, ajustan los límites de consultas y sus servicios de envío se caen. La tabla de mapeo y las alertas son los activos de largo plazo. El código de integración es solo consumible.
Por Lin Xiao, consultor de implementación de WMS Traducido del inglés. En caso de discrepancia, prevalece la versión en inglés.
