📋 Resumen general
Este sistema es un Punto de Venta local, offline-first. Opera desde el navegador, guarda las ventas en SQLite y permite seguir vendiendo sin depender de internet para la operación diaria.
POS táctilCatálogo, carrito, pagos, promociones, jornada y boleta en una sola pantalla.
Administración completaProductos, categorías, usuarios, cajeros, clientes, stock, medios de pago y configuración.
Integraciones localesTransbank, DTE, impresión térmica, báscula y notificaciones según configuración.
Herramientas de controlDashboard, historial, exportación, respaldos, guard de hardware e inspector SQL.
Rutas principales de uso:
/pos - Pantalla principal de venta./admin - Administración del sistema./panel - Indicadores y gráficos de ventas./guard - Protección de despliegue y vínculo de hardware./sys - Inspector SQL interno para diagnóstico./ayuda - Esta ayuda.
🔐 Acceso y perfiles
El sistema usa inicio de sesión en /login y controla los accesos según perfil.
- Administrador: acceso completo, incluyendo usuarios, configuración, medios de pago, Transbank, Guard e inspector SQL.
- Jefatura: operación, panel, administración operativa y acciones de control como exportar o anular ventas.
- Vendedor: operación diaria del POS, venta, jornada e historial permitido.
Tip: Desde el menú de configuración del POS puedes cerrar sesión con Salir.
🕐 Abrir / cerrar jornada
Antes de vender debe existir una jornada abierta. La jornada registra cajero, fondo inicial, ventas, pagos, efectivo esperado y diferencias al cierre.
Abrir jornada
- En
/pos, abre el menú Jornada de la barra superior.
- Selecciona Abrir Jornada.
- Elige el cajero e ingresa el fondo de caja inicial.
- Confirma para comenzar a vender.
Cerrar jornada
- Abre el menú Jornada y selecciona Cerrar Jornada.
- Ingresa el efectivo contado al cierre.
- Agrega notas si corresponde.
- Confirma el cierre para calcular ventas, transacciones, efectivo esperado y diferencia.
Fórmula: efectivo esperado = fondo inicial + pagos en efectivo - vueltos entregados.
🛒 Agregar productos
Desde el catálogo
- Selecciona una categoría en la franja superior del catálogo.
- Toca el producto que deseas vender.
- El producto se agrega al carrito o abre una ventana si necesita configuración.
Búsqueda y código de barras
- Buscar productos: escribe en el campo de búsqueda para filtrar en tiempo real.
- Escáner: escanea o escribe el código y presiona Enter.
- Foco automático: cuando el campo de código está visible, el POS intenta mantenerlo listo para el escáner.
🧩 Productos especiales
El catálogo admite varios tipos de producto:
- Simple: se agrega directo al carrito.
- Pesable / granel: se vende por kilo; puedes ingresar peso manual o escanear etiqueta de balanza.
- Configurable: abre un detalle para escoger opciones, modificadores o ajustes.
- Compuesto: guía una composición con base obligatoria y addons opcionales.
Los productos también pueden tener marca, descripción, color, orden, código de barras, IVA, costo, stock inicial y fecha de caducidad. Si un producto está vencido o por vencer, el POS muestra una alerta visual en la grilla.
⚖️ Balanza y códigos pesables
Cuando la balanza imprime etiquetas EAN-13 con PLU y peso embebido, el POS puede detectar el formato, extraer el peso y calcular el total contra el precio por kilo.
- Configura el producto como Pesable / granel.
- Usa el campo Código de barras como PLU de búsqueda, por ejemplo
31.
- Define el precio del producto como precio por kilo.
- Escanea la etiqueta de la balanza; el carrito registrará peso, precio/kg y total calculado.
El formato de lectura se ajusta desde /admin?section=settings en la pestaña Balanza: prefijo, largo total, posiciones de PLU y peso, divisor, modo de búsqueda y eliminación de ceros iniciales.
🧾 Gestión del carrito
- Cambiar cantidad: usa los controles de cada línea.
- Duplicar ítem: replica una línea, útil para productos configurados.
- Eliminar: quita una línea del carrito.
- Quitar addon: en productos compuestos puedes retirar addons agregados.
- Limpiar: vacía todo el pedido actual.
Importante: el carrito vive en la sesión local del POS. Finaliza o limpia la venta antes de cambiar de operación.
👤 Asociar cliente
Debajo del número de pedido puedes asociar cliente a la venta.
- Escribe nombre o RUT con al menos 2 caracteres.
- El POS muestra sugerencias de clientes registrados.
- Selecciona con mouse o con ↑ ↓ y Enter.
- Si no existe, puedes dejar un nombre manual como referencia.
Los clientes VIP aparecen marcados y pueden activar promociones configuradas para cliente.
Desde el menú Promociones de la barra inferior puedes revisar promociones activas, aplicar códigos promo y usar descuentos manuales.
- Promociones automáticas: porcentaje, monto fijo, compre X lleve Y, método de pago, rango horario, día de semana y cliente/VIP.
- Código promo: ingresa el código y el carrito recalcula el descuento si está vigente.
- Descuento manual: aplica porcentaje o monto fijo sobre el subtotal.
- Acumulables: las reglas marcadas como acumulables pueden convivir con otros descuentos según prioridad.
💰 Cobrar la venta
El POS permite pago rápido, efectivo con vuelto y checkout con uno o varios medios de pago.
Pago rápido
- Efectivo: abre un diálogo con monto recibido, botones rápidos, teclado numérico y cálculo de vuelto o faltante.
- Medios con acceso rápido: se muestran como botones en la barra inferior y cobran el total exacto.
- Otros medios: el menú de medios extra muestra los métodos activos que no tienen botón rápido.
Pago mixto
Usa Checkout para agregar varias filas de pago, seleccionar método, monto y referencia. El total debe quedar cubierto para confirmar.
Importante: debe existir jornada abierta y carrito con productos para cobrar.
💳 Terminal Transbank
Si un medio de pago tiene terminal Transbank y la integración está habilitada, el POS valida el servicio local antes de iniciar el cobro.
- Muestra una ventana de progreso con eventos del pinpad, como insertar tarjeta o ingresar clave.
- Permite cancelar la operación y devolver el terminal a modo normal.
- Puede imprimir o registrar el voucher según la configuración del servicio.
- El panel
/admin/tbk permite revisar health, poll, cargar llaves, totales, detalle, última venta, cierre de lote y modo normal.
Configuración: habilita tbk.enabled en setup.json y asigna el terminal en Admin → Medios de Pago.
🧾 Boleta, DTE e impresión
- Folio local: cada venta completada recibe un folio consecutivo reservado para el terminal.
- Boleta HTML: después de pagar puedes abrir Ver Boleta desde la venta completada o historial.
- Impresión térmica: cuando está habilitada, el sistema usa el spooler nativo de Windows/Linux y el ancho configurado.
- DTE: si
dte.enabled está activo, el sistema envía la boleta al sidecar local después del checkout.
La integración DTE permite configurar URL, token, tipo DTE, envío al SII, timeout y si un error debe bloquear o no la venta.
📜 Historial de ventas
Desde Jornada → Historial o /pos/history puedes revisar ventas recientes.
- Ver el detalle y abrir la boleta de una venta.
- Exportar ventas a Excel desde perfiles autorizados.
- Anular ventas desde perfiles de jefatura o administrador.
El engranaje de la esquina superior derecha contiene ajustes rápidos de pantalla y accesos de navegación.
- Claro / Oscuro: alterna tema y guarda la preferencia en el navegador.
- Pantalla completa: activa o desactiva el modo de pantalla completa.
- Ver info superior: muestra u oculta datos de empresa, sucursal y terminal.
- Buscar Productos: muestra u oculta el campo de búsqueda.
- Código de Barras: muestra u oculta el campo para escáner.
- Ver todos los productos: controla si aparece el botón de todos los productos.
- Navegación: accesos a Administración, Panel de Ventas, Ayuda y Guard.
⌨️ Teclados flotantes
El POS incluye teclados en pantalla para terminales táctiles.
- Teclado de texto: se abre al enfocar la búsqueda de productos.
- Teclado numérico: se abre desde el menú de teclado de la barra inferior y apunta al campo de código de barras.
- Configuración en caliente: se habilitan o deshabilitan desde Admin → Configuración → Teclados sin recompilar.
#️⃣ Folios
La barra superior muestra el folio actual y los folios restantes del bloque reservado. El sistema reserva bloques por terminal para operar offline y mantener numeración consecutiva.
Tip: si los folios restantes bajan demasiado, revisa la configuración folio.block_size y el estado de la base local antes de operar por largos periodos offline.
🔧 Panel de administración
Accede desde /admin. El menú lateral cambia según permisos; algunas secciones son solo para administrador.
📦 Productos
Permite crear, editar, desactivar y cargar productos en lote desde Excel. Campos relevantes: nombre, SKU, marca, categoría, tipo, precio, costo, código de barras, IVA, stock inicial, caducidad, orden, color, descripción y agrupadores personalizados.
- Carga masiva: descarga una plantilla Excel y sube productos en lote.
- Agrupadores personalizados: agrega campos extra para clasificar productos.
- Stock e historial: al editar un producto puedes revisar stock actual y movimientos.
🏷️ Categorías
Organizan la grilla del POS. Cada categoría tiene nombre, rol, color, icono, orden y estado activo.
- Normal: categoría visible para venta directa.
- Base composición: productos que funcionan como base obligatoria de un compuesto.
- Addon composición: productos que se ofrecen como adicionales en un compuesto.
👤 Cajeros
Administra los cajeros usados para abrir jornada. Cada cajero tiene nombre, PIN y estado activo.
🔐 Usuarios
Sección de administrador para crear y editar usuarios de acceso web. Los perfiles disponibles son Jefatura y Vendedor; el administrador principal viene desde la configuración inicial.
🎫 Promociones / descuentos
Permite configurar promociones por porcentaje, monto fijo, compre X lleve Y, código promo, método de pago, horario, día de semana o cliente. También define vigencia, prioridad, estado y si son acumulables.
📊 Inventario
Controla stock físico y lógico, registra ajustes, compras/ingresos, devoluciones e inventario inicial. La sección Historial Stock muestra movimientos globales y cada producto tiene su propio historial.
👥 Clientes
Registro de clientes con nombre, RUT, email, teléfono y marcador VIP. Los clientes registrados aparecen en la búsqueda inteligente del POS.
🕐 Jornadas
Historial de jornadas con estado, cajero, apertura, cierre, fondo inicial, ventas, transacciones, efectivo esperado, efectivo declarado y diferencia.
💰 Medios de pago
Sección de administrador para crear medios dinámicos. Cada medio tiene código, etiqueta, icono, color, terminal asociado, orden, acceso rápido y estado.
Uso típico: marca Acceso rápido para que el medio aparezca como botón en el POS. Asigna Transbank si debe usar pinpad.
⚙️ Configuración
La configuración administrativa tiene pestañas:
- Balanza: parámetros de lectura de etiquetas pesables.
- Teclados: habilita o deshabilita teclado numérico y de texto.
- Notificaciones: destinatarios y envío de correo de prueba para eventos de jornada.
- Base de datos: herramientas de mantenimiento, incluyendo reseteo protegido.
Cuidado: el reseteo de base requiere escribir BORRAR, crea respaldo de seguridad y elimina datos locales de operación.
📊 Panel de ventas
Accede desde /panel. Muestra analítica de ventas con filtro de fechas.
- KPIs: ventas, ingresos, ticket promedio, descuentos y artículos vendidos.
- Gráficos: tendencia diaria, métodos de pago, días de semana, horas y productos vendidos.
- Tablas: ranking de productos y promociones aplicadas.
🛡️ Guard y seguridad
/guard vincula el sistema al hardware mediante fingerprint y protege archivos/configuración de despliegue.
- Deploy: deja el sistema protegido para operación.
- Undeploy: desbloquea para mantenimiento autorizado.
- Unbind: permite revincular el fingerprint si cambia el equipo.
Cuando Guard está desplegado, el inspector SQL queda bloqueado hasta desbloquear desde /guard.
🧪 Inspector SQL
/sys es una herramienta interna para diagnóstico de la base SQLite. Permite consultar tablas y ejecutar consultas desde perfiles de administrador.
Uso recomendado: úsalo solo para soporte o revisión técnica. En modo desplegado, Guard bloquea este acceso.
🔌 API JSON
El sistema expone endpoints JSON para integraciones locales o diagnóstico.
| Ruta | Descripción |
|---|
/api/products | Lista productos. |
/api/products/{id} | Obtiene un producto por ID. |
/api/products/barcode/{barcode} | Busca producto por código de barras. |
/api/products/search | Busca productos por texto. |
/api/categories | Lista categorías. |
/api/sales | Lista ventas. |
/api/sales/{id} | Obtiene una venta por ID. |
/api/shift | Entrega la jornada actual. |
💾 Respaldos y base de datos
El sistema trabaja con una base SQLite local definida en setup.json. Los respaldos se guardan en la carpeta bk/ con empresa/sucursal/terminal y marca de tiempo.
- Respaldo manual: desde el POS, menú de sistema o ruta
/pos/database/backup para perfiles autorizados.
- Respaldo de seguridad: antes de vaciar la base desde administración se crea un respaldo.
- Outbox local: registra eventos para sincronización futura cuando la nube esté habilitada.
- Cloud opcional: si
cloud.enabled está activo, el sistema usa endpoint/API key/intervalo configurados.
Importante: realiza respaldos antes de cambios de catálogo masivos, mantenimiento de base, actualización del ejecutable o traslado del equipo.