Rastreo de Envíos

Consulte el estado actual y el historial de eventos de cada envío generado en ALTUM ERP. El sistema actualiza la información de rastreo de forma automática mediante un mecanismo de polling y también acepta notificaciones en tiempo real vía webhook desde los carriers.

Requisitos y permisos

Permiso requerido	Descripción
`paqueteria.dashboard_ver`	Permite ver la lista de envíos y el dashboard de KPIs
`paqueteria.envios_ver`	Permite ver el detalle y el timeline de eventos de un envío

Pantalla principal: lista de envíos

Acceda al módulo Paquetería desde el menú lateral. La pantalla principal muestra:

KPIs del mes actual: métricas del periodo en curso (envíos totales, entregados, en tránsito, con excepción).
Tabla de envíos: listado paginado (20 registros por página) con los envíos del tenant, ordenados por fecha de creación descendente.

Pantalla principal de paquetería con KPIs y tabla de envíos

Columnas de la tabla:

Columna	Descripción
Número de rastreo	Número asignado por el carrier, o el folio interno si aún no se generó
Carrier	DHL, FedEx, Estafeta o 99minutos
Estado	Estado actual del envío (ver tabla de estados más abajo)
Costo (MXN)	Costo del envío en pesos mexicanos
Fecha de creación	Fecha y hora de creación del registro
Destino	Municipio y estado del destinatario

La paginación es secuencial hacia adelante (cursor-forward). Use los controles de navegación en la parte inferior de la tabla para avanzar o retroceder páginas.

Estados de un envío

Estado	Descripción
`COTIZADO`	Tarifa seleccionada; guía aún no generada con el carrier
`GENERADO`	Guía generada; número de rastreo y etiqueta disponibles
`GENERADO_PARCIAL`	Consolidación parcialmente generada
`RECOGIDO`	El carrier recogió el paquete en origen
`EN_TRANSITO`	El paquete está en tránsito entre instalaciones del carrier
`EN_REPARTO`	El paquete está en reparto final hacia el destinatario
`EN_TRANSITO_EXCEPCION`	Ocurrió una excepción durante el tránsito (retraso, dirección incorrecta, etc.)
`ENTREGADO`	El paquete fue entregado al destinatario (estado terminal)
`CANCELACION_SOLICITADA`	Se solicitó la cancelación al carrier
`CANCELADO`	El envío fue cancelado exitosamente (estado terminal)
`CANCELACION_RECHAZADA`	El carrier rechazó la cancelación (estado terminal)
`ERROR`	El envío entró en un estado de error no recuperable

Los estados terminales (ENTREGADO, CANCELADO, CANCELACION_RECHAZADA) no admiten más transiciones. El sistema detiene automáticamente el polling para estos envíos.

Detalle de un envío

Haga clic en cualquier fila de la tabla para abrir la pantalla de detalle.

La pantalla de detalle presenta:

Encabezado: número de rastreo (o folio interno), con botones de acción contextuales.
Tarjeta de detalle (dos tercios de la pantalla): información completa del envío — carrier, estado, direcciones de origen y destino, dimensiones, costo y fechas.
Timeline de eventos (un tercio de la pantalla): historial cronológico de todos los eventos de tracking recibidos.

Timeline de eventos

El timeline muestra cada evento registrado con:

Descripción del evento (normalizada por ALTUM ERP desde los códigos del carrier)
Ubicación geográfica reportada por el carrier (cuando está disponible)
Fecha y hora del evento según el carrier
Estado ERP al que mapeó el evento

Los eventos pueden llegar al sistema de dos formas:

Polling automático: el sistema consulta periódicamente al carrier los eventos nuevos de los envíos activos (hasta 50 envíos por ciclo). Solo se procesan envíos con pollingActivo = true y que tengan número de rastreo asignado.
Webhook del carrier: notificaciones push enviadas directamente por el carrier cuando ocurre un evento. DHL utiliza este mecanismo y valida cada notificación mediante firma HMAC.

Actualización manual de tracking

Si desea forzar una actualización inmediata del estado de rastreo sin esperar al siguiente ciclo de polling:

Abra el detalle del envío.
Si el envío tiene pollingActivo = true, aparece el botón Reintentar tracking.
Haga clic en el botón. El sistema solicita al backend un nuevo ciclo de polling para ese envío específico.

Reglas y validaciones

Polling activo por defecto: los envíos recién generados tienen pollingActivo = true. El sistema desactiva el polling automáticamente al alcanzar un estado terminal.
Sin duplicado de eventos: el sistema procesa cada evento del carrier una sola vez. Si el carrier re-envía un evento ya registrado (mismo código + timestamp), se ignora.
Firma HMAC para DHL: el backend valida la firma de cada notificación webhook de DHL usando el webhookSecret configurado. Notificaciones con firma inválida son rechazadas con error de autenticación y no se persisten.
Timeout de 10 s por carrier: cada llamada de polling al carrier tiene un tiempo máximo de 10 segundos. Si el carrier no responde, el error se registra en los logs pero no afecta al polling de otros envíos en el mismo ciclo.

Casos frecuentes

El estado del envío no ha cambiado en mucho tiempo. Verifique que el envío tenga número de rastreo (estado GENERADO o posterior). Si el estado es COTIZADO, la guía aún no fue generada con el carrier y no hay eventos que rastrear. Si el envío ya tiene número de rastreo, use el botón Reintentar tracking para solicitar una actualización inmediata.

El timeline de eventos está vacío aunque el envío ya fue generado. Es normal durante las primeras horas después de generar la guía: el carrier puede tardar en registrar los primeros eventos. El polling lo detectará cuando el carrier los publique.

Aparece el estado EN_TRANSITO_EXCEPCION. El carrier reportó una excepción (dirección no encontrada, paquete dañado, intento fallido de entrega, etc.). El campo Observaciones en la tarjeta de detalle contiene el motivo específico. Contacte al carrier con el número de rastreo para resolver la situación.

¿Con qué frecuencia se actualiza el tracking automáticamente? El intervalo de polling es configurable en el backend. El sistema procesa hasta 50 envíos activos por ciclo. Los envíos con carriers que usan webhooks (como DHL) reciben actualizaciones en tiempo real independientemente del ciclo de polling.