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_DATA_PATH, FLEET_DATA_PATH — rutas de los archivos de datos (por defecto data/ 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.

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 Wompi, generadas manualmente y revocadas. Desde aquí se administra el ciclo de vida completo sin salir del panel.

• 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.

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.

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.

El servidor nunca se cae por un archivo dañado: al arrancar, si un JSON de datos no se puede leer, lo renombra a *.corrupt-<fecha> (cuarentena, sin borrarlo) y arranca con ese store vacío. El tab Backups muestra la alerta «⚠ Atención» con el archivo afectado.

Procedimiento de recuperación

1. Identifique el archivo: en el tab Backups verá el nombre en cuarentena (ej. instalaciones.json.corrupt-1760000000).
2. Detenga el servidor.
3. Restaure desde el último backup: descomprima el ZIP más reciente y copie el archivo afectado (ej. instalaciones.json) al directorio de datos.
4. Arranque el servidor y verifique en el tab Backups que aparezca «✓ Servidor sano» (elimine manualmente el .corrupt-* cuando ya no lo necesite).

¿Qué pierdo según el archivo afectado?

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»