Manual de Usuario — SAP Shipping Tracker
Sistema automatizado de rastreo de envíos y actualización en SAP Business One
Versión 1.0 — Febrero 2026
1. Descripción General
El SAP Shipping Tracker es un sistema integral diseñado para automatizar el rastreo de envíos y la actualización de entregas en SAP Business One. Combina web scraping con inteligencia artificial (Google Gemini) para capturar y analizar el estado de las guías de paquetería de forma completamente automatizada.
¿Qué hace el sistema?
| Función | Descripción |
|---|---|
| ? Rastreo Automático | Monitorea automáticamente el estado de las guías de envío en las páginas web de las paqueterías |
| ? Análisis con IA | Utiliza Google Gemini AI para interpretar capturas de pantalla de las páginas de rastreo y extraer información clave |
| ? Dashboard en Tiempo Real | Panel operativo con métricas, desglose por estatus y actividad del bot de rastreo |
| ? Notificaciones Inteligentes | Envía alertas automáticas por email cuando hay cambios de estatus, excepciones o entregas completadas |
| ? Carga Masiva | Permite asignar números de guía a múltiples entregas simultáneamente mediante archivos Excel |
| ⚙️ Configuración Dinámica | Toda la configuración del sistema es modificable en tiempo real desde la interfaz web |
Ubicación: https://saptracker.twparts.mx
2. Acceso al Sistema
Para acceder al sistema, navegue a la URL de la aplicación. Se le presentará la pantalla de inicio de sesión donde deberá ingresar sus credenciales.
2.1 Tipos de Autenticación
| Tipo | Descripción |
|---|---|
| Usuario Local | Cuentas creadas directamente en el sistema por un administrador. Las credenciales se almacenan de forma segura en la base de datos. |
| Usuario SAP | Credenciales validadas directamente contra SAP Business One Service Layer. Los usuarios SAP se registran automáticamente en su primer ingreso exitoso. |
2.2 Pasos para Iniciar Sesión
- Abra su navegador web y navegue a https://saptracker.twparts.mx
- En el campo “Usuario”, ingrese su nombre de usuario.
- En el campo “Contraseña”, ingrese su contraseña.
- Haga clic en el botón “Ingresar”.
- Si las credenciales son correctas, será redirigido al Dashboard principal.
3. Dashboard Principal
El Dashboard es la página principal del sistema. Muestra un resumen operativo en tiempo real con datos directos de SAP Business One, diseñado para proporcionar una visión rápida y completa del estado de las entregas.
3.1 Tarjetas de Métricas
En la parte superior del dashboard se muestran cuatro tarjetas principales:
| Tarjeta | Descripción | Color |
|---|---|---|
| Total Entregas | Cantidad total de entregas en el período configurado (últimos N meses) | Gris |
| Sin Guía Asignada | Entregas que aún no tienen número de guía de paquetería | Rojo/Naranja |
| Pendientes de Arribo | Entregas con guía asignada pero sin confirmación de recepción. Muestra desglose: Con guía / Sin guía | Amarillo |
| Completadas | Entregas finalizadas con éxito (confirmadas como entregadas) | Verde |
3.2 Filtros por Origen
En la esquina superior derecha del dashboard encontrará tres botones de filtro:
- Todos: Muestra todas las entregas sin filtro de origen.
- Nacional: Filtra solo entregas nacionales (envíos dentro del país).
- Exportación: Filtra entregas de exportación (envíos internacionales).
3.3 Desglose por Estatus
Debajo de las tarjetas principales se muestra un desglose visual de los diferentes estatus de rastreo:
| Estatus | Código | Descripción |
|---|---|---|
| Recolección | RE | La paquetería ha recolectado el paquete |
| En Tránsito | TR | El paquete está siendo transportado |
| Excepción | EX | Se detectó un problema con el envío |
| Entregado | EN | El paquete fue entregado exitosamente |
| Sucursal Destino | SD | El paquete llegó a la sucursal de destino |
| En Reparto | RP | El paquete está en proceso de entrega final |
3.4 Actividad del Bot (Hoy)
En la esquina inferior derecha se muestra la actividad del agente de rastreo automático del día actual:
- Procesadas: Total de entregas que el bot ha intentado procesar hoy.
- Exitosas: Entregas procesadas correctamente (se pudo obtener el estatus).
- Errores: Entregas donde ocurrió un error al consultar la paquetería.
- En Cola: Entregas pendientes de ser procesadas en el próximo ciclo.
4. Monitor de Entregas SAP
La sección de Entregas proporciona un listado completo y detallado de todas las entregas registradas en SAP. Desde aquí puede consultar el estado operativo de cada envío en tiempo real, aplicar filtros y exportar datos.
4.1 Filtros Disponibles
| Filtro | Descripción |
|---|---|
| Estado | Filtrar por estado de tracking: Todos, En Tránsito, Entregado, Excepción, Sin datos, etc. |
| Paquetería | Filtrar por proveedor de paquetería: DHL, FedEx, Estafeta, Paquete Express, etc. |
| Búsqueda | Campo de texto para buscar por número de guía, nombre de cliente o número de documento |
4.2 Columnas de la Tabla
| Columna | Descripción |
|---|---|
| F. DOC. | Fecha del documento en SAP |
| F. EMB. | Fecha de embarque programada |
| F. ARR. | Fecha de arribo confirmada (si aplica) |
| SAP# / ORG. | Número de documento SAP y origen (NAC=Nacional, EXP=Exportación) |
| CLIENTE | Código y nombre del cliente |
| PAQUETERÍA | Nombre de la paquetería asignada |
| F. PAGO ENVÍO | Forma de pago del envío (campo U_FEnvio de SAP). Ej: Pagado, Por Cobrar, etc. |
| GUÍA / STATUS | Número de guía de rastreo y estatus actual |
| RECIBIÓ | Nombre de la persona que recibió el paquete |
| COSTO | Costo de envío |
| TRÁNS. | Días en tránsito |
| INCIDENCIA | Botón para generar una incidencia directamente desde la entrega |
4.3 Exportar a Excel
En la esquina superior derecha se encuentra el botón “Excel” que permite exportar la tabla de entregas a un archivo Excel (.xlsx) con todos los datos y filtros aplicados.
5. Gestión de Incidencias
El módulo de Incidencias permite crear, dar seguimiento y resolver problemas relacionados con las entregas. Es una herramienta visual con contadores por estatus, filtros avanzados y la posibilidad de adjuntar fotografías.
5.1 Contadores de Estado
En la parte superior se muestran contadores de incidencias agrupados por estatus:
| Estado | Descripción |
|---|---|
| Abiertas | Incidencias recién creadas, pendientes de revisión inicial |
| Pendientes | Incidencias asignadas, en espera de que alguien tome acción |
| En Curso | Incidencias que están siendo atendidas activamente |
| Resueltas | Incidencias con solución aplicada, pendientes de cierre formal |
| Cerradas | Incidencias completamente cerradas y archivadas |
5.2 Crear una Incidencia
Existen dos formas de crear una nueva incidencia:
- Desde la tabla de Entregas: Haga clic en el botón “Generar Incidencia” (⚠️) en la columna de acciones de cualquier entrega.
- Desde el módulo de Incidencias: Si su rol lo permite, podrá crear incidencias directamente desde este módulo.
Al crear una incidencia se pueden especificar:
- Tipo de incidencia (daño, retraso, pérdida, etc.)
- Prioridad (baja, media, alta, urgente)
- Descripción detallada del problema
- Fotografías de evidencia (hasta 20 fotos por incidencia)
5.3 Dar Seguimiento
Cada incidencia cuenta con un historial de notas de seguimiento. Los usuarios autorizados (administrador y logística) pueden cambiar el estatus de una incidencia y agregar notas o fotos adicionales en cualquier momento.
6. Carga Masiva de Guías
La Carga Masiva permite asignar números de guía de paquetería a múltiples entregas simultáneamente utilizando un archivo Excel. Esto agiliza significativamente el proceso cuando se tienen muchas entregas pendientes.
6.1 Descarga de Plantillas
En la parte inferior de la pantalla encontrará dos opciones de plantilla:
| Plantilla | Descripción |
|---|---|
| Plantilla en Blanco | Archivo Excel vacío con las columnas requeridas para llenado manual |
| Plantilla con Pendientes | Archivo pre-llenado con las entregas de los últimos 30 días sin guía asignada. Solo necesitará completar paquetería, número de guía y forma de envío |
El archivo Excel contiene las siguientes hojas:
- Datos: Hoja principal donde se llenan los datos de las entregas.
- Instrucciones: Guía rápida de cómo llenar la plantilla.
- Paqueterías: Catálogo de paqueterías válidas en SAP con sus códigos.
- FormasEnvio: Catálogo de formas de pago de envío válidas (Pagado, Por Cobrar, etc.).
6.2 Columnas de la Plantilla Excel
| Columna | Obligatoria | Descripción |
|---|---|---|
| DocNum | Sí | Número de documento de entrega en SAP |
| TrackingNumber | Sí | Número de guía de la paquetería |
| TransportationCode | Sí | Código de paquetería (ej: 1 - PAQUETE EXPRESS). Consulte la hoja Paqueterías |
| FormaEnvio | Sí | Forma de pago del envío (ej: 3 - Pagado). Consulte la hoja FormasEnvio |
| FechaEmbarque | No | Fecha de embarque (formato YYYY-MM-DD) |
| CostoFlete | No | Costo del flete/envío |
| FechaArribo | No | Fecha de arribo (si ya se conoce) |
| QuienRecibio | No | Nombre de quien recibió (si aplica) |
| EstatusGuia | No* | Estatus de la guía. *Obligatorio para paqueterías no soportadas |
| Cliente | No | Nombre del cliente (referencia, no se actualiza en SAP) |
6.3 Carga con Paquetería Soportada (rastreo automático)
Al usar una paquetería soportada por el agente de rastreo automático (ej: Paquete Express, DHL, FedEx, Estafeta), el sistema rastreará automáticamente el estatus de la guía después de la carga.
- Preparar el archivo Excel: Descargue la plantilla y complete los campos obligatorios (DocNum, TrackingNumber, TransportationCode, FormaEnvio).
- Subir el archivo: En la sección de Carga Masiva, haga clic en el área de carga o arrastre su archivo Excel.
- Validar: El sistema valida cada DocNum contra SAP. Las filas válidas muestran ✅ OK.
- Revisar y editar: Los campos Paquetería, F. Envío, Costo, F. Arribo, Recibió y Estatus son editables directamente en la tabla de validación.
- Ejecutar: Haga clic en “Ejecutar Carga”. El sistema muestra resumen: Total Procesadas, Exitosas (✅) y Fallidas (❌).
- Verificar: Confirme en el Dashboard que las entregas aparecen con guía asignada.
6.4 Carga con Paquetería No Soportada (estatus manual)
Cuando la paquetería utilizada NO está soportada por el agente de rastreo automático (por ejemplo, LOGISTICA FDR), el usuario debe ingresar manualmente el estatus de cada guía.
- Preparar el Excel con estatus manual: Además de los campos obligatorios estándar, llene la columna “EstatusGuia” con el código correspondiente (TR, EN, EX, etc.). Una misma guía puede asociarse a múltiples entregas si hay envíos consolidados.
- Subir y validar: Las filas se muestran con estado ⚠️ Warning (amarillo), indicando que la paquetería no está soportada. La carga puede continuar normalmente.
- Ejecutar carga: El sistema muestra barra de progreso durante el procesamiento.
- Verificar resultados: Revise el resumen de resultados y confirme en SAP que los campos fueron actualizados.
Campos actualizados en SAP tras la carga: Paquetería, # GUÍA, Forma de pago de envío, Costo del flete, Fecha de embarque y Estatus guía de paquetería.
7. Administración de Usuarios
La sección de Usuarios permite a los administradores gestionar las cuentas de acceso al sistema.
7.1 Información de la Tabla
| Columna | Descripción |
|---|---|
| Usuario | Nombre de usuario para iniciar sesión |
| Nombre | Nombre completo del usuario |
| Rol | Rol asignado (Administrador, Logística, Almacén, Vendedor, Soporte Ventas) |
| Afinidad Ext/Nac | Tipo de asignación: Global (ve todo), Nacional o Exportación |
| Fuente | Origen de la cuenta: Local (creada manualmente) o SAP (autenticada contra SAP) |
| Estado | Estado de la cuenta: Activo o Inactivo |
| Creado | Fecha de creación de la cuenta |
| Acciones | Botones para Editar (✏️), Cambiar Contraseña (?) y Eliminar (?️) |
7.2 Crear Nuevo Usuario
Para crear un nuevo usuario local, haga clic en el botón “+ Nuevo Usuario Local” ubicado en la esquina superior derecha. Complete los campos requeridos: nombre de usuario (único), nombre completo, contraseña y rol a asignar.
8. Configuración del Sistema
La página de Configuración permite ajustar los parámetros operativos del sistema de forma dinámica. Los cambios se aplican en tiempo real sin necesidad de reiniciar.
8.1 Pestaña General
| Sección | Parámetros |
|---|---|
| ? Dashboard Operativo | Historial de Entregas (Días): define cuántos días buscar entregas para el dashboard (Default: 90) |
| ⚠️ Incidencias | Máximo de Fotos por Incidencia (Default: 20) |
| ? Agente de Rastreo | Estado del agente (activo/inactivo) e intervalo de ejecución en minutos (Mínimo: 1 min) |
8.2 Pestaña Paqueterías
Gestión de los proveedores de paquetería configurados en el sistema: habilitar/deshabilitar paqueterías, agregar nuevas y utilizar la función de Auto-Descubrimiento con IA (Gemini + Playwright) para sugerir configuraciones de rastreo.
8.3 Configuraciones Adicionales
| Sección | Descripción |
|---|---|
| ? Reporte Diario | Hora y minuto de envío del reporte gerencial diario |
| ? Destinatarios de Email | Lista de correos que reciben el reporte diario |
| ? Excepciones Nac/Exp | Correos específicos para alertas de excepciones nacionales vs. internacionales |
| ? Alertas de Status | Configuración de notificaciones automáticas a clientes por cambio de estatus |
| ?️ Logo del Sistema | URL del logo personalizado que aparece en los correos de notificación |
| ? Modo Debug | Activa logs detallados para diagnóstico técnico |
9. Estado del Sistema
Muestra la conectividad y salud de todos los servicios que componen la plataforma. Es útil para diagnosticar problemas de conexión o verificar que todos los componentes están operativos.
| Servicio | Descripción |
|---|---|
| Backend API | Estado del servidor de la API REST (FastAPI) |
| MongoDB | Conexión a la base de datos MongoDB |
| SAP Service Layer | Conectividad con el ERP SAP Business One |
| Frontend | Estado de la aplicación web React |
Cada servicio muestra un indicador visual de estado (verde = operativo, rojo = con problemas). Haga clic en “Actualizar” para refrescar el estado.
10. Roles y Permisos
El sistema implementa un control de acceso basado en roles (RBAC). Cada usuario tiene un rol asignado que determina qué secciones puede ver y qué acciones puede realizar.
10.1 Roles Disponibles
| Rol | Acceso | Restricciones |
|---|---|---|
| Administrador | Acceso total a todas las secciones | Sin restricciones |
| Logística | Dashboard, Entregas, Incidencias, Carga Masiva, Estado del Sistema | No puede administrar usuarios ni configuración |
| Soporte Ventas | Visualización de todos los registros | Sin columnas de Proveedor, Costos ni Aduana |
| Almacén | Dashboard, Entregas, Incidencias, Estado del Sistema | Solo lectura |
| Vendedor | Dashboard, Entregas (filtradas) | Solo ve sus propias entregas asignadas |
10.2 Matriz de Acceso por Sección
| Sección | Admin | Logística | Sop. Ventas | Almacén | Vendedor |
|---|---|---|---|---|---|
| Dashboard | ✅ | ✅ | ✅ | ✅ | ✅ |
| Entregas | ✅ | ✅ | ✅* | ✅ | ✅** |
| Incidencias | ✅ | ✅ | ✅ | ✅ | ❌ |
| Carga Masiva | ✅ | ✅ | ❌ | ❌ | ❌ |
| Usuarios | ✅ | ❌ | ❌ | ❌ | ❌ |
| Paqueterías | ✅ | ❌ | ❌ | ❌ | ❌ |
| Configuración | ✅ | ❌ | ❌ | ❌ | ❌ |
| Estado Sistema | ✅ | ✅ | ✅ | ✅ | ❌ |
* Columnas limitadas (sin Proveedor, Costos, Aduana) ** Solo ve sus propias entregas
11. Notificaciones por Email
El sistema envía notificaciones automáticas por correo electrónico utilizando plantillas HTML profesionales compatibles con todos los clientes de correo y con soporte nativo para modo oscuro.
11.1 Tipos de Notificaciones
| Tipo | Cuándo se envía | Destinatarios |
|---|---|---|
| Actualización de Estatus | Cuando el bot detecta un cambio de estatus real en una guía | Cliente y Vendedor asignado |
| Excepción de Envío | Cuando la guía tiene estatus de excepción (EX) | Lista de excepciones (Nacional o Exportación) |
| Error de Rastreo | Cuando hay un error al consultar la paquetería | Lista de excepciones |
| Error SAP | Cuando hay un error grave al actualizar SAP | Lista de excepciones |
| Paquetería Deshabilitada | Cuando una paquetería se desactiva automáticamente | Ambas listas de excepciones |
| Reporte Gerencial Diario | A la hora configurada cada día | Todos los destinatarios configurados |
11.2 Reporte Gerencial Diario
El reporte diario incluye:
- Total de entregas y completadas (contexto general)
- Sin Guía Asignada con desglose ?? Nacionales / ? Extranjeros
- Pendientes de Arribo con desglose ?? Nacionales / ? Extranjeros
- Enlace a Google Sheets (si está configurado)
12. Preguntas Frecuentes
❓ ¿Cada cuánto se actualiza la información del dashboard?
El dashboard se refresca automáticamente cada 5 minutos con datos directos de SAP. También puede refrescar manualmente recargando la página.
❓ ¿Cómo sé si mi guía ya fue rastreada?
En la tabla de Entregas, la columna GUÍA/STATUS muestra el estatus actual. Verde con “EN” = entregada. Azul con “TR” = en tránsito.
❓ ¿Qué hago si una paquetería no aparece en el sistema?
Contacte al administrador para que la agregue desde Configuración › Paqueterías. El sistema cuenta con Auto-Descubrimiento con IA para facilitar la configuración.
❓ ¿Puedo ver el historial de rastreo de una guía específica?
Sí, en la sección de Entregas puede buscar por número de guía. Al hacer clic podrá ver su historial completo de procesamiento.
❓ ¿Qué significa el estatus “Excepción”?
Indica que la paquetería reportó un problema con el envío (dirección incorrecta, intento fallido, paquete retenido, etc.). El sistema envía una notificación automática cuando detecta esta situación.
❓ ¿Cómo cambio mi contraseña?
Contacte al administrador del sistema quien podrá actualizar su contraseña desde la sección de Usuarios.
❓ ¿Qué navegadores son compatibles?
Google Chrome, Mozilla Firefox, Microsoft Edge y Safari. Se recomienda Google Chrome para la mejor experiencia.
❓ ¿Puedo usar la aplicación desde mi celular?
Sí, la interfaz es responsiva y se adapta a dispositivos móviles. Sin embargo, para una experiencia óptima se recomienda una computadora de escritorio.
Logística — SAP Shipping Tracker v1.0 — Febrero 2026
© TW Parts — Todos los derechos reservados