TerminalServer.es

Introducción

La API de TerminalServer.es sigue convenciones REST estándar. Todas las respuestas son JSON.

BASE URL

https://terminalserver.es/api/
http://localhost:8080/api/    ← desarrollo

Método	Descripción
GET	Leer un recurso
POST	Crear un recurso
PUT	Reemplazar un recurso completamente
PATCH	Actualizar campos específicos
DELETE	Eliminar un recurso

Autenticación

La API usa JWT Bearer tokens. Incluye el token en el header Authorization o en el header X-API-Key (para API Keys).

HTTP

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

# O con API Key:
X-API-Key: ts_abc123def456...

Obtén tu token haciendo POST a /api/auth/login. Los tokens de usuario expiran en 24h (o 30 días si usas remember: true). Los tokens de admin no expiran por defecto.

Códigos de error

Código	Significado
200	OK — solicitud exitosa
201	Created — recurso creado
400	Bad Request — parámetros inválidos
401	Unauthorized — token inválido o expirado
403	Forbidden — sin permisos para esta acción
404	Not Found — recurso no encontrado
409	Conflict — recurso ya existe (ej: email duplicado)
429	Too Many Requests — rate limit alcanzado
500	Internal Server Error

JSON

{ "error": "Mensaje descriptivo del error" }

Auth

POST /api/auth/register Registrar nueva cuenta Público ›

Crea una nueva cuenta de usuario. El plan inicial siempre es free.

Body (JSON)

Campo	Tipo	Req.	Descripción
name	string	Req	Nombre completo
email	string	Req	Email único
password	string	Req	Mínimo 8 caracteres

cURL

curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name":"Juan García","email":"juan@example.com","password":"MiPass123!"}'

⚡ Probar

POST /api/auth/login Iniciar sesión Público ›

Campo	Tipo	Req.	Descripción
email	string	Req	Email de la cuenta
password	string	Req	Contraseña
remember	boolean	Opt	Si true, el token dura 30 días

⚡ Probar

GET /api/auth/me Perfil del usuario autenticado Auth ›

Devuelve los datos del usuario cuyo token se envía en el header Authorization.

⚡ Probar

POST /api/auth/change-password Cambiar contraseña Auth ›

Campo	Tipo	Req.	Descripción
current	string	Req	Contraseña actual
newPassword	string	Req	Nueva contraseña (min 8 chars)

⚡ Probar

2FA — Autenticación en dos pasos

POST /api/auth/2fa/setup Iniciar configuración de 2FA Auth ›

Genera un secreto TOTP y devuelve el URI para el código QR. Compatible con Google Authenticator, Authy y cualquier app TOTP.

RESPONSE

{
  "secret": "JBSWY3DPEHPK3PXP",
  "otpUri": "otpauth://totp/TerminalServer.es:user@example.com?secret=..."
}

⚡ Probar

POST /api/auth/2fa/verify Verificar y activar 2FA Auth ›

Campo	Tipo	Descripción
code	string	Código TOTP de 6 dígitos de la app autenticadora

Tickets de soporte

GET /api/tickets Listar tickets Auth ›

Los usuarios ven sus propios tickets. Los admins ven todos.

Query param	Tipo	Descripción
status	string	open \| in-progress \| resolved \| closed
priority	string	low \| normal \| high \| urgent
search	string	Buscar en el asunto
page	number	Página (default: 1)
limit	number	Por página (default: 20, max: 100)

⚡ Probar

POST /api/tickets Crear ticket Auth ›

Campo	Tipo	Req.	Descripción
subject	string	Req	Asunto del ticket
message	string	Req	Descripción del problema
category	string	Opt	soporte-tecnico \| facturacion \| cuenta \| bug \| feature \| otro
priority	string	Opt	low \| normal \| high \| urgent (default: normal)

⚡ Probar

POST /api/tickets/:id/messages Añadir mensaje a ticket Auth ›

Campo	Tipo	Descripción
text	string	Texto del mensaje

PATCH /api/tickets/:id Actualizar estado del ticket Auth ›

Los usuarios solo pueden cerrar sus propios tickets. Los admins pueden cambiar todos los campos.

Campo	Admin only	Descripción
status	No	open \| in-progress \| resolved \| closed
priority	Sí	low \| normal \| high \| urgent
assignedTo	Sí	Email del agente asignado

Sesiones remotas

GET /api/sessions/my Mis sesiones recientes Auth ›

⚡ Probar

POST /api/sessions/log Registrar inicio de sesión Auth ›

Campo	Tipo	Descripción
code	string	Código de 6 dígitos de la sala
role	string	host \| client

Utilidades de red

POST /api/dns DNS Lookup Auth ›

Campo	Tipo	Descripción
host	string	Dominio o IP a consultar
type	string	A \| AAAA \| MX \| TXT \| NS \| CNAME (default: A)

⚡ Probar

POST /api/ports Escanear puertos TCP Auth ›

Campo	Tipo	Descripción
host	string	Hostname o IP a escanear
ports	string	Lista separada por comas: "80,443,3306"
timeout	number	Timeout por puerto en ms (default: 2000)

⚡ Probar

POST /api/ping Ping a host Auth ›

Campo	Tipo	Descripción
host	string	IP o dominio (default: 8.8.8.8)
count	number	Número de pings (default: 8, max: 20)

POST /api/wol Wake on LAN — enviar Magic Packet Auth ›

Campo	Tipo	Descripción
mac	string	Dirección MAC (formato: AA:BB:CC:DD:EE:FF)
broadcast	string	IP de broadcast (default: 255.255.255.255)

Admin

GET /api/admin/stats Estadísticas del sistema Admin ›

⚡ Probar

GET /api/users Listar todos los usuarios Admin ›

Query param	Descripción
search	Buscar por nombre o email
role	admin \| user
page, limit	Paginación

⚡ Probar

GET /api/status Estado del servidor (público) Público ›

RESPONSE

{
  "status": "online",
  "rooms": 2,
  "clients": 4,
  "uptime": 86400,
  "version": "4.0.0",
  "users": 12,
  "tickets": 3
}

⚡ Probar

Billing & Payments

POST /api/billing/checkout Unified checkout (Stripe/PayPal) Auth ›

Inicia un proceso de pago unificado compatible con Stripe y PayPal.

Campo	Tipo	Req.	Descripción
plan	string	Req	Plan a contratar
method	string	Req	Método de pago: stripe \| paypal
coupon	string	Opt	Código de cupón de descuento

POST /api/billing/start-trial Iniciar prueba gratuita de 14 días Auth ›

Activa una prueba gratuita de 14 días para el usuario autenticado.

GET /api/billing/trial-status Comprobar elegibilidad de trial Auth ›

Devuelve si el usuario puede iniciar una prueba gratuita.

POST /api/billing/validate-coupon Validar código de descuento Auth ›

Campo	Tipo	Req.	Descripción
code	string	Req	Código del cupón a validar

GET /api/billing/fiscal-data Obtener datos fiscales del usuario Auth ›

Devuelve los datos fiscales almacenados del usuario autenticado.

PUT /api/billing/fiscal-data Actualizar datos fiscales Auth ›

Campo	Tipo	Req.	Descripción
nif	string	Opt	NIF / CIF
razonSocial	string	Opt	Razón social
direccion	string	Opt	Dirección fiscal

POST /api/billing/cancel Cancelar suscripción Auth ›

Cancela la suscripción activa del usuario.

POST /api/billing/cancel-recurring Cancelar renovación automática Auth ›

Desactiva la renovación automática sin cancelar inmediatamente la suscripción.

GET /api/billing/recurring-status Estado de renovación automática Auth ›

Devuelve el estado actual de la renovación automática de la suscripción.

POST /api/billing/refund/:invoiceId Procesar reembolso Admin ›

Procesa un reembolso para la factura indicada. Solo administradores.

Admin: Coupons

GET /api/admin/coupons Listar todos los cupones Admin ›

Devuelve la lista completa de cupones de descuento.

POST /api/admin/coupons Crear cupón Admin ›

Campo	Tipo	Req.	Descripción
code	string	Req	Código del cupón
type	string	Req	Tipo de descuento (porcentaje, fijo, etc.)
value	number	Req	Valor del descuento
maxUses	number	Opt	Número máximo de usos
validUntil	string	Opt	Fecha de expiración (ISO 8601)

DELETE /api/admin/coupons/:code Eliminar cupón Admin ›

Elimina el cupón identificado por su código.

Admin: PayPal

GET /api/admin/paypal Obtener configuración de PayPal Admin ›

Devuelve la configuración actual de las credenciales de PayPal.

PUT /api/admin/paypal Actualizar credenciales de PayPal Admin ›

Actualiza las credenciales de integración con PayPal.

Admin: Email

POST /api/admin/email/test-connection Probar conexión SMTP Admin ›

Verifica que la configuración SMTP es correcta enviando un test de conexión.

GET /api/admin/email/stats Estadísticas de email Admin ›

Devuelve estadísticas de envío de emails (enviados, fallidos, etc.).

GET /api/admin/email/history Historial de emails (paginado) Admin ›

Devuelve el historial de emails enviados con paginación.

GET /api/admin/email/preview/:templateId Previsualizar plantilla de email Admin ›

Genera una vista previa de la plantilla de email indicada.

GET /api/admin/email/templates Listar plantillas personalizadas Admin ›

Devuelve la lista de plantillas de email personalizadas.

PUT /api/admin/email/templates/:id Guardar plantilla personalizada Admin ›

Guarda o actualiza una plantilla de email personalizada.

DELETE /api/admin/email/templates/:id Restaurar plantilla original Admin ›

Elimina la personalización y restaura la plantilla original.

POST /api/admin/email/preview-custom Previsualizar contenido personalizado Admin ›

Genera una vista previa con contenido personalizado antes de guardar.

Email Preferences

GET /api/email/unsubscribe Cancelar suscripción a emails Público ›

Permite al usuario cancelar la suscripción a emails mediante un enlace con token.

GET /api/email/preferences Obtener preferencias de email Auth ›

Devuelve las preferencias de notificaciones por email del usuario.

PUT /api/email/preferences Actualizar preferencias de email Auth ›

Actualiza las preferencias de notificaciones por email.

Security & Integrity

GET /api/security/integrity/status Estado de integridad de archivos Admin ›

Devuelve el estado actual del sistema de verificación de integridad de archivos.

POST /api/security/integrity/check Ejecutar verificación de integridad Admin ›

Lanza una verificación de integridad de archivos contra el baseline actual.

POST /api/security/integrity/baseline Crear nuevo baseline Admin ›

Genera un nuevo baseline de hashes para la verificación de integridad de archivos.

GET /api/security/integrity/incidents Listar incidentes Admin ›

Devuelve la lista de incidentes de integridad detectados.

POST /api/security/integrity/restore Restaurar archivos desde backup Admin ›

Restaura archivos modificados o eliminados desde la copia de seguridad.

POST /api/security/integrity/full-test Test completo para reactivación Admin ›

Ejecuta un test completo de integridad necesario antes de la reactivación del sistema.

POST /api/security/integrity/upload-agent Subir nuevo archivo de agente Admin ›

Sube un nuevo archivo de agente para reemplazar el existente.

GET /api/security/lockdown/status Estado de lockdown Admin ›

Devuelve si el sistema está actualmente en modo lockdown.

POST /api/security/lockdown/reactivate Reactivar web tras lockdown Admin ›

Reactiva el servicio web después de un lockdown de seguridad.

GET /api/security/groq/status Estado de Groq AI Security Admin ›

Devuelve el estado de la integración con Groq para análisis de seguridad con IA.

PUT /api/security/groq/config Actualizar API key de Groq Admin ›

Actualiza la clave de API de Groq para el módulo de seguridad.

POST /api/security/analyze Analizar texto con IA Admin ›

Envía texto para ser analizado por IA en busca de amenazas de seguridad.

WebSocket — Protocolo de señalado

El servidor WebSocket en wss://terminalserver.es/ws gestiona el intercambio de SDP/ICE para establecer conexiones WebRTC P2P.

Mensajes del cliente → servidor

JSON

// Crear sala (anfitrión)
{ "type": "create-room", "code": "482719" }

// Unirse a sala (cliente)
{ "type": "join-room", "code": "482719" }

// Enviar señal WebRTC (SDP offer/answer, ICE candidate)
{ "type": "signal", "data": { "type": "offer", "sdp": "..." } }

// Chat (sin conexión P2P)
{ "type": "chat", "msg": "Hola" }

// Ping de latencia
{ "type": "ping", "ts": 1700000000000 }

Mensajes servidor → cliente

JSON

// Bienvenida al conectar
{ "type": "welcome", "clientId": "abc123", "ts": 1700000000000 }

// Sala creada
{ "type": "room-created", "code": "482719", "expires": 1700000600000 }

// Cliente unido
{ "type": "joined", "code": "482719" }

// Nuevo cliente en la sala (al host)
{ "type": "client-joined", "clientId": "def456" }

// Señal WebRTC recibida
{ "type": "signal", "from": "host", "data": { ... } }

// Chat
{ "type": "chat", "from": "abc123", "msg": "Hola", "ts": ... }

// Host desconectado
{ "type": "host-disconnected" }

// Código expirado
{ "type": "room-expired" }

// Pong
{ "type": "pong", "ts": 1700000000000, "serverTs": ... }

// Error
{ "type": "error", "msg": "Código no encontrado" }

API Reference

Introducción

Autenticación

Códigos de error

Auth

2FA — Autenticación en dos pasos

Tickets de soporte

Sesiones remotas

Utilidades de red

Admin

Billing & Payments

Admin: Coupons

Admin: PayPal

Admin: Email

Email Preferences

Security & Integrity

WebSocket — Protocolo de señalado

Mensajes del cliente → servidor

Mensajes servidor → cliente