MSP-CAS/docs/api/README.md

API Reference

Vision General

La API de MSP Monitor Dashboard utiliza tRPC para comunicacion type-safe entre frontend y backend. Todos los endpoints estan disponibles bajo /api/trpc.

Autenticacion

Login con Email/Password

// POST /api/trpc/auth.login
const result = await trpc.auth.login.mutate({
  email: "usuario@example.com",
  password: "password123"
})
// Returns: { success: true, user: { id, email, nombre, rol } }

Login con MeshCentral SSO

// POST /api/trpc/auth.loginMeshCentral
const result = await trpc.auth.loginMeshCentral.mutate({
  username: "meshuser",
  token: "mesh-auth-token"
})

Logout

// POST /api/trpc/auth.logout
await trpc.auth.logout.mutate()

Usuario Actual

// GET /api/trpc/auth.me
const user = await trpc.auth.me.query()
// Returns: { id, email, nombre, rol, cliente, permisos }

Clientes (Tenants)

Listar Clientes

// GET /api/trpc/clientes.list
const { clientes, pagination } = await trpc.clientes.list.query({
  search: "term",
  activo: true,
  page: 1,
  limit: 20
})

Obtener Cliente

// GET /api/trpc/clientes.byId
const cliente = await trpc.clientes.byId.query({ id: "client-id" })

Crear Cliente

// POST /api/trpc/clientes.create
const cliente = await trpc.clientes.create.mutate({
  nombre: "Empresa XYZ",
  codigo: "XYZ",
  email: "contacto@xyz.com",
  meshcentralGrupo: "mesh-group-id"
})

Estadisticas del Dashboard

// GET /api/trpc/clientes.dashboardStats
const stats = await trpc.clientes.dashboardStats.query({
  clienteId: "optional-client-id"
})
// Returns: {
//   totalDispositivos, dispositivosOnline, dispositivosOffline,
//   dispositivosAlerta, alertasActivas, alertasCriticas
// }

Equipos (PC/Laptop/Servidor)

Listar Equipos

// GET /api/trpc/equipos.list
const { dispositivos, pagination } = await trpc.equipos.list.query({
  clienteId: "client-id",
  tipo: "SERVIDOR", // PC | LAPTOP | SERVIDOR
  estado: "ONLINE", // ONLINE | OFFLINE | ALERTA | MANTENIMIENTO
  search: "term",
  page: 1,
  limit: 20
})

Obtener Equipo

// GET /api/trpc/equipos.byId
const equipo = await trpc.equipos.byId.query({ id: "device-id" })
// Incluye: cliente, ubicacion, software, alertas activas

Obtener Metricas

// GET /api/trpc/equipos.metricas
const metricas = await trpc.equipos.metricas.query({
  dispositivoId: "device-id",
  periodo: "24h" // 1h | 6h | 24h | 7d | 30d
})

Iniciar Sesion Remota

// POST /api/trpc/equipos.iniciarSesion
const { sesionId, url } = await trpc.equipos.iniciarSesion.mutate({
  dispositivoId: "device-id",
  tipo: "desktop" // desktop | terminal | files
})
// Redirigir a `url` para abrir conexion

Ejecutar Comando

// POST /api/trpc/equipos.ejecutarComando
const resultado = await trpc.equipos.ejecutarComando.mutate({
  dispositivoId: "device-id",
  comando: "Get-Process",
  tipo: "powershell" // powershell | cmd | bash
})
// Returns: { success: true, output: "..." }

Reiniciar/Apagar

// POST /api/trpc/equipos.reiniciar
await trpc.equipos.reiniciar.mutate({ dispositivoId: "device-id" })

// POST /api/trpc/equipos.apagar
await trpc.equipos.apagar.mutate({ dispositivoId: "device-id" })

Celulares (MDM)

Listar Celulares

// GET /api/trpc/celulares.list
const { dispositivos, pagination } = await trpc.celulares.list.query({
  clienteId: "client-id",
  estado: "ONLINE",
  search: "term"
})

Obtener Ubicacion

// GET /api/trpc/celulares.ubicacion
const { lat, lng, updatedAt } = await trpc.celulares.ubicacion.query({
  dispositivoId: "device-id"
})

Solicitar Ubicacion

// POST /api/trpc/celulares.solicitarUbicacion
await trpc.celulares.solicitarUbicacion.mutate({
  dispositivoId: "device-id"
})

Bloquear/Desbloquear

// POST /api/trpc/celulares.bloquear
await trpc.celulares.bloquear.mutate({
  dispositivoId: "device-id",
  mensaje: "Dispositivo bloqueado por seguridad"
})

// POST /api/trpc/celulares.desbloquear
await trpc.celulares.desbloquear.mutate({
  dispositivoId: "device-id"
})

Hacer Sonar

// POST /api/trpc/celulares.sonar
await trpc.celulares.sonar.mutate({
  dispositivoId: "device-id"
})

Enviar Mensaje

// POST /api/trpc/celulares.enviarMensaje
await trpc.celulares.enviarMensaje.mutate({
  dispositivoId: "device-id",
  mensaje: "Mensaje para el usuario"
})

Borrar Datos (Factory Reset)

// POST /api/trpc/celulares.borrarDatos
// CUIDADO: Esta accion es irreversible
await trpc.celulares.borrarDatos.mutate({
  dispositivoId: "device-id"
})

Instalar/Desinstalar App

// POST /api/trpc/celulares.instalarApp
await trpc.celulares.instalarApp.mutate({
  dispositivoId: "device-id",
  packageName: "com.example.app"
})

// POST /api/trpc/celulares.desinstalarApp
await trpc.celulares.desinstalarApp.mutate({
  dispositivoId: "device-id",
  packageName: "com.example.app"
})

Red (SNMP/NetFlow)

Listar Dispositivos de Red

// GET /api/trpc/red.list
const { dispositivos, pagination } = await trpc.red.list.query({
  clienteId: "client-id",
  tipo: "ROUTER", // ROUTER | SWITCH | FIREWALL | AP | IMPRESORA | OTRO
  estado: "ONLINE"
})

Obtener Interfaces

// GET /api/trpc/red.interfaces
const interfaces = await trpc.red.interfaces.query({
  dispositivoId: "device-id"
})
// Returns: [{ ifName, ifAlias, ifSpeed, ifOperStatus, ifInOctets_rate, ifOutOctets_rate }]

Obtener Trafico

// GET /api/trpc/red.trafico
const datos = await trpc.red.trafico.query({
  dispositivoId: "device-id",
  portId: 123,
  periodo: "24h"
})
// Returns: [{ timestamp, in, out }]

Obtener Topologia

// GET /api/trpc/red.topologia
const { nodes, links } = await trpc.red.topologia.query({
  clienteId: "client-id"
})
// Para visualizacion con D3.js o similar

Alertas

Listar Alertas

// GET /api/trpc/alertas.list
const { alertas, pagination } = await trpc.alertas.list.query({
  clienteId: "client-id",
  estado: "ACTIVA", // ACTIVA | RECONOCIDA | RESUELTA
  severidad: "CRITICAL", // INFO | WARNING | CRITICAL
  dispositivoId: "device-id",
  desde: new Date("2024-01-01"),
  hasta: new Date("2024-01-31")
})

Reconocer Alerta

// POST /api/trpc/alertas.reconocer
await trpc.alertas.reconocer.mutate({ id: "alert-id" })

Resolver Alerta

// POST /api/trpc/alertas.resolver
await trpc.alertas.resolver.mutate({ id: "alert-id" })

Conteo de Alertas Activas

// GET /api/trpc/alertas.conteoActivas
const { total, critical, warning, info } = await trpc.alertas.conteoActivas.query({
  clienteId: "client-id"
})

Reglas de Alerta

Listar Reglas

// GET /api/trpc/alertas.reglas.list
const reglas = await trpc.alertas.reglas.list.query({
  clienteId: "client-id"
})

Crear Regla

// POST /api/trpc/alertas.reglas.create
const regla = await trpc.alertas.reglas.create.mutate({
  clienteId: "client-id", // null para regla global
  nombre: "CPU Alta",
  metrica: "cpu",
  operador: ">",
  umbral: 90,
  duracionMinutos: 5,
  severidad: "WARNING",
  notificarEmail: true,
  notificarSms: false
})

Reportes

Reporte de Inventario

// GET /api/trpc/reportes.inventario
const { dispositivos, resumen } = await trpc.reportes.inventario.query({
  clienteId: "client-id",
  tipo: "SERVIDOR"
})

Reporte de Uptime

// GET /api/trpc/reportes.uptime
const { dispositivos, promedioGeneral } = await trpc.reportes.uptime.query({
  clienteId: "client-id",
  desde: new Date("2024-01-01"),
  hasta: new Date("2024-01-31")
})

Reporte de Alertas

// GET /api/trpc/reportes.alertas
const { alertas, resumen } = await trpc.reportes.alertas.query({
  clienteId: "client-id",
  desde: new Date("2024-01-01"),
  hasta: new Date("2024-01-31")
})

Exportar a CSV

// POST /api/trpc/reportes.exportarCSV
const { filename, content, contentType } = await trpc.reportes.exportarCSV.mutate({
  tipo: "inventario", // inventario | alertas | actividad
  clienteId: "client-id"
})
// Descargar el contenido como archivo CSV

Usuarios

Listar Usuarios

// GET /api/trpc/usuarios.list
const { usuarios, pagination } = await trpc.usuarios.list.query({
  clienteId: "client-id",
  rol: "TECNICO",
  activo: true
})

Crear Usuario

// POST /api/trpc/usuarios.create
const usuario = await trpc.usuarios.create.mutate({
  email: "nuevo@example.com",
  nombre: "Nuevo Usuario",
  password: "password123",
  clienteId: "client-id",
  rol: "TECNICO"
})

Resetear Password

// POST /api/trpc/usuarios.resetPassword
await trpc.usuarios.resetPassword.mutate({
  id: "user-id",
  newPassword: "newpassword123"
})

Configuracion

Obtener Configuracion

// GET /api/trpc/configuracion.get
const config = await trpc.configuracion.get.query({
  clave: "smtp_host"
})

Establecer Configuracion

// POST /api/trpc/configuracion.set
await trpc.configuracion.set.mutate({
  clave: "smtp_host",
  valor: "smtp.gmail.com",
  tipo: "string",
  categoria: "notificacion"
})

Estado de Integraciones

// GET /api/trpc/configuracion.integraciones.status
const { meshcentral, librenms, headwind } = await trpc.configuracion.integraciones.status.query()
// Returns: { configurado: boolean, url?: string }

Configurar MeshCentral

// POST /api/trpc/configuracion.integraciones.setMeshCentral
await trpc.configuracion.integraciones.setMeshCentral.mutate({
  url: "https://mesh.tudominio.com",
  user: "admin",
  password: "password",
  domain: "default"
})

Codigos de Error

Codigo	Descripcion
UNAUTHORIZED	No autenticado
FORBIDDEN	Sin permisos
NOT_FOUND	Recurso no encontrado
CONFLICT	Conflicto (ej: email duplicado)
BAD_REQUEST	Request invalido
INTERNAL_SERVER_ERROR	Error del servidor

Rate Limiting

• API general: 100 requests/minuto
• Autenticacion: 10 requests/minuto
• Acciones sensibles (wipe, commands): 5 requests/minuto

Webhooks

Las alertas pueden enviar webhooks a URLs configuradas:

{
  "id": "alert-id",
  "severidad": "CRITICAL",
  "titulo": "Servidor offline",
  "mensaje": "El servidor SRV-01 no responde",
  "dispositivo": "SRV-01",
  "cliente": "Cliente A",
  "timestamp": "2024-01-15T10:30:00Z"
}