SaturnoPOS · License ServerConsola de administración de licencias

La regla de oro (modelo pull): el servidor NUNCA se conecta a las instalaciones. Cada instalación «llama a casa» periódicamente (check-in) y en esa misma respuesta recibe: comandos pendientes, configuración publicada y noticias de releases. Por eso todo cambio tarda hasta el próximo check-in de cada equipo en aplicarse.

El servidor se configura exclusivamente con variables de entorno (nunca hay secretos en archivos):

• ADMIN_API_KEY — llave para entrar a este panel y a los endpoints administrativos.
• LICENSE_PRIVATE_KEY — clave privada ECDSA del proveedor; firma códigos de activación y comandos de configuración. Sin ella no se puede activar licencias ni publicar configuración.
• WOMPI_PRIVATE_KEY y WOMPI_EVENTS_SECRET — integración de pagos Wompi.
• SMTP_HOST / SMTP_USER / SMTP_PASSWORD — relay central de correo de la flota. Rotar la contraseña = cambiar la variable y reiniciar; la flota no se toca.
• LICENSE_DB_PATH — ruta de la base de datos SQLite única (por defecto data/licenseserver.db junto al ejecutable).
• DEVICE_TOKEN_SECRET — activa el token por instalación del relay de correo (anti-suplantación). Vea la sección «🔐 Seguridad».
• REQUIRE_HTTPS=true — rechaza todo tráfico sin HTTPS (respeta X-Forwarded-Proto del reverse proxy).
• BACKUP_OFFSITE_PATH — segunda copia de cada backup en otro destino (regla 3-2-1).
• NEW_INSTALLS_PER_DAY_ALERT — umbral de alerta por crecimiento anómalo del inventario (por defecto 50/día).

Puesta en marcha desde cero

1. Genere el par de claves del proveedor: licensetool keys → guarda license-private.key (secreta, solo el servidor) y license-public.key (se embebe en la app).
2. Defina las variables de entorno del servidor (ADMIN_API_KEY, LICENSE_PRIVATE_KEY, SMTP, Wompi).
3. Inicie el servidor (consola, servicio o Docker) y abra /admin en el navegador.
4. Ingrese la llave de administrador y pulse Conectar.
5. Espere el primer check-in de las instalaciones: aparecerán solas en el tab Instalaciones.

Cada instalación de la app (solo el equipo principal del negocio; las sucursales no reportan) envía automáticamente una vez por semana a POST /api/insights/ventas un resumen consolidado de sus ventas: totales por familia, productos más vendidos con precio mín/prom/máx, serie diaria, distribución por hora y día de la semana, formas de pago y conteos de compradores (distintos, nuevos, recurrentes, mostrador vs identificados) por segmento (lista de precios) y ciudad. El envío viene activado por defecto y el Administrador del negocio puede apagarlo en Configuración → Backups → Compartir tendencias de consumo.

Nunca llegan facturas individuales ni datos de clientes finales (nombres, documentos, teléfonos, correos, direcciones): de los compradores solo llegan números agregados.

Qué muestra el dashboard

• KPIs: negocios, tickets, venta, ticket promedio, compradores distintos, nuevos, recurrentes y % de tickets identificados.
• Tendencia mensual (variación mes a mes) y serie diaria con los días de mayor venta.
• Familias con participación y margen; diferencial de precios por familia = dispersión del precio del mismo producto entre negocios (rojo ≥ 40 %, ámbar ≥ 15 %).
• Productos más vendidos y de menor rotación.
• Compradores por segmento comercial y mostrador vs identificados; geografía por ciudad del negocio y ciudad del comprador.
• Horas pico, días de la semana y formas de pago.

Cómo consultarlo

1. Abra el tab 📊 Tendencias. Por defecto muestra los últimos 90 días (por fecha de fin de cada período semanal); use Rango rápido o ajuste Desde/Hasta.
2. Filtre por Ciudad o suba el mínimo de negocios por grupo y pulse Consultar.
3. Cada panel tiene botón ⬇ CSV; ⬇ CSV completo exporta todos los bloques para Excel/Power BI.
4. Para integraciones: GET /api/insights/consolidado?desde=AAAA-MM-DD&hasta=AAAA-MM-DD&ciudad=Bogotá&minNegocios=5 con header X-Admin-Key.

🤖 Analista IA

Escriba una pregunta en lenguaje natural (o use los chips de preguntas rápidas) y pulse Analizar con IA. El servidor envía al modelo exactamente el mismo JSON k-anónimo que ve el panel para el rango filtrado, nunca reportes individuales. Requiere AI_API_KEY en el servidor (cualquier API estilo OpenAI: AI_BASE_URL, AI_MODEL; por defecto gpt-4o-mini, el de menor costo con buena calidad). Límite de 30 consultas por hora y caché de 12 h por pregunta para controlar el gasto; la etiqueta junto al título indica el modelo activo o si la IA no está configurada.

k-anonimato

Un grupo (familia, producto, ciudad, segmento, día, mes, forma de pago) solo se publica si lo reportan al menos INSIGHTS_MIN_NEGOCIOS NIT distintos (por defecto 5). Ese umbral puede subirse por consulta, pero nunca bajarse. Si el total de negocios del rango no alcanza el mínimo, el panel solo muestra los conteos. En la app, además, cada grupo de compradores (segmento/ciudad) solo se reporta con 5+ tickets.

Derecho de supresión

Si un comerciante pide retirar sus datos, use «🗑️ Retirar los reportes de un NIT» al final del tab (o DELETE /api/insights/ventas/{nit}). Cada instalación puede enviar máximo 4 reportes por día; los excedentes se rechazan con 429.

Variables: INSIGHTS_MIN_NEGOCIOS (umbral de anonimato), MAX_INSIGHTS_SNAPSHOTS (límite de reportes almacenados; por defecto 100 000), AI_API_KEY/AI_BASE_URL/AI_MODEL/AI_MAX_TOKENS (analista IA). Los bloques de serie diaria, precios y compradores requieren reportes v2 (app 1.0.24+); los reportes v1 anteriores siguen sumándose al resto.

El relay de correo puede exigir un token secreto por instalación (header X-Device-Token). El servidor lo deriva con HMAC-SHA256 de un secreto que solo el servidor conoce: una huella inventada jamás podrá producir un token válido, lo que elimina por completo la suplantación y el uso del relay como spam.

¿Cómo se distribuye el token a la flota?

Pasos para activarlo

1. Genere un secreto fuerte (64 caracteres hex). En PowerShell: [Convert]::ToHexString([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(32)) — o en Linux: openssl rand -hex 32.
2. Configúrelo como variable de entorno DEVICE_TOKEN_SECRET y reinicie el servidor. Nunca lo guarde en archivos ni en el repositorio.
3. Espere ~24 horas (un ciclo de check-in): cada POS con licencia pagada recibe y guarda su token automáticamente.
4. Listo: el relay ya exige el token. Las huellas falsas reciben 401 aunque hagan check-in.

Preguntas frecuentes

Muestra cada instalación que ha hecho check-in (la app reporta su estado periódicamente de forma automática). Columnas clave:

• Salud: Ok normal, Advertencia requiere atención pronto, Crítico requiere acción inmediata (licencia vencida, muchos errores, sin reportar).
• Licencia: estado y días restantes.
• Outbox: correos/sincronizaciones pendientes en el equipo (número alto sostenido = problema de conectividad del cliente).
• Err 24h: errores registrados en las últimas 24 horas.

Procesos habituales: asignar vendedor a una instalación (campo editable en la fila), verificar geo-discrepancias (⚠️ indica que la ciudad declarada no coincide con la IP — posible copia de la instalación), y enviar comandos remotos desde la fila.

¿Qué hago según la salud?

Historial completo de todas las activaciones de licencia: pagadas por Nequi (cobro push directo al celular, sin comisión de agregador) o Wompi (link de pago, plan B), generadas manualmente y revocadas. Desde aquí se administra el ciclo de vida completo sin salir del panel. La columna Origen indica el medio usado.

• Ver código (🔑): recupera el código de activación firmado de una licencia pagada, para reenviarlo al cliente si lo perdió.
• Activación manual (➕): genera un código firmado sin pasar por la pasarela de pago. Úsela solo cuando el pago fue verificado por otro medio (transferencia, efectivo). Requiere NIT, huella del equipo (la muestra la app del cliente) y meses. Queda auditada con origen "Manual".
• Revocar (⛔): invalida una licencia pagada en el servidor (p. ej. contracargo o fraude). Pide un motivo y queda registrada en Auditoría. Es idempotente: revocar dos veces no genera error.

Estados de una activación

Agrupa las instalaciones por cliente (NIT) con sus datos de contacto reportados por la propia app. Útil para saber cuántos equipos tiene cada cliente, cuáles están críticos y cuándo reportaron por última vez. Es solo lectura: los datos se corrigen en la app del cliente.

Comisiones

Liquida comisiones por rango de fechas: elija Desde/Hasta, la tasa % y pulse Liquidar. El cálculo usa los pagos registrados y el vendedor asignado a cada instalación.

Vendedores

Alta y edición de vendedores (nombre, teléfono, email, activo). El nombre del vendedor es el que se asigna a las instalaciones en el tab Instalaciones. Las tarjetas muestran el desempeño de los últimos meses seleccionados.

• Precio base: valor por sede/mes que pagan todos los clientes sin precio especial. Cambiarlo aplica a pagos futuros; no requiere tocar la app.
• Precio especial: por NIT, con vigencia opcional (desde/hasta) y nota. Tiene prioridad sobre el base.
• Ajuste masivo: aumenta por % o fija precio a: solo base, solo negociados, ambos, o una lista de NITs. Use la nota para dejar rastro (ej.: «ajuste anual 2026»).

Proceso de aumento anual

1. En «Ajuste masivo» elija el alcance: Base + negociados (lo usual para aumento general).
2. Tipo: Aumento % y escriba el porcentaje (ej. 8).
3. Escriba una nota de rastro: «ajuste anual 2026».
4. Pulse 📈 Aplicar ajuste masivo y confirme.
5. Revise la tabla resultante de precios especiales.

El servidor evalúa la flota periódicamente y genera alertas (licencias por vencer, equipos sin reportar, errores altos). Si configuró un webhook, también las notifica allí. Esta vista es el historial; no requiere acción sobre el panel, sino sobre el cliente afectado.

Permite encolar comandos que la instalación ejecuta en su próximo check-in (modelo pull; no hay conexión directa al equipo). Comandos soportados:

• Ping — verificar que el equipo responde y ver su latencia de check-in.
• ForzarBackup — el equipo genera un backup inmediato.
• ActualizarEstado — fuerza un reporte de estado completo.

Proceso:

Publica valores que TODAS las instalaciones aplican en su próximo check-in, sin redistribuir la app. El servidor firma cada comando con la clave ECDSA del proveedor y cada cliente valida la firma antes de aplicar.

Claves disponibles:

• server_url — URL de este servidor (para migraciones de dominio/host).
• enforcement — enforcement de licencia (1 activo / 0 desactivado).
• support_phone — teléfono/WhatsApp de soporte mostrado en la app.
• support_email — correo de soporte mostrado en la app.
• website — sitio web oficial mostrado en la app.
• wompi_public_key — llave pública Wompi (pub_prod_/pub_test_) usada por los POS para cobros.
• wompi_private_key — llave privada Wompi (prv_prod_/prv_test_). Secreto: cada POS la guarda cifrada y nunca la muestra ni reporta; en este panel solo se confirma como «(secreto definido)».
• wompi_sandbox — ambiente Wompi de los POS (1 pruebas / 0 producción).
• wompi_payment_link — link de pagos fijo (https://checkout.wompi.co/l/...) mostrado como QR en Venta rápida.

Ejemplo: cambiar el teléfono de soporte en toda la flota

1. Elija la clave support_phone en el selector.
2. Escriba el nuevo número (ej. 313 000 0000).
3. Defina la vigencia del comando en días (tiempo en que las instalaciones pueden recogerlo; el valor aplicado persiste aunque venza).
4. Pulse 📡 Publicar a la flota y confirme.
5. Cada instalación lo aplica en su siguiente check-in — verifíquelo en la tabla de valores publicados.

Cómo viaja el cambio (seguridad)

Proceso para publicar una actualización:

1. Compile y firme el instalador de la nueva versión y súbalo a un hosting con HTTPS.
2. Calcule el SHA-256 del archivo (recomendado: el cliente verifica integridad): Get-FileHash .\pos-1.4.0.msix -Algorithm SHA256
3. En este tab llene: versión (ej. 1.4.0), plataforma (WinUI/Android/iOS/MacCatalyst), URL de descarga, SHA-256 y notas.
4. Marque Obligatoria solo para correcciones críticas o de seguridad; la app insistirá al usuario hasta actualizar.
5. Pulse 🚀 Publicar. Cada instalación se entera en su próximo check-in.
6. Vigile la tabla Adopción los días siguientes hasta que la mayoría esté en la nueva versión.

La tabla Adopción muestra cuántas instalaciones ya están en cada versión — úsela para saber cuándo puede retirar soporte de versiones viejas.

Registra cada acceso administrativo (fecha, IP, método, ruta, resultado). 10 intentos fallidos en 15 minutos bloquean la IP temporalmente. Use los filtros de fecha y «solo fallidos» para investigar accesos sospechosos, y la purga para retirar registros antiguos.

Cada evento del ciclo de pago de licencias queda en un libro de auditoría solo-agregar: cobro creado (Nequi o Wompi), pago aprobado, pago rechazado, código entregado, activación manual y revocación. Cada entrada se sella con SHA-256 encadenado a la anterior (estilo libro contable): editar, borrar o insertar un registro rompe la cadena y se detecta.

Cómo consultar

1. Abra el tab 💳 Pagos y filtre por NIT, activación, evento, medio (Nequi/Wompi/Manual) o rango de fechas.
2. Para investigar un cobro concreto, filtre por su Id de activación: verá la línea de tiempo completa de ese pago.
3. Pulse 🛡️ Verificar integridad periódicamente (por ejemplo, junto a su rutina de backups): confirma que ningún registro fue alterado. Si la cadena está rota, el mensaje indica la entrada exacta donde ocurrió.

Los datos del servidor (inventario de la flota, activaciones, comisiones, auditoría) son irremplazables. El servidor los respalda solo, pero la seguridad total depende de que usted saque copias fuera del servidor.

Qué hace el servidor automáticamente

• Cada 6 horas (configurable con BACKUP_INTERVAL_HOURS) crea un ZIP con todos los archivos de datos.
• Cada archivo lleva su huella SHA-256 en un manifiesto; el ZIP se verifica antes de darse por bueno. Un backup corrupto nunca se guarda.
• Conserva los 30 más recientes (configurable con BACKUP_RETAIN_COUNT) y purga los demás.

Su rutina como operador — regla 3-2-1

3 copias de los datos · en 2 medios distintos · 1 fuera del servidor.

1. Entre a este tab (Backups) al menos una vez por semana.
2. Pulse ⬇️ Descargar el más reciente y guarde el ZIP en su computador.
3. Suba esa copia a un almacenamiento externo (Google Drive, OneDrive, S3…). Puede automatizarlo con un cron: curl -H "X-Admin-Key: SU_LLAVE" https://su-servidor/api/backups/ultimo -o backup.zip
4. Si usa Docker, monte /app/backups en un disco distinto al de /app/data.

Cómo restaurar (ensáyelo al menos una vez)

1. Detenga el servidor.
2. Descomprima el ZIP del backup dentro del directorio de datos (/app/data), reemplazando los archivos.
3. Arranque el servidor: la flota se re-sincroniza sola con los check-ins diarios.

⚠️ Un backup que nunca se ha probado a restaurar no es un backup: es una esperanza.

Los datos viven en una base SQLite única (data/licenseserver.db) con transacciones ACID y journal WAL: la corrupción por corte de energía es extremadamente improbable. Si una fila individual quedara ilegible, el servidor la omite al cargar y arranca normalmente; nunca se cae por un dato dañado.

Procedimiento de recuperación (base dañada)

1. Detenga el servidor.
2. Restaure desde el último backup: descomprima el ZIP más reciente y copie licenseserver.db al directorio de datos (elimine antes los archivos licenseserver.db-wal y licenseserver.db-shm si existen).
3. Arranque el servidor y verifique en el tab Backups que aparezca «✓ Servidor sano».

¿Qué pierdo si arranco con base vacía (sin restaurar)?

Primer paso siempre: abra el tab Backups (consulta /api/salud) y lea los problemas detectados. Luego:

Si nada de esto aplica, revise los logs del proceso (Docker: docker logs <contenedor>) — el servidor registra cada backup, alerta y fallo con detalle.

El flujo normal es automático: el cliente paga desde la app (Wompi) y el servidor emite el código de activación firmado.

Flujo automático (el habitual)

Flujo manual de respaldo (pago por otro medio o sin internet)

1. El cliente le comparte su huella (la muestra la app en la pantalla de licencia) o la solicitud completa (LIC-REQ|v1|...).
2. Genere el código con LicenseTool: licensetool code <nit> <huella> <meses> (ej.: licensetool code 900123456-7 AB3D-K9M2 3) o licensetool code "<solicitud>".
3. Envíe el código al cliente; lo ingresa en la app y queda activado.

Árbol de decisión: «un cliente reporta un problema»