# API Reference

## Vision General

La API de MSP Monitor Dashboard utiliza [tRPC](https://trpc.io/) para comunicacion type-safe entre frontend y backend. Todos los endpoints estan disponibles bajo `/api/trpc`.

## Autenticacion

### Login con Email/Password

```typescript
// 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

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

### Logout

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

### Usuario Actual

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

## Clientes (Tenants)

### Listar Clientes

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

### Obtener Cliente

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

### Crear Cliente

```typescript
// 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

```typescript
// 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

```typescript
// 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

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

### Obtener Metricas

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

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

### Obtener Ubicacion

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

### Solicitar Ubicacion

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

### Bloquear/Desbloquear

```typescript
// 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

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

### Enviar Mensaje

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

### Borrar Datos (Factory Reset)

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

### Instalar/Desinstalar App

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

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

### Resolver Alerta

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

### Conteo de Alertas Activas

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

## Reglas de Alerta

### Listar Reglas

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

### Crear Regla

```typescript
// 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

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

### Reporte de Uptime

```typescript
// 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

```typescript
// 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

```typescript
// 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

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

### Crear Usuario

```typescript
// 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

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

## Configuracion

### Obtener Configuracion

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

### Establecer Configuracion

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

### Estado de Integraciones

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

### Configurar MeshCentral

```typescript
// 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:

```json
{
  "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"
}
```