Gadget xPOS

📚 Presentación General

Bienvenido al Gadget xPOS, una plataforma integral que permite la administración centralizada, supervisión y configuración de todos los dispositivos xPOS implementados por tu organización. Esta herramienta está diseñada para brindar una experiencia amigable, con funcionalidades intuitivas que facilitan el seguimiento del estado operativo, gestión de los dispositivos, la visualización de logs y mucho más.

Este manual está pensado para que cualquier usuario, sin conocimientos técnicos avanzados, pueda navegar y aprovechar al máximo las funcionalidades del portal.

✅ Beneficios del Portal xPOS

• Visibilidad operativa centralizada y en tiempo real.
• Gestión remota de configuraciones críticas.
• Análisis técnico respaldado por datos.
• Cumplimiento normativo automatizado.
• Detección proactiva de errores y contingencias.

🏠 Sección de Inicio

📌 Descripción General

La página principal (Inicio) ofrece un resumen visual del estado actual de tu ecosistema xPOS:

• Indicadores clave de rendimiento: cantidad de documentos procesados durante el día bajo, con errores o en modalidad de contingencia.
• Panel de actividad de los últimos registros: muestra en un diagrama de barras que muestra la evolución de los documentos procesados, errores y respuestas ET/contingencias, con posibilidad de filtrar por semana, mes o año.
• Accesos directos a las secciones como Monitor, Logs y Configuraciones.
• Actualización de datos de forma automática cada 5 minutos.

✅ Recomendaciones de uso

• Revisar el panel al iniciar la jornada para verificar si hay errores o retrasos en el procesamiento de documentos.
• Si hay documentos erróneos, consultar la sección de Logs o contactar al equipo de soporte.
• Utilizar los filtros (semanal, mensual, anual) para hacer seguimiento de desempeño y volumen de documentos.

🏋️ Sección de Pool

📌 Descripción General

La sección "Pool" permite visualizar, administrar y configurar los distintos xPOS registrados en el sistema.

🔹 Descripción general de la vista

La tabla muestra un listado de todos los xPOS creados en el entorno, junto a información clave para su gestión.

📋 Columnas de la tabla

Columna	Descripción
ID xPOS	Identificador único del xPOS en formato UUID.
Nombre xPOS	Nombre asignado al dispositivo de punto de emisión.
Fecha de creación	Fecha y hora de creación del xPOS.
Umbral (Tipo DTE | Valor)	Tipos de documentos asignados al xPOS y el umbral de recarga configurado. * Campo disponible solo si el Gestor de Folios 3.0 esta activado.
Usuario Última Acción	Usuario que realizó la última modificación o acción sobre el xPOS.
Sucursal	Permite visualizar la sucursal a la cual pertenece el xPOS.
Estado	Muestra si el xPOS está: Activo: Habilitado para emitir documentos electrónicos. Inactivo: No se encuentra habilitado para emitir documentos. Bloqueado: xPOS configurado y asociado al dispositivo, pero está bloqueado para procesar documentos electrónicos.
Acciones	Permite acceder a más opciones: Reiniciar online: permite reiniciar de forma remota y dejar inactivo un xPOS si este se encuentra con conexión a internet. Reiniciar offline: permite reiniciar y dejar inactivo un xPOS en el caso de que el equipo no cuente con conexión a internet y se desea hacer un reseteo forzado. Bloquear: permite bloquear un xPOS. Eliminar: permite borrar un xPOS solo si se encuentra Inactivo. Desbloquear: solo habilitado cuando el xPOS está en estado bloqueado. Editar: permite entrar a modificar información o agregar/eliminar tipos de DTE en el xPOS. Clonar entre ambientes: permite clonar el xPOS entre los ambientes de SBX y PRD, y se creará con el mismo UUID. Liberar folios: permite liberar el subrango de folios de un documento y este sea devuelto al GF3.0.

🔘 Botones y funcionalidades

🔍 Filtrar

Permite aplicar filtros personalizados sobre el listado, facilitando la búsqueda de xPOS específicos.

Campos de Filtrado
A continuación, se detalla la función de cada criterio disponible:

• ID xPOS: Ingrese el xPOS UUID único del punto de venta. Es ideal cuando necesita consultar un xPOS específico.
• Nombre xPOS: Permite buscar por el nombre asignado al punto de venta (ej: "Caja Central", "Sucursal Norte"). Puede ingresar el nombre completo o parcial.
• Estado: Utilice este menú desplegable para filtrar los registros según el estado de onboarding del xPOS (por ejemplo: Activos, Inactivos o Bloqueados).
• Búsqueda por DTE: Este filtro le permite segmentar por el tipo de Documento Tributario Electrónico (como Facturas, Boletas, Notas de Crédito, etc.) asignados al xPOS.
• Búsqueda por Sucursal: Si su empresa cuenta con múltiples sucursales, seleccione una sucursal específica para visualizar solo los movimientos asociados a ese recinto.

Acciones del Panel:

• Limpiar: Junto a cada campo encontrará la opción "Limpiar". Al presionarla, se borrará únicamente el contenido de ese filtro específico, permitiéndole corregir una búsqueda sin afectar las demás.
• Botón Filtrar: Una vez completados los campos deseados, presione el botón verde Filtrar en la parte inferior para actualizar la lista en pantalla con los resultados encontrados.
• Cerrar (X): Puede cerrar el panel en cualquier momento presionando la "X" en la esquina superior derecha si decide no aplicar cambios.

💡 Tip de eficiencia: No es necesario completar todos los campos, se pueden realizar combinaciones, por ejemplo: "Sucursal" y "Estado" para obtener un reporte rápido de los puntos activos en una ubicación determinada.

⚙️ Opciones

Acceso a acciones generales sobre el listado:

Exportar: la lista de xPOS.

¿Cómo exportar la información? Para realizar una exportación exitosa, siga estos tres pasos:

• Selección de registros: Desde la pantalla principal de "Pool", marque la casilla de verificación (checkbox) junto a cada xPOS que desee incluir en su reporte.
  Nota: El sistema solo exportará aquellos elementos que hayan sido seleccionados previamente.
• Acceso al Menú: Una vez marcados los registros, diríjase al botón de "Opciones" ubicado en la parte superior de la pantalla.
• Generación del archivo: Dentro del menú desplegable, haga clic en la opción "Exportar".

Resultado de la descarga

• Formato: El sistema generará automáticamente un archivo en formato CSV (Valores separados por comas), compatible con Microsoft Excel, Google Sheets y otros gestores de datos.
• Ubicación: El archivo se descargará de forma automática en la carpeta de "Descargas" predeterminada de su computador local o navegador.

⚠️ Importante: Si el botón "Exportar" no aparece habilitado o no genera ninguna acción, asegúrese de haber seleccionado correctamente al menos un xPOS en la lista de xPOS.

Importar: crear masivamente xPOS.

Esta funcionalidad permite dar de alta nuevos dispositivos o actualizar la configuración de los existentes de forma masiva en el sistema, optimizando el tiempo de implementación.

Requisitos de los Archivos:
Para procesar una importación, el sistema requiere que se carguen obligatoriamente dos archivos en formato CSV. Es fundamental respetar la estructura de columnas para evitar errores de validación.

• Archivo de Cabecera: En este archivo se define la identidad básica del dispositivo, incluyendo su Nombre y la Sucursal a la cual estará asociado.
• Archivo de Líneas (Detalle): Este archivo contiene la configuración operativa detallada. Aquí se deben listar los DTE (Documentos Tributarios Electrónicos) que el xPOS está autorizado a emitir y los umbrales de recarga de folios.
  ⚠️ Importante: este archivo solo es funcional si la organización tiene habilitado el Gestor de Folios 3.0.

Paso a Paso para Importar

• Descarga de Plantilla: Antes de comenzar, se recomienda presionar el botón "EJEMPLO". Esto descargará archivos base que puede utilizar como guía para completar su propia información.
• Selección de Archivos: Haga clic en el primer botón de "Seleccionar archivo" para cargar el archivo de Cabecera.
  Haga clic en el segundo botón de "Seleccionar archivo" para cargar el archivo de Líneas.
• Confirmación: Una vez que ambos archivos aparezcan como seleccionados, presione el botón verde "CONFIRMAR" para iniciar el proceso de carga y actualización.

💡 Recomendación: Si desea cancelar el proceso en cualquier momento antes de la confirmación final, puede utilizar el botón "CANCELAR" o cerrar la ventana desde la "X" superior.

➕ Agregar xPOS

Abre un formulario para crear un nuevo xPOS. Los campos requeridos suelen incluir:

• Nombre del xPOS
• Seleccionar la sucursal del xPOS
• Asignar el tipo de documento
• Parámetros de umbral

🔁 Recargar

Actualiza la tabla de xPOS con los datos más recientes desde el backend.

Interacción recomendada: Usar esta sección al dar de alta nuevos puntos de emisión o al modificar sus parámetros.

🧾 Sección de Logs

📌 Descripción General

La sección Logs de xPOS proporciona una visualización en tiempo real del comportamiento del sistema a través de gráficos interactivos, construidos a partir de datos recolectados y procesados por Elasticsearch. Esta herramienta es fundamental para el monitoreo operativo, soporte técnico y análisis de rendimiento.

🔐 Acceso a la Sección

Desde el menú principal de xPOS, selecciona la opción Logs para ingresar al panel de visualización. Allí encontrarás filtros y representaciones gráficas del estado del sistema.

1. 🎛 Filtros de Visualización

En la parte superior del panel se encuentra la barra de filtros y controles de visualización:

Selector de tiempo Permite definir el período de análisis, como por ejemplo: “Últimos 2 días” o rangos personalizados.

Botón de actualización ( 🔄 Refresh ) Recarga los datos desde Elasticsearch para mostrar la información más reciente disponible.

Controles de vista Íconos o botones que ajustan el tipo de gráfico, densidad de datos o estilos de visualización.

• UUID xPOS: corresponde al ID asignado del xPOS especifico a consultar.
• docNumber: corresponde a la serie y número fiscal del documento.
• TransactionID: corresponde al transaction ID del documento generado en xPOS.
• ET_CODE: corresponde al numero de autorización de la entidad tributaria (CUFE, N° de autorización, etc.).

2. 🧠 Fuente de Datos: Elasticsearch

Todos los datos presentados en esta sección provienen de un clúster de Elasticsearch, que permite:

• Almacenamiento e indexación eficiente de logs generados por xPOS.
• Consultas optimizadas por tipo de evento, error, período de tiempo, entre otros.
• Visualización en casi tiempo real, ideal para diagnóstico inmediato.

3. ✅ Buenas Prácticas de Uso

• Monitorea diariamente la sección para verificar el estado del sistema.
• Observa picos de errores o interrupciones en el flujo normal de procesamiento.
• Ajusta los filtros de tiempo para enfocar tu análisis en períodos críticos (por ejemplo, horarios de alta demanda).

Si detectas comportamientos anómalos o errores recurrentes:

• Exporta la data (si la funcionalidad está disponible).
• Informa al equipo de soporte técnico para revisión.

🧾 Sección de Contingencia

📌 Descripción General

La sección Contingencias permite visualizar información sobre los distintos terminales xPOS que han registrado eventos en modo de contingencia. Este panel ayuda a los usuarios a monitorear el comportamiento de los dispositivos ante fallas de conexión con la DIAN u otros servicios críticos.

🧭 Navegación y Componentes

🔍 Botón “Filtrar”

Ubicado en la parte superior izquierda.

Permite aplicar filtros personalizados sobre la lista de dispositivos xPOS para facilitar su búsqueda.

🔁 Botón “Recargar”

Ubicado en la parte superior derecha.

Actualiza la tabla con la información más reciente de los logs de contingencia.

📋 Tabla de Contingencias

Columna	Descripción
ID xPOS	Identificador único del dispositivo xPOS (se muestra de forma abreviada con puntos suspensivos).
Nombre xPOS	Nombre asignado al dispositivo para su fácil identificación (ej: JPF-xCO3, JAVIERA UWU).
Últimos logs	Fecha y hora del último registro de actividad del xPOS en modo contingencia.
Acciones	Ícono de reloj 🕒 que permite acceder al historial detallado de logs del dispositivo seleccionado

📝 Ejemplo de Uso

• Haz clic en el botón Filtrar si deseas buscar un xPOS específico (por nombre, ID u otro criterio).
• Revisa la columna Últimos logs para identificar qué terminales han reportado actividad recientemente en contingencia.
• Haz clic en el ícono de reloj en la columna Acciones para visualizar el historial detallado de eventos del terminal seleccionado.
• Pulsa Recargar para actualizar la información mostrada.

💡 Recomendaciones

• Revisa periódicamente esta sección para anticipar o investigar posibles fallas de comunicación.
• Los eventos en contingencia suelen indicar que el sistema operó sin conexión al sistema central (por ejemplo, DIAN), lo cual puede requerir revisión o sincronización posterior.

🖥️ Sección de Monitor

📌 Descripción General

La sección Monitor permite visualizar el estado en tiempo real de los diferentes xPOS registrados por sucursal. Desde aquí, los usuarios pueden verificar el estado operativo (activo/inactivo/bloqueado), la versión instalada, los datos procesados, errores y contingencias asociadas a cada xPOS.

🔍 Filtros Superiores

En la parte superior de la pantalla, se encuentran tres filtros clave:

• Sucursal: Permite seleccionar una o más sucursales específica para mostrar únicamente los xPOS asociados.
• Estado: Filtra los xPOS por su estado (Activo / Inactivo).
• Conexión: Filtra los xPOS por su estado de conexión (Online / Offline).
• Versión: Muestra las versiones activas de los xPOS de la organización.

🧱 Modos de Visualización

Puedes alternar entre dos modos de visualización:

• Grilla: Muestra los xPOS en tarjetas individuales con su información relevante, separados por sucursal.
• Tabla: Permite ver los datos de los xPOS en formato tabular.

📋 Información por xPOS

Cada tarjeta contiene:

• Sucursal: Nombre de la sucursal.
• Nombre del xPOS: Identificador único asignado al punto.
• Estado: Indicado por una etiqueta de color si el onboarding está:
• Activo.
• Inactivo.
• Bloqueado.
• Versión: Número de versión del xPOS instalado.
• Procesados: Cantidad de documentos procesados.
• ET / Contingencias: Cantidad de documentos procesados bajo:
• ET (CL, PY): Documentos enviados a la API SendDocumentToAuthority para enviar a la entidad tributaria.
• Contingencias (CO, CR, GT, PA): Modalidad de contingencias, ya sean de emisor o entidad tributaria.
• Errores: Cantidad de documentos procesados con errores detectados.
• Estado Online/Offline: Indicador visual del estado de la conexión a internet:
• Punto rojo corresponde al modo offline.
• Punto verde corresponde al modo online.
• Última recarga: Fecha de registro de la última vez que el xPOS realizo la recarga de configuraciones.

🔄 Botón Acciones remotas”

Ubicado en la parte superior derecha, permite ejecutar acciones especificas a los xPOS seleccionados, tales como:

• Actualizar xPOS: permite actualizar la versión del xPOS.
• Recargar configuración: permite ejecutar el proceso de actualizar con las últimas configuraciones del xPOS.

🔄 Botón “Recargar”

Ubicado en la parte superior derecha, permite refrescar los datos de todos los xPOS mostrados.

🗂️ Sección de Versiones

📌 Descripción General

La sección Versiones permite al usuario consultar el historial de actualizaciones del sistema xPOS, incluyendo detalles sobre cada versión publicada, su fecha de despliegue, el producto asociado y una breve descripción de los cambios realizados.

🧭 Navegación y Componentes

🔽 Filtro de Producto

• Ubicado en la parte superior izquierda.
• Permite seleccionar el producto específico (CORE / UPDATER / CONSOLE) para filtrar las versiones mostradas en el listado.

🔁 Botón “Recargar”

• Ubicado en la parte superior derecha.
• Refresca los datos de la tabla para mostrar información actualizada sin recargar la página.

🔁 Botón “Ver descargas”

• Ubicado en la parte superior derecha (reemplaza el botón “Historial de notas”).
• Permite acceder a la pantalla para ver las versiones y descargarlas.

🔁 Botón “Historial de notas”

• Ubicado en la parte superior derecha.
• Permite acceder a la pantalla para ver el historico de los release notes.

📋 Tabla de Versiones

Columna	Descripción
Versión XPOS	Número de versión desplegada XX.XX.XX (ej: 2.4.6).
Fecha Actualización	Fecha en que fue liberada la versión correspondiente.
Producto	Producto al cual pertenece la versión (ej. CORE
Descripción	Información resumida sobre los cambios incluidos en la versión. Pueden incluir correcciones, mejoras o nuevas funcionalidades.
Acciones	Menú contextual con acciones adicionales (puede incluir visualización detallada o descarga de release notes, si está habilitado). Ver realase: visualización detallada de release notes y descarga del archivo. Descargar: permite descargar el instalador para las plataformas Windows y Linux; y la URL del repositorio para Docker.

📝 Ejemplo de Uso

1. Selecciona el producto desde el menú desplegable.
2. Consulta la lista ordenada cronológicamente (de la más reciente a la más antigua).
3. Haz clic en el ícono de acciones (⋮) al final de la fila para ver más detalles de una versión específica (si aplica).
4. Usa el botón “Recargar” si se han liberado nuevas versiones durante tu sesión.

💡 Notas Adicionales

• Las descripciones de las versiones pueden incluir emojis o íconos para resaltar tipos de cambios (🚀 nuevas funcionalidades, 🐞 correcciones, ⚙️ mejoras técnicas, etc.).
• Este listado es útil tanto para desarrolladores como para usuarios de soporte que deseen validar si un problema ya fue corregido en una versión posterior.

🧾 Sección de Configuraciones

📌 Descripción General

La sección Configuraciones permite definir parámetros esenciales para el correcto funcionamiento del sistema xPOS. Desde esta vista, los usuarios pueden ajustar opciones relacionadas con persistencia de datos, actualizaciones automáticas, políticas de gestión de tiempos, sucursales y reportes regulatorios (si aplica).

1. 🗂 Persistencia de Datos

Esta opción permite controlar la retención local de documentos en el dispositivo.

• Días de almacenamiento: define el número de días que los documentos serán conservados localmente (máximo: 20 días).
• Una vez superado este plazo, los registros serán eliminados automáticamente del dispositivo.

2. 🔄 Actualización del xPOS

Permite configurar el método y horario de actualización del sistema en los dispositivos.

⚠️

El producto xPOS Updater utilizará esta configuración para definir su modo de operación

▪ Tipo de actualización

Define el modo en que el sistema se actualiza:

• Automática: el dispositivo se actualiza de forma automática en el dispositivo xPOS.
• Esta configuración se ejecutará en el horario update xPOS definido.
• Manual: sse requiere intervención manual de usuario para aplicar las actualizaciones diretamente en los dispositivos xPOS.
• Programado: permite programar una actualización planificada, se debe definir:
• La fecha y hora de ejecución.
• Seleccionar los xPOS afectos a la tarea de actualización programada.

Una vez definidos los parametros, se debe hacer clic en Guardar. Se podrán visualizar las tareas programadas y/o ejecutadas en el botón Ver updates programados.

▪ Horario de actualización

Establece las horas en que el sistema realizará procesos programados:

• Actualización de versión: momento en el que xPOS Updater descarga e instala nuevas versiones.
• Recarga de xPOS Core: descarga de configuraciones nuevas desde el servidor.

3. ⏱ Gestión de Tiempos

Controla el comportamiento del sistema frente a fallos de conexión o ejecución, asegurando resiliencia y continuidad operativa.

Tiempo de Envío de Logs

• Frecuencia de envío de logs: establece el intervalo de tiempo (en minutos) entre cada envío automático de logs del sistema.
• Valor predeterminado: 10 minutos

✅

Importante: Al terminar la configuración, presiona el botón Guardar para aplicar los cambios

4. 🏢 Gestión de Sucursales

Permite la creación y edición de sucursales dentro de la organización.

• Las sucursales configuradas estarán disponibles para ser asignadas al crear o editar un dispositivo xPOS.
• Útil para organizaciones con múltiples puntos de venta o sedes.

5. 💬 Gestión de Comunicaciones

Permite gestionar los usuarios a los cuales les pueden llegar las notificaciones (por correo electrónico) relacionadas con xPOS.

• Se deben agregar las cuentas de correo electrónico de los usuarios a los que se deseen enviar las comunicaciones de xPOS.
• Se debe seleccionar el tipo de notificaciones que se van a recibir:
• Versiones: recibir noticias acerca de nuevas versiones de xPOS.
• Alertas: recibir alertas/notificaciones de eventos de xPOS.