Mapas de calor

Visualiza en un mapa interactivo la ubicación de tus vendedores, puntos de venta pendientes y visitados, zonas comerciales y mapas de calor basados en oportunidades

Desde Maps Vendedores puedes visualizar en tiempo real la ubicación de tus vendedores sobre un mapa interactivo de Google Maps. El módulo muestra puntos de venta pendientes y visitados, zonas comerciales como polígonos y un mapa de calor (heatmap) que representa la concentración de oportunidades comerciales en el territorio.

Esta vista se encuentra en la ruta Inicio > Comercial > Maps Vendedores dentro del sistema. El módulo requiere que el navegador tenga habilitada la geolocalización para funcionar correctamente.

Requisitos previos

Antes de utilizar este módulo, asegúrate de cumplir con los siguientes requisitos:

Requisito	Detalle
Geolocalización del navegador	Debe estar habilitada. Si está deshabilitada, el sistema muestra un error y el mapa no se carga
Parámetro de configuración	El dominio `PARAMS-ERPX-COMERCIAL-DASHBOARD` debe tener configurado el valor con los IDs de colaboradores a monitorear
Conexión a internet	Se requiere conexión activa para cargar los tiles de Google Maps y la API de visualización
Permisos de acceso	El usuario debe tener un perfil con acceso al módulo de analíticas comerciales

Si la geolocalización no está habilitada en el navegador, el sistema muestra una notificación de error con el mensaje: "POR FAVOR HABILITE LA LOCALIZACIÓN" (duración: 5 segundos). El mapa no se renderiza y se queda mostrando el spinner de carga indefinidamente.

Cabecera de la página

La parte superior de la vista muestra:

El breadcrumb muestra la ruta de acceso con tres niveles:

Nivel	Texto	Acción al hacer clic
1	Inicio	Redirige a la URL raíz (`/`)
2	Comercial	Redirige a `/comercial`
3	Maps Vendedores	Sin acción (página actual)

Título y descripción

Título: Maps Vendedores
Descripción: "Muestra el listado y las herramientas para gestionar los maps de vendedores"

Debajo del título se muestra un separador horizontal (p-divider).

Pantalla de carga

Mientras el mapa se inicializa (antes de obtener la geolocalización y cargar los datos), el sistema muestra una pantalla de carga que cubre toda el área del mapa:

Fondo: gris claro (rgb(210, 210, 210))
Indicador: spinner de progreso (p-progressSpinner) centrado vertical y horizontalmente
Z-index: 1000 (se superpone a todo el contenido)
Altura: calc(100vh - 74.6px) — ocupa toda la altura visible menos la cabecera

La pantalla de carga desaparece cuando:

Se obtiene la posición del usuario exitosamente.
Se completa la carga de datos de oportunidades desde el DWH.
Se renderizan los datos en el mapa.

Mapa interactivo

El componente principal es un mapa de Google Maps que ocupa todo el ancho de la pantalla y una altura de calc(100vh - 74.6px).

Configuración inicial del mapa

Propiedad	Valor
Centro	Coordenadas de geolocalización del usuario actual
Zoom	`15`
Control de zoom	Habilitado
Control de tipo de mapa	Deshabilitado
Control de Street View	Deshabilitado
Control de pantalla completa	Deshabilitado

Marcador de ubicación del usuario

Al inicializar el mapa, se coloca un marcador en la posición actual del usuario:

Propiedad	Valor
Título	`YO`
Etiqueta	Texto `YO` en color blanco (`#ffffff`)
Ícono	`./assets/map_icon_mi.png`
Clickeable	No (`clickable: false`)

La posición del marcador "YO" se actualiza automáticamente cada 1 segundo mediante setInterval. Esto permite rastrear el movimiento del usuario en tiempo real. Se utiliza watchPosition con alta precisión (enableHighAccuracy: true).

Panel de leyenda (controles)

A la derecha del mapa se muestra un panel de leyenda flotante con los controles de filtrado. Este panel solo es visible cuando el mapa ha terminado de cargar (displayMaximizableMap = true).

Estilos del panel

Propiedad	Valor
Fondo	Blanco (`#fff`)
Borde	Radio de `3px`
Sombra	`0 1px 2px rgba(0, 0, 0, 0.1)`
Padding	`10px`
Posición	Absoluta, `top: 60px`
Ancho	`360px`
Z-index	`1000`

Filtro de fecha

Campo	Tipo	Valor por defecto	Descripción
Fecha	`input[type="date"]` con `pInputText`	Fecha actual (zona horaria `America/Lima`)	Al cambiar la fecha, el sistema recarga automáticamente todos los datos del mapa

La fecha se inicializa con la zona horaria de América/Lima utilizando moment-timezone. Todos los cálculos de rango de fecha para la consulta al DWH se realizan en esta zona horaria.

Al cambiar la fecha:

Se eliminan todos los polígonos de zonas existentes del mapa.
Se limpian los arrays de puntos pendientes y visitados.
Se ejecuta una nueva consulta al DWH con el rango del día seleccionado (desde 00:00:00 hasta 23:59:59).
Se reconstruyen los marcadores, polígonos y mapa de calor.

Checkboxes de visualización

El panel ofrece tres checkboxes binarios (p-checkbox con [binary]="true") para controlar qué capas se muestran en el mapa:

Checkbox	ID	Valor inicial	Descripción
Zonas	`zonas`	Desactivado (`false`)	Muestra/oculta los polígonos de zonas comerciales en el mapa
P. Pendientes	`puntos_ventas_pendientes`	Desactivado (`false`)	Incluye los puntos de venta pendientes de visita en el mapa de calor
P. Visitados	`puntos_ventas_visitados`	Desactivado (`false`)	Incluye los puntos de venta ya visitados en el mapa de calor

Los checkboxes P. Pendientes y P. Visitados solo afectan al mapa de calor cuando hay al menos un vendedor activado (con show: true). Si ningún vendedor está activado, activar estos checkboxes no mostrará puntos en el mapa de calor.

Al activar o desactivar P. Pendientes o P. Visitados, el sistema reconstruye el mapa de calor (setDataMap()), recalculando los puntos que deben incluirse según los vendedores activos y los tipos de punto seleccionados.

Lista de vendedores

Debajo de los checkboxes se muestra la sección Vendedores con un encabezado <h4>.

La lista muestra todos los colaboradores obtenidos del parámetro PARAMS-ERPX-COMERCIAL-DASHBOARD. Cada vendedor se muestra como un elemento clickeable con:

Elemento	Descripción
Indicador de color	Círculo de `10px × 10px` con borde redondeado (`border-radius: 50%`) y color de fondo asignado
Nombre completo	Formato: `\{apellido_paterno\} \{apellido_materno\} \{nombres\}`

Colores asignados a vendedores

Los colores se asignan en orden según la posición del vendedor en la lista. Si hay más vendedores que colores disponibles (8), los vendedores adicionales reciben un color por defecto.

Posición	Color de fondo	Color de texto
1	`#ff0000` (rojo)	`#ffffff`
2	`#00ff00` (verde)	`#000000`
3	`#0000ff` (azul)	`#ffffff`
4	`#00ffff` (cian)	`#000000`
5	`#ff00ff` (magenta)	`#ffffff`
6	`#ffff00` (amarillo)	`#000000`
7	`#023535` (verde oscuro)	`#ffffff`
8	`#ef6024` (naranja)	`#ffffff`

Comportamiento al hacer clic en un vendedor

Al hacer clic en un vendedor se alterna su estado de visibilidad (show):

Vendedor activado (show: true): El nombre se muestra con estilo normal. Sus puntos de venta (pendientes y/o visitados, según los checkboxes activos) se incluyen en el mapa de calor.
Vendedor desactivado (show: false): El nombre se muestra con texto tachado y color rojo (text-decoration: line-through; color: red). Sus puntos se excluyen del mapa de calor.

Por defecto, todos los vendedores inician desactivados (show: false). Para ver datos en el mapa de calor, debes activar al menos un vendedor haciendo clic en su nombre y activar al menos uno de los checkboxes P. Pendientes o P. Visitados.

Flujo de datos

El módulo sigue el siguiente flujo al inicializarse:

Obtener geolocalización

El sistema solicita la posición del navegador con alta precisión (enableHighAccuracy: true). Si es exitoso, centra el mapa en la ubicación del usuario y coloca el marcador "YO". Si falla, muestra el error de localización.

Cargar parámetros de configuración

Se consulta el endpoint de parámetros buscando el dominio PARAMS-ERPX-COMERCIAL-DASHBOARD. El valor de este parámetro contiene los IDs de los colaboradores (vendedores) a monitorear.

Obtener lista de colaboradores

Con los IDs obtenidos del parámetro, se consulta el endpoint de colaboradores para obtener los datos completos de cada vendedor (nombre, apellidos). Se asigna un color de la paleta a cada vendedor según su posición.

Consultar oportunidades del DWH

Se ejecuta una búsqueda en el Data Warehouse (DWH) con los siguientes criterios:

Rango de fecha: Día seleccionado completo (00:00:00 a 23:59:59)
Tipo: 3
Indicador código: OPORTUNIDAD
Vendedor ID: Lista de todos los IDs de vendedores separados por coma
Tamaño máximo: 1,000,000,000 registros

Procesar y renderizar datos

Los datos de oportunidades se procesan para cada vendedor:

Se filtran las oportunidades por vendedor_id.
Se ordenan por oportunidad.orden (ascendente).
Cada oportunidad se clasifica:
- Si oportunidad.visita_fecha == null → Punto pendiente
- Si oportunidad.visita_fecha != null → Punto visitado
Se extraen las coordenadas del punto de venta (cliente_punto_venta.latitud, cliente_punto_venta.longitud).
Si la oportunidad tiene una zona con map_location, se extraen las coordenadas del polígono.

Capas del mapa

Mapa de calor (HeatmapLayer)

El mapa de calor utiliza la API de visualización de Google Maps (google.maps.visualization.HeatmapLayer) para representar la densidad de puntos de venta.

Propiedad	Valor
Radio	`20` píxeles
Opacidad	`1` (completamente opaco)
Datos	Coordenadas `LatLng` de los puntos de venta filtrados

Los puntos incluidos en el mapa de calor dependen de:

Vendedores activados: Solo se incluyen puntos de vendedores cuyo estado show es true.
Tipo de punto: Se incluyen puntos pendientes si P. Pendientes está activado, y puntos visitados si P. Visitados está activado.

Cada vez que se cambia un filtro (vendedor, checkbox, o fecha), el mapa de calor se destruye y recrea completamente. El mapa de calor anterior se elimina con setMap(null) antes de crear uno nuevo.

Polígonos de zonas

Las zonas comerciales se representan como polígonos (google.maps.Polygon) sobre el mapa. Los polígonos se generan automáticamente a partir de la propiedad zona.map_location.coordenadas de cada oportunidad.

Cada coordenada del polígono tiene:

latitud → convertido a lat (float)
longitud → convertido a lng (float)

Los polígonos se muestran siempre que existan datos de zonas en las oportunidades. Al cambiar la fecha, todos los polígonos existentes se eliminan del mapa (setMap(null)) antes de crear los nuevos.

El checkbox Zonas del panel de leyenda controla la visibilidad general de las zonas, pero los polígonos se crean y renderizan como parte del flujo de datos al cargar las oportunidades.

Clasificación de puntos de venta

Las oportunidades del DWH se clasifican en dos categorías según el estado de la visita:

Categoría	Condición	Descripción
Pendientes	`oportunidad.visita_fecha == null`	El vendedor aún no ha visitado este punto de venta en la fecha seleccionada
Visitados	`oportunidad.visita_fecha != null`	El vendedor ya realizó la visita al punto de venta

Cada punto se almacena con las coordenadas del cliente/punto de venta:

Latitud: cliente_punto_venta.latitud
Longitud: cliente_punto_venta.longitud

Endpoints utilizados

El módulo consume los siguientes endpoints del servidor:

Endpoints principales

Endpoint	Método	Descripción
`v2.0.1/erpx/global/params`	GET	Obtiene los parámetros de configuración del dashboard comercial
`v2.0.3/erpx/rrhh/colaboradores`	GET	Obtiene los datos de los colaboradores/vendedores
`v2.0.1/erpx/analiticas/dwh`	GET	Consulta el Data Warehouse para obtener las oportunidades
`v2.0.1/erpx/crm/oportunidades`	GET	Gestión de oportunidades comerciales
`v2.0.1/erpx/global/zonas`	GET	Obtiene información de zonas geográficas

Endpoints adicionales disponibles

Endpoint	Método	Descripción
`v2.0.1/erpx/comercial/hojas-rutas`	GET	Consulta hojas de ruta de vendedores
`v2.0.2/erpx/comercial/clientes`	GET	Consulta de clientes
`v2.0.3/erpx/comercial/pedidos`	GET	Consulta de pedidos
`v2.0.1/erpx/comercial/configs-vendedores`	GET	Configuraciones de vendedores

Consulta DWH — Formato de búsqueda

La consulta al Data Warehouse se construye con el siguiente formato:

search=** AND fecha:[{fecha_inicio} TO {fecha_fin}] AND tipo:3 AND indicador_codigo:OPORTUNIDAD AND vendedor_id:{ids}

Donde:

\{fecha_inicio\}: Fecha del día seleccionado a las 00:00:00 en formato YYYYMMDDHHmm (ejemplo: 202403080000)
\{fecha_fin\}: Fecha del día seleccionado a las 23:59:59 en formato YYYYMMDDHHmm (ejemplo: 202403082359)
\{ids\}: IDs de vendedores separados por coma

Autenticación

Todas las peticiones al servidor incluyen las siguientes cabeceras:

Cabecera	Valor
`accept`	`application/json`
`Authorization`	`Bearer \{token\}`
`enterprise-id`	ID de la empresa del usuario autenticado

Manejo de errores

Código HTTP	Mensaje mostrado
`400`	Mensaje del primer error devuelto por el servidor (`error.error.errors[0]`)
`402`	Mensaje del primer error devuelto por el servidor (`error.error.errors[0]`)
`404`	"No se encontró el servidor de respuestas, consulte con el Administrador. ERROR 404"
`500`	"Error interno del servidor. ERROR 500"
Otro	"Error 404 consulte con su admin."

Problemas comunes

Problema	Causa	Solución
El mapa no carga y aparece un spinner indefinidamente	La geolocalización del navegador está deshabilitada	Habilita la geolocalización en la configuración del navegador y recarga la página
Aparece el error "POR FAVOR HABILITE LA LOCALIZACIÓN"	El navegador no tiene permiso para acceder a la ubicación	Permite el acceso a la ubicación en las preferencias del navegador
No se muestran puntos en el mapa de calor	Ningún vendedor está activado o ningún checkbox de tipo de punto está marcado	Haz clic en al menos un vendedor para activarlo y marca P. Pendientes o P. Visitados
No aparecen vendedores en el panel	El parámetro `PARAMS-ERPX-COMERCIAL-DASHBOARD` no tiene valores configurados	Solicita al administrador que configure los IDs de colaboradores en el parámetro
Los polígonos de zonas no se muestran	Las oportunidades no tienen datos de zona con `map_location` configurado	Verifica que las zonas comerciales tengan coordenadas de mapa configuradas en el módulo de zonas
La posición "YO" no se actualiza	Error de geolocalización durante la actualización	Verifica que la geolocalización siga habilitada y que la señal GPS sea estable
Se muestra el mapa pero sin datos	No hay oportunidades registradas para la fecha seleccionada	Cambia la fecha a un día con actividad comercial registrada
Los colores de vendedores se repiten	Hay más de 8 vendedores configurados	El sistema solo tiene 8 colores predefinidos; los vendedores adicionales pueden no tener un color distinguible

Páginas relacionadas

Métricas — Configuración de métricas de rendimiento con indicadores personalizados.
Métricas — Detalles — Visualización de gráficos y datos de métricas configuradas.