API REST de SIVA

Documentación de referencia de la API del backend (backend/). Todos los endpoints se montan bajo el prefijo /api salvo la interfaz de Swagger. La fuente interactiva está en /api/docs (Swagger UI) y el contrato máquina-legible en /api/docs.json y openapi.yaml.

Convenciones generales

Aspecto	Detalle
Base URL (dev)	`http://localhost:3000/api`
Formato	JSON (`Content-Type: application/json`); subidas con `multipart/form-data`
Autenticación	`Authorization: Bearer <accessToken>`
Envoltura de éxito	`{ "success": true, "data": ... }`
Envoltura de error	`{ "success": false, "error": { "code", "message", "details?" } }`
Paginación	`?page=1&limit=50`; respuesta con `total`, `page`, `limit`, `totalPages`
Rate limit global	200 req / 15 min por IP (`RATE_LIMIT_MAX`/`RATE_LIMIT_WINDOW_MS`)
Rate limit sensible	10 req / 15 min en login, refresh, forgot/reset password y verify-email
Cabecera de traza	`X-Request-Id` (generada por `requestId`)

Roles

requireRole(ADMIN) autoriza a ADMIN y SUPERADMIN; requireRole(ADMIN, SUPERVISOR) autoriza a ADMIN, SUPERVISOR y SUPERADMIN. SUPERADMIN siempre pasa (backend/src/middlewares/role.middleware.ts). Los roles válidos son SUPERADMIN, ADMIN, SUPERVISOR.

Tras la revisión de permisos, las rutas operativas (catálogos, convocatorias, ejercicios, ubicaciones, vigilantes, asignaciones, notificación, asistencia y configuración) admiten ADMIN y SUPERVISOR. Solo Usuarios y Plantillas permanecen restringidos a ADMIN. Dentro de Configuración, un SUPERVISOR recibe 403 al intentar modificar las claves reservadas a ADMIN (colores_miembros_tribunal, colores_roles_usuarios, envio_correos_vigilantes, etiqueta_colores_predefinidos, export_field_labels, penalizacion_duracion_dias, penalizacion_habilitada, modo_asignacion_aulas_default).

Códigos de error comunes

HTTP	`code`	Causa
400	`VALIDATION_ERROR`	Body/query inválido (Zod). Incluye `details[]` por campo.
400	`BAD_REQUEST`	Petición semánticamente incorrecta.
401	`UNAUTHORIZED`	Sin token, token inválido/caducado, credenciales incorrectas, usuario inactivo o email no verificado.
403	`FORBIDDEN`	Autenticado pero sin permisos, o acceso a 1:1 ajeno.
404	`NOT_FOUND`	Recurso inexistente.
409	`CONFLICT`	Conflicto de unicidad o regla de negocio.
429	`RATE_LIMIT_EXCEEDED`	Se superó el límite de peticiones.
500	`INTERNAL_SERVER_ERROR`	Error no controlado.

Paginación

La mayoría de listados devuelven:

json

{
  "success": true,
  "data": {
    "data": [],
    "total": 123,
    "page": 1,
    "limit": 50,
    "totalPages": 3
  }
}

⚠️ Excepción: GET /api/users devuelve { items, meta: { total, page, limit, totalPages } }.

Flujo de autenticación

Tabla resumen de endpoints

Autenticación — `/api/auth`

Método	Ruta	Descripción	Auth / Rol
POST	`/api/auth/login`	Iniciar sesión	No
POST	`/api/auth/logout`	Cerrar sesión	Sí (cualquiera)
POST	`/api/auth/refresh-token`	Renovar access token	No
POST	`/api/auth/change-password`	Cambiar contraseña propia	Sí (cualquiera)
POST	`/api/auth/forgot-password`	Solicitar restablecimiento	No
POST	`/api/auth/reset-password`	Restablecer con token	No
POST	`/api/auth/verify-email`	Verificar correo	No
GET	`/api/auth/me`	Usuario autenticado	Sí (cualquiera)

Usuarios — `/api/users`

Método	Ruta	Descripción	Auth / Rol
GET	`/api/users/me`	Perfil propio	Sí (cualquiera)
PUT	`/api/users/me`	Actualizar perfil propio	Sí (cualquiera)
POST	`/api/users/me/avatar`	Subir avatar	Sí (cualquiera)
DELETE	`/api/users/me/avatar`	Eliminar avatar	Sí (cualquiera)
GET	`/api/users`	Listar usuarios	Sí (ADMIN)
GET	`/api/users/:id`	Obtener usuario	Sí (ADMIN)
POST	`/api/users`	Crear usuario	Sí (ADMIN)
PUT	`/api/users/:id`	Actualizar usuario	Sí (ADMIN)
DELETE	`/api/users/:id`	Eliminar usuario	Sí (ADMIN)
PATCH	`/api/users/:id/status`	Activar/desactivar	Sí (ADMIN)

Vigilantes — `/api/vigilantes`

Método	Ruta	Descripción	Auth / Rol
GET	`/api/vigilantes`	Listar vigilantes	Sí (ADMIN, SUPERVISOR)
GET	`/api/vigilantes/:id`	Obtener vigilante	Sí (ADMIN, SUPERVISOR)
GET	`/api/vigilantes/:id/historial-asistencia`	Historial de asistencia	Sí (ADMIN, SUPERVISOR)
GET	`/api/vigilantes/:id/penalizaciones`	Penalizaciones del vigilante	Sí (ADMIN, SUPERVISOR)
POST	`/api/vigilantes`	Crear vigilante	Sí (ADMIN, SUPERVISOR)
PUT	`/api/vigilantes/:id`	Actualizar vigilante	Sí (ADMIN, SUPERVISOR)
DELETE	`/api/vigilantes/:id`	Eliminar vigilante	Sí (ADMIN, SUPERVISOR)
POST	`/api/vigilantes/import/preview`	Previsualizar importación	Sí (ADMIN, SUPERVISOR)
POST	`/api/vigilantes/import/execute`	Ejecutar importación	Sí (ADMIN, SUPERVISOR)
PUT	`/api/vigilantes/:id/toggle-bloqueado`	Bloquear/desbloquear	Sí (ADMIN, SUPERVISOR)

Etiquetas — `/api/tags`

Método	Ruta	Descripción	Auth / Rol
GET	`/api/tags`	Listar etiquetas	Sí (ADMIN, SUPERVISOR)
POST	`/api/tags`	Crear etiqueta	Sí (ADMIN, SUPERVISOR)
PUT	`/api/tags/:id`	Actualizar etiqueta	Sí (ADMIN, SUPERVISOR)
DELETE	`/api/tags/:id`	Eliminar etiqueta	Sí (ADMIN, SUPERVISOR)

Sedes — `/api/sedes`

Método	Ruta	Descripción	Auth / Rol
GET	`/api/sedes`	Listar sedes	Sí (ADMIN, SUPERVISOR)
GET	`/api/sedes/municipios`	Municipios distintos	Sí (ADMIN, SUPERVISOR)
GET	`/api/sedes/provincias`	Provincias distintas	Sí (ADMIN, SUPERVISOR)
GET	`/api/sedes/:id`	Obtener sede	Sí (ADMIN, SUPERVISOR)
POST	`/api/sedes`	Crear sede	Sí (ADMIN, SUPERVISOR)
PUT	`/api/sedes/:id`	Actualizar sede	Sí (ADMIN, SUPERVISOR)
DELETE	`/api/sedes/:id`	Eliminar sede	Sí (ADMIN, SUPERVISOR)
PUT	`/api/sedes/:id/toggle-active`	Activar/desactivar	Sí (ADMIN, SUPERVISOR)

Edificios — `/api/edificios`

Método	Ruta	Descripción	Auth / Rol
GET	`/api/edificios`	Listar edificios	Sí (ADMIN, SUPERVISOR)
GET	`/api/edificios/:id`	Obtener edificio	Sí (ADMIN, SUPERVISOR)
POST	`/api/edificios`	Crear edificio	Sí (ADMIN, SUPERVISOR)
PUT	`/api/edificios/:id`	Actualizar edificio	Sí (ADMIN, SUPERVISOR)
DELETE	`/api/edificios/:id`	Eliminar edificio	Sí (ADMIN, SUPERVISOR)

Aulas — `/api/aulas`

Método	Ruta	Descripción	Auth / Rol
GET	`/api/aulas`	Listar aulas	Sí (ADMIN, SUPERVISOR)
GET	`/api/aulas/:id`	Obtener aula	Sí (ADMIN, SUPERVISOR)
POST	`/api/aulas`	Crear aula	Sí (ADMIN, SUPERVISOR)
PUT	`/api/aulas/:id`	Actualizar aula	Sí (ADMIN, SUPERVISOR)
DELETE	`/api/aulas/:id`	Eliminar aula	Sí (ADMIN, SUPERVISOR)

Plantas — `/api/plantas`

Método	Ruta	Descripción	Auth / Rol
GET	`/api/plantas`	Listar plantas	Sí (ADMIN, SUPERVISOR)
POST	`/api/plantas`	Crear planta	Sí (ADMIN, SUPERVISOR)
PUT	`/api/plantas/:id`	Actualizar planta	Sí (ADMIN, SUPERVISOR)
DELETE	`/api/plantas/:id`	Eliminar planta	Sí (ADMIN, SUPERVISOR)
GET	`/api/plantas/edificio/:edificioId`	Plantas de un edificio	Sí (ADMIN, SUPERVISOR)
POST	`/api/plantas/edificio/:edificioId/assign/:plantaId`	Asignar planta	Sí (ADMIN, SUPERVISOR)
DELETE	`/api/plantas/edificio/:edificioId/assign/:plantaId`	Desasignar planta	Sí (ADMIN, SUPERVISOR)

Convocatorias — `/api/convocatorias`

Método	Ruta	Descripción	Auth / Rol
GET	`/api/convocatorias`	Listar convocatorias	Sí (ADMIN, SUPERVISOR)
GET	`/api/convocatorias/:id`	Obtener convocatoria	Sí (ADMIN, SUPERVISOR)
POST	`/api/convocatorias`	Crear convocatoria	Sí (ADMIN, SUPERVISOR)
PUT	`/api/convocatorias/:id`	Actualizar convocatoria	Sí (ADMIN, SUPERVISOR)
PUT	`/api/convocatorias/:id/estado`	Cambiar estado	Sí (ADMIN, SUPERVISOR)
DELETE	`/api/convocatorias/:id`	Eliminar convocatoria	Sí (ADMIN, SUPERVISOR)

Tipos de ejercicio — `/api/tipos-ejercicio`

Método	Ruta	Descripción	Auth / Rol
GET	`/api/tipos-ejercicio`	Listar tipos	Sí (ADMIN, SUPERVISOR)
POST	`/api/tipos-ejercicio`	Crear tipo	Sí (ADMIN, SUPERVISOR)
PUT	`/api/tipos-ejercicio/:id`	Actualizar tipo	Sí (ADMIN, SUPERVISOR)
DELETE	`/api/tipos-ejercicio/:id`	Eliminar tipo	Sí (ADMIN, SUPERVISOR)

Tribunal — `/api/tribunal-miembros`

Método	Ruta	Descripción	Auth / Rol
GET	`/api/tribunal-miembros`	Listar miembros	Sí (cualquiera)
GET	`/api/tribunal-miembros/:id`	Obtener miembro	Sí (cualquiera)
POST	`/api/tribunal-miembros`	Crear miembro	Sí (ADMIN, SUPERVISOR)
PUT	`/api/tribunal-miembros/:id`	Actualizar miembro	Sí (ADMIN, SUPERVISOR)
PUT	`/api/tribunal-miembros/:id/toggle-renuncia`	Marcar/desmarcar renuncia	Sí (ADMIN, SUPERVISOR)
DELETE	`/api/tribunal-miembros/:id`	Eliminar miembro	Sí (ADMIN, SUPERVISOR)

Ejercicios — `/api/ejercicios`

Método	Ruta	Descripción	Auth / Rol
GET	`/api/ejercicios`	Listar ejercicios	Sí (ADMIN, SUPERVISOR)
GET	`/api/ejercicios/:id`	Obtener ejercicio	Sí (ADMIN, SUPERVISOR)
POST	`/api/ejercicios`	Crear ejercicio	Sí (ADMIN, SUPERVISOR)
PUT	`/api/ejercicios/:id`	Actualizar ejercicio	Sí (ADMIN, SUPERVISOR)
DELETE	`/api/ejercicios/:id`	Eliminar ejercicio	Sí (ADMIN, SUPERVISOR)
GET	`/api/ejercicios/:id/impacto-cierre`	Advertencias de cierre	Sí (ADMIN, SUPERVISOR)
PUT	`/api/ejercicios/:id/estado`	Cambiar estado (cerrar/reabrir)	Sí (ADMIN, SUPERVISOR)
GET	`/api/ejercicios/:ejercicioId/sedes`	Sedes del ejercicio	Sí (ADMIN, SUPERVISOR)
POST	`/api/ejercicios/:ejercicioId/sedes`	Añadir sede	Sí (ADMIN, SUPERVISOR)
DELETE	`/api/ejercicios/:ejercicioId/sedes/:id`	Quitar sede	Sí (ADMIN, SUPERVISOR)
GET	`/api/ejercicios/:ejercicioId/sedes/:ejercicioSedeId/aulas`	Aulas de la sede	Sí (ADMIN, SUPERVISOR)
POST	`/api/ejercicios/:ejercicioId/sedes/:ejercicioSedeId/aulas`	Añadir aula	Sí (ADMIN, SUPERVISOR)
DELETE	`/api/ejercicios/:ejercicioId/sedes/:ejercicioSedeId/aulas/:id`	Quitar aula	Sí (ADMIN, SUPERVISOR)
GET	`/api/ejercicios/:ejercicioId/vigilantes`	Vigilantes del ejercicio	Sí (ADMIN, SUPERVISOR)
GET	`/api/ejercicios/:ejercicioId/vigilantes/disponibles`	Vigilantes disponibles	Sí (ADMIN, SUPERVISOR)
POST	`/api/ejercicios/:ejercicioId/vigilantes`	Seleccionar vigilantes	Sí (ADMIN, SUPERVISOR)
DELETE	`/api/ejercicios/:ejercicioId/vigilantes/:vigilanteId`	Quitar vigilante	Sí (ADMIN, SUPERVISOR)
GET	`/api/ejercicios/:ejercicioId/vigilantes/export`	Exportar vigilantes (Excel)	Sí (ADMIN, SUPERVISOR)
GET	`/api/ejercicios/:ejercicioId/ubicaciones`	Estructura de ubicaciones	Sí (ADMIN, SUPERVISOR)
PUT	`/api/ejercicios/:ejercicioId/ubicaciones`	Guardar ubicaciones	Sí (ADMIN, SUPERVISOR)
POST	`/api/ejercicios/:ejercicioId/ubicaciones/validar`	Validar ubicaciones	Sí (ADMIN, SUPERVISOR)
GET	`/api/ejercicios/:ejercicioId/grupos-vigilantes`	Grupos y vigilantes	Sí (ADMIN, SUPERVISOR)
PUT	`/api/ejercicios/:ejercicioId/grupos-vigilantes`	Guardar grupos	Sí (ADMIN, SUPERVISOR)
POST	`/api/ejercicios/:ejercicioId/penalizaciones`	Registrar no asistidos	Sí (ADMIN, SUPERVISOR)
GET	`/api/ejercicios/:ejercicioId/penalizaciones`	Penalizaciones activas	Sí (ADMIN, SUPERVISOR)

Asignación rápida (simulación) — `/api/ejercicios`

Método	Ruta	Descripción	Auth / Rol
GET	`/api/ejercicios/:id/simulation-meta`	Meta de la ventana	Sí (ADMIN, SUPERVISOR)
POST	`/api/ejercicios/:id/simulate`	Generar propuesta	Sí (ADMIN, SUPERVISOR)
POST	`/api/ejercicios/:id/apply-simulation`	Aplicar propuesta	Sí (ADMIN, SUPERVISOR)
GET	`/api/ejercicios/:id/export-asignaciones`	Exportar asignaciones	Sí (ADMIN, SUPERVISOR)
GET	`/api/ejercicios/:id/control-asistencia`	Documento de control	Sí (ADMIN, SUPERVISOR)

Asignaciones — `/api/asignaciones`

Método	Ruta	Descripción	Auth / Rol
GET	`/api/asignaciones`	Listar asignaciones	Sí (ADMIN, SUPERVISOR)
GET	`/api/asignaciones/:id`	Obtener asignación	Sí (ADMIN, SUPERVISOR)
POST	`/api/asignaciones`	Crear asignación manual	Sí (ADMIN, SUPERVISOR)
PUT	`/api/asignaciones/:id`	Actualizar asignación	Sí (ADMIN, SUPERVISOR)
DELETE	`/api/asignaciones/:id`	Eliminar asignación	Sí (ADMIN, SUPERVISOR)
POST	`/api/asignaciones/auto`	Auto-asignar	Sí (ADMIN, SUPERVISOR)
PUT	`/api/asignaciones/:id/anular-asistencia`	Anular asistencia	Sí (ADMIN, SUPERVISOR)
PUT	`/api/asignaciones/:id/restaurar-asistencia`	Restaurar asistencia	Sí (ADMIN, SUPERVISOR)

Llamamientos — `/api`

Método	Ruta	Descripción	Auth / Rol
GET	`/api/ejercicios/:ejercicioId/llamamientos`	Llamamientos del ejercicio	Sí (ADMIN, SUPERVISOR)
POST	`/api/ejercicios/:ejercicioId/llamamientos`	Crear llamamiento	Sí (ADMIN, SUPERVISOR)
GET	`/api/llamamientos/:id`	Obtener llamamiento	Sí (ADMIN, SUPERVISOR)
DELETE	`/api/llamamientos/:id`	Eliminar llamamiento	Sí (ADMIN, SUPERVISOR)
GET	`/api/llamamientos/:id/impacto-anulacion`	Impacto de anulación	Sí (ADMIN, SUPERVISOR)
POST	`/api/llamamientos/:id/anular`	Anular llamamiento	Sí (ADMIN, SUPERVISOR)
GET	`/api/llamamientos/:id/correos`	Correos del llamamiento	Sí (ADMIN, SUPERVISOR)
POST	`/api/vigilante-llamamientos/:id/confirmar`	Confirmar vigilante	Sí (ADMIN, SUPERVISOR)
POST	`/api/vigilante-llamamientos/:id/rechazar`	Rechazar vigilante	Sí (ADMIN, SUPERVISOR)
POST	`/api/vigilante-llamamientos/:id/desconfirmar`	Desconfirmar	Sí (ADMIN, SUPERVISOR)
PATCH	`/api/vigilante-llamamientos/:id/sede`	Editar sede preferida	Sí (ADMIN, SUPERVISOR)
GET	`/api/ejercicios/:ejercicioId/confirmaciones/pendientes`	Confirmaciones pendientes	Sí (ADMIN, SUPERVISOR)
POST	`/api/ejercicios/:ejercicioId/confirmaciones/importar-excel`	Previsualizar importación	Sí (ADMIN, SUPERVISOR)
POST	`/api/ejercicios/:ejercicioId/confirmaciones/aplicar-excel`	Aplicar importación	Sí (ADMIN, SUPERVISOR)
POST	`/api/vigilante-llamamientos/:id/reenviar-correo`	Reenviar correo	Sí (ADMIN, SUPERVISOR)

Notificaciones — `/api`

Método	Ruta	Descripción	Auth / Rol
GET	`/api/ejercicios/:ejercicioId/notificaciones`	Notificaciones del ejercicio	Sí (ADMIN, SUPERVISOR)
POST	`/api/ejercicios/:ejercicioId/notificaciones`	Crear notificación (multipart, hasta 10 archivos)	Sí (ADMIN, SUPERVISOR)
GET	`/api/notificaciones/:id`	Obtener notificación	Sí (ADMIN, SUPERVISOR)
POST	`/api/notificaciones/:id/anular`	Anular notificación	Sí (ADMIN, SUPERVISOR)
POST	`/api/notificaciones/:id/documentos`	Añadir documento	Sí (ADMIN, SUPERVISOR)
DELETE	`/api/notificaciones/:id/documentos/:documentoId`	Eliminar documento	Sí (ADMIN, SUPERVISOR)
POST	`/api/notificacion-vigilantes/:id/reenviar-correo`	Reenviar correo individual	Sí (ADMIN, SUPERVISOR)
POST	`/api/notificaciones/:id/reenviar`	Reenviar notificación	Sí (ADMIN, SUPERVISOR)
GET	`/api/ejercicios/:ejercicioId/documentos`	Documentos del ejercicio	Sí (ADMIN, SUPERVISOR)
POST	`/api/ejercicios/:ejercicioId/documentos`	Subir documento de ejercicio	Sí (ADMIN, SUPERVISOR)
DELETE	`/api/ejercicios/:ejercicioId/documentos/:documentoId`	Eliminar documento	Sí (ADMIN, SUPERVISOR)

Plantillas de email — `/api/templates`

Método	Ruta	Descripción	Auth / Rol
GET	`/api/templates/types`	Tipos disponibles	Sí (ADMIN)
GET	`/api/templates`	Listar plantillas	Sí (ADMIN)
GET	`/api/templates/:id`	Obtener plantilla	Sí (ADMIN)
POST	`/api/templates`	Crear plantilla	Sí (ADMIN)
PUT	`/api/templates/:id`	Actualizar plantilla	Sí (ADMIN)
DELETE	`/api/templates/:id`	Eliminar plantilla	Sí (ADMIN)
PATCH	`/api/templates/:id/activate`	Activar/desactivar	Sí (ADMIN)
POST	`/api/templates/:id/preview`	Previsualizar	Sí (ADMIN)
GET	`/api/templates/active/:tipo`	Plantilla activa por tipo	Sí (ADMIN, SUPERVISOR)

Plantillas de documento — `/api/document-templates`

Método	Ruta	Descripción	Auth / Rol
GET	`/api/document-templates`	Listar plantillas	Sí (ADMIN, SUPERVISOR)
GET	`/api/document-templates/types`	Tipos disponibles	Sí (ADMIN, SUPERVISOR)
GET	`/api/document-templates/:id`	Obtener plantilla	Sí (ADMIN, SUPERVISOR)
POST	`/api/document-templates`	Crear plantilla	Sí (ADMIN, SUPERVISOR)
PUT	`/api/document-templates/:id`	Actualizar plantilla	Sí (ADMIN, SUPERVISOR)
POST	`/api/document-templates/:id/preview`	Previsualizar	Sí (ADMIN, SUPERVISOR)
DELETE	`/api/document-templates/:id`	Eliminar plantilla	Sí (ADMIN, SUPERVISOR)
PATCH	`/api/document-templates/:id/activate`	Activar/desactivar	Sí (ADMIN, SUPERVISOR)

Configuración — `/api/configuracion`

Método	Ruta	Descripción	Auth / Rol
GET	`/api/configuracion/colores-roles-usuarios`	Colores por rol	Sí (cualquiera)
GET	`/api/configuracion/colores-miembros-tribunal`	Colores de tribunal	Sí (cualquiera)
GET	`/api/configuracion/etiqueta-colores`	Colores de etiquetas	Sí (cualquiera)
GET	`/api/configuracion/pagina-ayuda/check`	Comprueba la URL de ayuda	Sí (cualquiera)
GET	`/api/configuracion`	Listar parámetros	Sí (ADMIN, SUPERVISOR)
PUT	`/api/configuracion/:clave`	Actualizar parámetro	Sí (ADMIN, SUPERVISOR*)

* El SUPERVISOR no puede modificar las claves reservadas a ADMIN (ver Roles). El intento responde 403.

Otros

Método	Ruta	Descripción	Auth / Rol
PUT	`/api/penalizaciones/:id/levantar`	Levantar penalización	Sí (ADMIN, SUPERVISOR)
GET	`/api/ubicaciones/usos`	Ejercicios abiertos que usan una ubicación	Sí (ADMIN, SUPERVISOR)
GET	`/api/summary`	KPIs del dashboard	Sí (ADMIN, SUPERVISOR)
GET	`/api/health`	Salud del servicio y BD	No
GET	`/api/files/download/:objectName`	Descargar fichero	No
GET	`/api/docs`	Swagger UI	No
GET	`/api/docs.json`	Especificación OpenAPI	No

1. Autenticación

Descripción: autentica con email y contraseña. Requiere cuenta activa y email verificado.
Autenticación: no.
Body:

json

{ "email": "superadmin@inap.es", "password": "********" }

Campo	Tipo	Requerido	Descripción
`email`	string (email)	Sí	Correo del usuario
`password`	string	Sí	Contraseña

Respuestas:
- 200:

json

{
  "success": true,
  "data": {
    "accessToken": "eyJ...",
    "refreshToken": "eyJ...",
    "user": { "id": "uuid", "name": "Super Administrador", "email": "superadmin@inap.es", "role": "SUPERADMIN" }
  }
}

401 credenciales inválidas, usuario inactivo o email no verificado.
429 demasiados intentos.
Errores comunes: contraseña incorrecta, cuenta desactivada, email sin verificar.

POST /api/auth/logout

Descripción: invalida el refresh_token del usuario autenticado.
Autenticación: requerida.
Body: ninguno.
Respuestas: 200 { success: true, data: null }; 401.

POST /api/auth/refresh-token

Descripción: emite un nuevo par de tokens si el refresh es válido y coincide con el almacenado (rotación).
Autenticación: no.
Body: { "refreshToken": "eyJ..." } (refreshToken requerido).
Respuestas:

json

{ "success": true, "data": { "accessToken": "eyJ...", "refreshToken": "eyJ..." } }

401 refresh inválido o usuario inactivo.
Errores comunes: token caducado, refresh ya rotado.

POST /api/auth/change-password

Descripción: cambia la contraseña del usuario autenticado.
Autenticación: requerida.
Body: { "currentPassword": "...", "newPassword": "..." }; newPassword debe cumplir la política (password-policy).
Respuestas: 200 { data: null }; 400 validación; 401 contraseña actual incorrecta.

POST /api/auth/forgot-password

Descripción: genera token de restablecimiento y envía email (respuesta genérica anti-enumeración).
Autenticación: no.
Body: { "email": "usuario@inap.es" }.
Respuestas: 200 { data: { message: "Si el email está registrado, ..." } }.

POST /api/auth/reset-password

Descripción: restablece la contraseña con token.
Autenticación: no.
Body: { "token": "...", "newPassword": "..." }.
Respuestas: 200 { data: { message: "Contraseña restablecida correctamente." } }; 400 token inválido/caducado.

POST /api/auth/verify-email

Descripción: verifica el correo con el token enviado.
Autenticación: no.
Body: { "token": "..." }.
Respuestas: 200 { data: { message: "Correo electrónico verificado correctamente." } }; 400.

GET /api/auth/me

Descripción: devuelve el usuario autenticado (con perfil).
Autenticación: requerida.
Respuestas: 200 { data: { id, name, email, role, profile? } }; 401.

2. Usuarios

GET /api/users/me

Descripción: perfil propio.
Autenticación: requerida.
Respuestas: 200 usuario con perfil; 401.

PUT /api/users/me

Descripción: actualiza nombre, email y perfil propios.
Autenticación: requerida.
Body:

json

{
  "name": "Nombre Apellidos",
  "email": "usuario@inap.es",
  "profile": { "dni": "12345678Z", "phone": "600000000", "company": "INAP", "notes": "" }
}

Campo	Tipo	Requerido
`name`	string (1..100)	No
`email`	string (email)	No
`profile.dni`	string (≤9) / null	No
`profile.phone`	string (≤20) / null	No
`profile.company`	string (≤255) / null	No
`profile.notes`	string / null	No

Respuestas: 200; 400; 409 email duplicado.

POST /api/users/me/avatar

Descripción: sube el avatar (multipart/form-data, campo avatar).
Autenticación: requerida.
Body: fichero de imagen (extensiones permitidas por STORAGE_ALLOWED_IMAGE_EXTENSIONS, tamaño máximo MAX_AVATAR_MB).
Respuestas: 200 con clave/URL del avatar; 400 tipo o tamaño no permitido.

DELETE /api/users/me/avatar

Descripción: elimina el avatar propio.
Autenticación: requerida.
Respuestas: 200.

GET /api/users

Descripción: lista paginada de usuarios.
Autenticación: requerida (ADMIN).
Query:

Param	Tipo	Requerido	Descripción
`page`	int ≥1	No	Página (def. 1)
`limit`	int 1..1000	No	Tamaño (def. 50)
`search`	string	No	Nombre o email
`role`	`SUPERADMIN\|ADMIN\|SUPERVISOR`	No	Filtro por rol
`isActive`	`true\|false`	No	Filtro por estado

Respuestas (forma especial):

json

{
  "success": true,
  "data": {
    "items": [
      { "id": "uuid", "name": "Laura", "email": "laura@inap.es", "role": "ADMIN", "is_active": true, "profile": null }
    ],
    "meta": { "total": 1, "page": 1, "limit": 50, "totalPages": 1 }
  }
}

GET /api/users/:id

Descripción: obtiene un usuario por UUID.
Autenticación: requerida (ADMIN).
Params: id (uuid).
Respuestas: 200; 404.

POST /api/users

Descripción: crea un usuario. Un ADMIN no puede crear ADMIN ni SUPERADMIN.
Autenticación: requerida (ADMIN).
Body: { "name", "email", "password", "role": "SUPERVISOR\|ADMIN" }.
Respuestas: 200/201; 400; 403 por jerarquía; 409 email duplicado.

PUT /api/users/:id

Descripción: actualiza nombre, email, rol y estado.
Autenticación: requerida (ADMIN).
Body: { "name?", "email?", "role?", "is_active?" }.
Respuestas: 200; 400; 404; 409.

DELETE /api/users/:id

Descripción: elimina/desactiva un usuario.
Autenticación: requerida (ADMIN).
Respuestas: 200; 404; 403 (no eliminarse a sí mismo / jerarquía).

PATCH /api/users/:id/status

Descripción: activa o desactiva un usuario.
Autenticación: requerida (ADMIN).
Body: { "is_active": true }.
Respuestas: 200; 404.

3. Vigilantes

GET /api/vigilantes

Descripción: lista paginada de vigilantes.
Autenticación: requerida (ADMIN, SUPERVISOR).
Query:

Param	Tipo	Requerido	Descripción
`page`	int ≥1	No	Página (def. 1)
`limit`	int (-1 o 1..1000)	No	Tamaño (`-1` = todos, def. 50)
`search`	string	No	Búsqueda sin acentos
`tags`	string	No	IDs de etiquetas
`bloqueado`	`true\|false`	No	Filtro de bloqueo
`fechaDesde` / `fechaHasta`	string	No	Rango de fechas

Respuestas: 200 paginado ({ data, total, page, limit, totalPages }).

GET /api/vigilantes/:id

Descripción: detalle de un vigilante.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

GET /api/vigilantes/:id/historial-asistencia

Descripción: historial de asistencia del vigilante.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200 { data: { ... } }; 404.

GET /api/vigilantes/:id/penalizaciones

Descripción: penalizaciones del vigilante.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

POST /api/vigilantes

Descripción: crea un vigilante (valida DNI/NIE).
Autenticación: requerida (ADMIN, SUPERVISOR).
Body:

json

{
  "dni": "12345678Z",
  "nombre": "Ana",
  "primer_apellido": "García",
  "segundo_apellido": "",
  "correo_electronico_corporativo": "ana@inap.es",
  "correo_electronico_personal": null,
  "telefono": "600000000",
  "tagIds": ["uuid-tag"],
  "bloqueado": false,
  "motivoBloqueo": null,
  "comentarios": null
}

Campo	Tipo	Requerido	Descripción
`dni`	string (NIF/NIE válido)	Sí	Documento
`nombre` / `primer_apellido`	string 1..100	Sí	Nombre y primer apellido
`segundo_apellido`	string ≤100	No	Se guarda `""` si vacío
`correo_electronico_corporativo` / `_personal`	string (email)	No	Correos
`telefono`	string ≤20	No	Teléfono
`tagIds`	uuid[]	No	Etiquetas
`bloqueado`	boolean	No	Def. `false`
`motivoBloqueo`	string ≤1000	No	—
`comentarios`	string	No	—

Respuestas: 200; 400 DNI inválido; 409 DNI duplicado.

PUT /api/vigilantes/:id

Descripción: actualiza un vigilante (incluye motivoDesbloqueo).
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: mismos campos que el alta, todos opcionales.
Respuestas: 200; 404; 409.

DELETE /api/vigilantes/:id

Descripción: elimina un vigilante.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404; 409 si está referenciado.

PUT /api/vigilantes/:id/toggle-bloqueado

Descripción: alterna el bloqueo, con motivo opcional.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "motivo": "Texto opcional" } (por defecto {}).
Respuestas: 200; 404.

POST /api/vigilantes/import/preview

Descripción: analiza filas de una importación y devuelve coincidencias/conflictos sin persistir.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "filas": [ImportRow], "batchTagIds": ["uuid"]? } (mínimo 1 fila).
Respuestas: 200 con previsualización; 400.

POST /api/vigilantes/import/execute

Descripción: aplica la importación según las decisiones por fila.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body:

json

{
  "rows": [
    { "data": { "rowId": "1", "dni": "12345678Z", "nombre": "Ana", "primer_apellido": "García" },
      "include": true, "updateFields": ["telefono"] }
  ],
  "batchTagIds": ["uuid"],
  "archivoNombre": "vigilantes.xlsx"
}

Respuestas: 200 con totales (nuevos, actualizados, errores); 400.

4. Etiquetas

GET /api/tags

Descripción: lista etiquetas; admite filtro scope.
Autenticación: requerida (ADMIN, SUPERVISOR).
Query: scope (string, opcional).
Respuestas: 200 { data: Tag[] }.

POST /api/tags

Descripción: crea una etiqueta.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "nombre": "TIC", "color": "#2563eb", "scope": "general" }.
- nombre requerido (1..100, trim). color opcional, formato #RRGGBB (def. #6c757d). scope opcional (1..20).
Respuestas: 200; 400; 409.

PUT /api/tags/:id

Descripción: actualiza una etiqueta.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: igual que alta (nombre obligatorio; color/scope opcionales).
Respuestas: 200; 404; 409.

DELETE /api/tags/:id

Descripción: elimina una etiqueta.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404; 409 si está en uso.

5. Sedes

GET /api/sedes

Descripción: lista paginada de sedes (soporta ordenación).
Autenticación: requerida (ADMIN, SUPERVISOR).
Query: page, limit, search, municipio, provincia, is_active.
Respuestas: 200 paginado.

GET /api/sedes/municipios

Descripción: municipios distintos.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200 { data: string[] }.

GET /api/sedes/provincias

Descripción: provincias distintas.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200 { data: string[] }.

GET /api/sedes/:id

Descripción: detalle de sede con edificios.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

POST /api/sedes

Descripción: crea una sede.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body:

json

{
  "nombre": "Sede Central",
  "direccion": "C/ Ejemplo 1",
  "municipio": "Madrid",
  "codigo_postal": "28001",
  "provincia": "Madrid",
  "responsable": "Nombre",
  "telefono": "910000000",
  "correo_contacto": "sede@inap.es",
  "observaciones": "",
  "como_llegar": ""
}

Campo	Tipo	Requerido
`nombre`	string 1..255	Sí
`direccion`	string ≥1	Sí
`municipio` / `codigo_postal` / `provincia` / `responsable` / `telefono` / `correo_contacto` / `observaciones` / `como_llegar`	string	No

Respuestas: 200; 400.

PUT /api/sedes/:id

Descripción: actualiza una sede (incluye is_active).
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: mismos campos, opcionales y anulables.
Respuestas: 200; 404.

DELETE /api/sedes/:id

Descripción: elimina una sede.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404; 409 si tiene edificios o uso.

PUT /api/sedes/:id/toggle-active

Descripción: activa/desactiva la sede.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

6. Edificios

GET /api/edificios

Descripción: lista paginada de edificios, filtrable por sede_id.
Autenticación: requerida (ADMIN, SUPERVISOR).
Query: page, limit, sede_id, search.
Respuestas: 200 paginado.

GET /api/edificios/:id

Descripción: detalle de edificio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

POST /api/edificios

Descripción: crea un edificio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "nombre", "sede_id": "uuid", "direccion?", "estado?": "activo|inactivo|en_obras", "observaciones?" }.
Respuestas: 200; 400; 404 sede inexistente.

PUT /api/edificios/:id

Descripción: actualiza un edificio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: campos opcionales (nombre, sede_id, direccion, estado, observaciones).
Respuestas: 200; 404.

DELETE /api/edificios/:id

Descripción: elimina un edificio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404; 409 si tiene aulas.

7. Aulas

GET /api/aulas

Descripción: lista paginada de aulas con filtros.
Autenticación: requerida (ADMIN, SUPERVISOR).
Query: page, limit, edificio_id, search, tipo (general|informatica), tag_ids (CSV), capacidad_min, capacidad_max, solo_disponibles.
Respuestas: 200 paginado.

GET /api/aulas/:id

Descripción: detalle de aula.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

POST /api/aulas

Descripción: crea un aula.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "nombre", "edificio_id": "uuid", "capacidad": 30, "planta_id?", "tipo?": "general|informatica", "equipamiento?", "estado?": "disponible|mantenimiento|inactiva", "observaciones?", "tagIds?": [] }.
- nombre y edificio_id y capacidad (entero positivo) requeridos.
Respuestas: 200; 400; 404.

PUT /api/aulas/:id

Descripción: actualiza un aula.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: campos opcionales.
Respuestas: 200; 404.

DELETE /api/aulas/:id

Descripción: elimina un aula.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404; 409 si está en uso.

8. Plantas

GET /api/plantas

Descripción: lista todas las plantas.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200 { data: Planta[] }.

POST /api/plantas

Descripción: crea una planta.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "nombre": "Planta baja", "orden": 0 } (nombre req., orden opcional).
Respuestas: 200; 400; 409 nombre duplicado.

PUT /api/plantas/:id

Descripción: actualiza una planta.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404; 409.

DELETE /api/plantas/:id

Descripción: elimina una planta.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404; 409.

GET /api/plantas/edificio/:edificioId

Descripción: plantas asociadas a un edificio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

POST /api/plantas/edificio/:edificioId/assign/:plantaId

Descripción: asigna una planta a un edificio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404; 409.

DELETE /api/plantas/edificio/:edificioId/assign/:plantaId

Descripción: desasigna una planta de un edificio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

9. Convocatorias

GET /api/convocatorias

Descripción: lista paginada de convocatorias.
Autenticación: requerida (ADMIN, SUPERVISOR).
Query: page, limit, estado (ABIERTA|CERRADA), search, anio_desde, anio_hasta.
Respuestas: 200 paginado.

GET /api/convocatorias/:id

Descripción: detalle con ejercicios y tribunal.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

POST /api/convocatorias

Descripción: crea una convocatoria.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "nombre", "anio": 2026, "observaciones?" }.
Respuestas: 200; 400.

PUT /api/convocatorias/:id

Descripción: actualiza una convocatoria.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "nombre?", "anio?", "observaciones?" }.
Respuestas: 200; 404.

PUT /api/convocatorias/:id/estado

Descripción: cambia el estado (ABIERTA/CERRADA).
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "estado": "CERRADA" }.
Respuestas: 200; 400; 404; 409 si hay ejercicios abiertos.

DELETE /api/convocatorias/:id

Descripción: elimina una convocatoria.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404; 409 si tiene ejercicios.

10. Tipos de ejercicio

GET /api/tipos-ejercicio

Descripción: lista el catálogo de tipos de ejercicio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200 { data: TipoEjercicio[] }.

POST /api/tipos-ejercicio

Descripción: crea un tipo.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "nombre": "Acceso libre" } (req., 1..100, trim).
Respuestas: 200; 400; 409.

PUT /api/tipos-ejercicio/:id

Descripción: renombra un tipo (propaga el cambio a ejercicios).
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "nombre": "Nuevo nombre" }.
Respuestas: 200; 404; 409.

DELETE /api/tipos-ejercicio/:id

Descripción: elimina un tipo.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404; 409.

11. Tribunal

GET /api/tribunal-miembros

Descripción: lista paginada de miembros de tribunal.
Autenticación: requerida (cualquier rol).
Query: page, limit, convocatoria_id, tipo (TITULAR|SUPLENTE), cargo (PRESIDENTE|VOCAL|SECRETARIO), search, renuncia.
Respuestas: 200 paginado.

GET /api/tribunal-miembros/:id

Descripción: detalle de miembro.
Autenticación: requerida (cualquier rol).
Respuestas: 200; 404.

POST /api/tribunal-miembros

Descripción: crea un miembro.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "convocatoria_id": "uuid", "tipo": "TITULAR", "nombre": "...", "cargo": "VOCAL", "correo_electronico?", "telefono?", "renuncia?": false, "motivoRenuncia?", "comentarios?" }.
Respuestas: 200; 400; 404.

PUT /api/tribunal-miembros/:id

Descripción: actualiza un miembro.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: tipo y cargo obligatorios en el esquema; resto opcional (incluye motivoReincorporacion).
Respuestas: 200; 404.

PUT /api/tribunal-miembros/:id/toggle-renuncia

Descripción: alterna la renuncia.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "motivo": "..." } (opcional).
Respuestas: 200; 404.

DELETE /api/tribunal-miembros/:id

Descripción: elimina un miembro.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

12. Ejercicios

GET /api/ejercicios

Descripción: lista paginada de ejercicios.
Autenticación: requerida (ADMIN, SUPERVISOR).
Query: page, limit, convocatoria_id, search, estado (ABIERTA|CERRADA).
Respuestas: 200 paginado.

GET /api/ejercicios/:id

Descripción: detalle del ejercicio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

POST /api/ejercicios

Descripción: crea un ejercicio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "nombre", "convocatoria_id": "uuid", "tipo", "fecha?", "hora_vigilantes_aula_tribunal?", "hora_comienzo_ejercicio?", "duracion_acceso_libre?", "duracion_promocion_interna?", "observaciones?" }.
Respuestas: 200; 400; 404.

PUT /api/ejercicios/:id

Descripción: actualiza un ejercicio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: campos opcionales.
Respuestas: 200; 404; 409 si está cerrado.

DELETE /api/ejercicios/:id

Descripción: elimina un ejercicio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404; 409 si tiene dependencias.

GET /api/ejercicios/:id/impacto-cierre

Descripción: devuelve advertencias antes de cerrar (asistencia pendiente, etc.).
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

PUT /api/ejercicios/:id/estado

Descripción: cambia el estado del ejercicio (cerrar/reabrir).
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "estado": "CERRADA" }.
Respuestas: 200; 400; 404; 409 si hay asistencia pendiente.

GET /api/ejercicios/:ejercicioId/sedes

Descripción: sedes asociadas al ejercicio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

POST /api/ejercicios/:ejercicioId/sedes

Descripción: añade una sede al ejercicio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "sede_id": "uuid" }.
Respuestas: 200; 400; 409 duplicado.

DELETE /api/ejercicios/:ejercicioId/sedes/:id

Descripción: quita una sede del ejercicio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404; 409 con dependencias.

GET /api/ejercicios/:ejercicioId/sedes/:ejercicioSedeId/aulas

Descripción: aulas configuradas en la sede del ejercicio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

POST /api/ejercicios/:ejercicioId/sedes/:ejercicioSedeId/aulas

Descripción: añade un aula a la sede del ejercicio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "aula_id": "uuid" }.
Respuestas: 200; 400; 404; 409.

DELETE /api/ejercicios/:ejercicioId/sedes/:ejercicioSedeId/aulas/:id

Descripción: quita un aula de la sede del ejercicio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.
⚠️ Nota: el controlador lee req.params.ejercicioSedeAulaId, pero la ruta define :id (ver DEUDA_TECNICA.md).

GET /api/ejercicios/:ejercicioId/vigilantes

Descripción: vigilantes seleccionados en el ejercicio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

GET /api/ejercicios/:ejercicioId/vigilantes/disponibles

Descripción: vigilantes disponibles para seleccionar.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

POST /api/ejercicios/:ejercicioId/vigilantes

Descripción: selecciona vigilantes para el ejercicio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "vigilante_ids": ["uuid", "..."] } (mín. 1).
Respuestas: 200; 400; 404.

DELETE /api/ejercicios/:ejercicioId/vigilantes/:vigilanteId

Descripción: quita un vigilante del ejercicio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404; 409.

GET /api/ejercicios/:ejercicioId/vigilantes/export

Descripción: exporta el listado de vigilantes a Excel (binario).
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200 (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet).

GET /api/ejercicios/:ejercicioId/ubicaciones

Descripción: estructura jerárquica de sedes/edificios/aulas del ejercicio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

PUT /api/ejercicios/:ejercicioId/ubicaciones

Descripción: guarda la configuración de ubicaciones y capacidades.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body:

json

{
  "sedes": [
    {
      "sede_id": "uuid",
      "edificios": [
        {
          "edificio_id": "uuid",
          "modo": "calcular_aulas",
          "vigilantes_manual": 2,
          "aulas": [
            { "aula_id": "uuid", "modo": "ratio", "ratio_denominador": 25 },
            { "aula_id": "uuid", "modo": "fijo", "vigilantes_fijos": 2 }
          ]
        }
      ]
    }
  ]
}

Respuestas: 200; 400; 404; 409 (p. ej. impacto sobre ejercicios existentes).

POST /api/ejercicios/:ejercicioId/ubicaciones/validar

Descripción: valida el impacto del cambio sin persistir.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: igual que saveUbicaciones.
Respuestas: 200 con UbicacionesImpacto; 400.

GET /api/ejercicios/:ejercicioId/grupos-vigilantes

Descripción: grupos y vigilantes del ejercicio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

PUT /api/ejercicios/:ejercicioId/grupos-vigilantes

Descripción: guarda grupos y asignación de vigilantes a grupos.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "grupos": [ { "nombre": "Grupo A", "vigilantes": [ { "vigilante_id": "uuid", "orden": 0 } ] } ] }.
Respuestas: 200; 400; 404.

POST /api/ejercicios/:ejercicioId/penalizaciones

Descripción: registra como no asistidos a los vigilantes del ejercicio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

GET /api/ejercicios/:ejercicioId/penalizaciones

Descripción: penalizaciones activas del ejercicio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

13. Asignación rápida (simulación)

GET /api/ejercicios/:id/simulation-meta

Descripción: datos y metadatos para la ventana de asignación rápida.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200 con SimulationMeta; 404.

POST /api/ejercicios/:id/simulate

Descripción: genera una propuesta de reparto (no persistente).
Autenticación: requerida (ADMIN, SUPERVISOR).
Body:

json

{
  "ejercicio_id": "uuid",
  "scope": { "tipo": "todas" },
  "reglas": [
    { "id": "resp", "activa": true, "orden": 0 },
    { "id": "pref", "activa": true, "orden": 1 }
  ],
  "respetarCapacidad": true,
  "ratioManual": 3,
  "minResponsablesAula": 1,
  "reasignarTodo": false,
  "asignacionEquitativa": false,
  "priorizarSinPreferencia": false,
  "designarResponsablesAuto": false,
  "excluirVigilanteIds": [],
  "fijados": [
    { "vigilanteId": "uuid", "targetType": "aula", "targetId": "uuid", "esResponsable": true }
  ]
}

Campo	Tipo	Requerido	Descripción
`ejercicio_id`	uuid	Sí	Ejercicio
`scope`	unión discriminada `todas\|sedes\|edificios\|aulas`	Sí	Alcance (`sedes`/`edificios`/`aulas` requieren `ids[]`)
`reglas[]`	`{ id: resp\|pref\|orden\|equidad, activa, orden }`	Sí (mín. 1)	Reglas y prioridad
`respetarCapacidad`	boolean	No (def. true)	—
`ratioManual`	int ≥1	No (def. 3)	—
`minResponsablesAula`	int ≥1	No (def. 1)	—
`reasignarTodo`	boolean	No	—
`asignacionEquitativa`	boolean	No	—
`priorizarSinPreferencia`	boolean	No	—
`designarResponsablesAuto`	boolean	No	—
`excluirVigilanteIds`	uuid[]	No	—
`fijados[]`	`{ vigilanteId, targetType, targetId, esResponsable }`	No	Fijados manualmente

Respuestas: 200 con ResultadoSimulacion; 400; 404; 409.

POST /api/ejercicios/:id/apply-simulation

Descripción: persiste la propuesta de reparto.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body:

json

{
  "ejercicio_id": "uuid",
  "reasignarTodo": false,
  "reconciliar": false,
  "assignments": [
    { "vigilanteId": "uuid", "targetType": "aula", "targetId": "uuid", "esResponsable": true }
  ]
}

Respuestas: 200; 400; 404; 409 (p. ej. vigilante ya notificado).

GET /api/ejercicios/:id/export-asignaciones

Descripción: exporta las asignaciones en XLSX o PDF.
Autenticación: requerida (ADMIN, SUPERVISOR).
Query: formato (xlsx def. | pdf).
Respuestas: 200 binario (Content-Type según formato); 404.

GET /api/ejercicios/:id/control-asistencia

Descripción: genera el documento de control de asistencia con una plantilla.
Autenticación: requerida (ADMIN, SUPERVISOR).
Query: templateId (uuid, requerido).
Respuestas: 200 binario (PDF/HTML); 400; 404.

14. Asignaciones

GET /api/asignaciones

Descripción: lista paginada de asignaciones, filtrable por ejercicio_id.
Autenticación: requerida (ADMIN, SUPERVISOR).
Query: page, limit, ejercicio_id.
Respuestas: 200 paginado.

GET /api/asignaciones/:id

Descripción: detalle de asignación.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

POST /api/asignaciones

Descripción: crea una asignación manual (exactamente un destino).
Autenticación: requerida (ADMIN, SUPERVISOR).
Body:

json

{ "ejercicio_sede_aula_id": "uuid", "vigilante_id": "uuid", "es_responsable_aula": false }

(o ejercicio_sede_edificio_id en lugar de ejercicio_sede_aula_id).

Respuestas: 200; 400 si no se indica exactamente un destino; 404; 409 duplicado.

PUT /api/asignaciones/:id

Descripción: actualiza responsable y estado de asistencia.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "es_responsable_aula?": bool, "estado_asistencia?": "pendiente|asistio|no_asistio" }.
Respuestas: 200; 404.

DELETE /api/asignaciones/:id

Descripción: elimina una asignación.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404; 409 si está notificada.

POST /api/asignaciones/auto

Descripción: auto-asigna vigilantes a las aulas del ejercicio (motor sencillo).
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "ejercicio_id": "uuid", "reasignar": false }.
Respuestas: 200; 400; 404.

PUT /api/asignaciones/:id/anular-asistencia

Descripción: anula la asistencia con motivo.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "motivo": "..." }.
Respuestas: 200; 400; 404.

PUT /api/asignaciones/:id/restaurar-asistencia

Descripción: restaura una asistencia anulada.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

15. Llamamientos

GET /api/ejercicios/:ejercicioId/llamamientos

Descripción: lista los llamamientos del ejercicio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

POST /api/ejercicios/:ejercicioId/llamamientos

Descripción: crea un llamamiento y envía correos a los vigilantes.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body:

json

{
  "vigilante_ids": ["uuid", "uuid"],
  "reintentar_ids": [],
  "fecha_limite_respuesta": "2026-06-01T23:59:00.000Z"
}

Respuestas: 200 con Llamamiento; 400; 404; 409.

GET /api/llamamientos/:id

Descripción: detalle del llamamiento.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

DELETE /api/llamamientos/:id

Descripción: elimina un llamamiento.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404; 409.

GET /api/llamamientos/:id/impacto-anulacion

Descripción: impacto de anular el llamamiento.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

POST /api/llamamientos/:id/anular

Descripción: anula el llamamiento con motivo.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "motivo": "..." }.
Respuestas: 200; 400; 404; 409 por coherencia.

GET /api/llamamientos/:id/correos

Descripción: correos asociados al llamamiento.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

POST /api/vigilante-llamamientos/:id/confirmar

Descripción: confirma al vigilante, opcionalmente con sede preferida.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "sede_id": "uuid" } (opcional/null).
Respuestas: 200; 404; 409.

POST /api/vigilante-llamamientos/:id/rechazar

Descripción: marca rechazo.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

POST /api/vigilante-llamamientos/:id/desconfirmar

Descripción: revierte la confirmación.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404; 409.

PATCH /api/vigilante-llamamientos/:id/sede

Descripción: edita la sede preferida.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "sede_id": "uuid" }.
Respuestas: 200; 404.

GET /api/ejercicios/:ejercicioId/confirmaciones/pendientes

Descripción: confirmaciones pendientes del ejercicio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

POST /api/ejercicios/:ejercicioId/confirmaciones/importar-excel

Descripción: previsualiza una importación de confirmaciones desde Excel (multipart, campo file).
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200 con ExcelPreview; 400.

POST /api/ejercicios/:ejercicioId/confirmaciones/aplicar-excel

Descripción: aplica las confirmaciones importadas.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "filas": [ { "vigilante_llamamiento_id": "uuid", "sede_id?": "uuid", "actualizar_datos?": { ... } } ] }.
Respuestas: 200; 400; 404.

POST /api/vigilante-llamamientos/:id/reenviar-correo

Descripción: reenvía el correo individual del llamamiento.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404; 500 si falla SMTP.

16. Notificaciones

GET /api/ejercicios/:ejercicioId/notificaciones

Descripción: lista las notificaciones del ejercicio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

POST /api/ejercicios/:ejercicioId/notificaciones

Descripción: crea y envía una notificación. multipart/form-data.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body (multipart):

Campo	Tipo	Requerido	Descripción
`asunto`	string	Sí	Asunto
`cuerpo`	string	Sí	Cuerpo (HTML/texto)
`files`	file[] (máx. 10)	No	Adjuntos

Respuestas: 200 con la notificación; 400; 404.
Errores comunes: fallo SMTP (se registra; el estado del correo queda correo_enviado=false).

GET /api/notificaciones/:id

Descripción: detalle de la notificación con destinatarios y documentos.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

POST /api/notificaciones/:id/anular

Descripción: anula la notificación.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "motivo": "...", "anular_asignaciones": false }.
Respuestas: 200; 400; 404; 409.

POST /api/notificaciones/:id/documentos

Descripción: añade un documento a la notificación (multipart, campo file).
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 400; 404.

DELETE /api/notificaciones/:id/documentos/:documentoId

Descripción: elimina un documento de la notificación.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

POST /api/notificacion-vigilantes/:id/reenviar-correo

Descripción: reenvía el correo a un destinatario concreto.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

POST /api/notificaciones/:id/reenviar

Descripción: reenvía la notificación completa.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404; 409.

GET /api/ejercicios/:ejercicioId/documentos

Descripción: documentos asociados al ejercicio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

POST /api/ejercicios/:ejercicioId/documentos

Descripción: sube un documento al ejercicio (multipart, campo file).
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 400; 404.

DELETE /api/ejercicios/:ejercicioId/documentos/:documentoId

Descripción: elimina un documento del ejercicio.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

17. Plantillas de email

GET /api/templates/types

Descripción: tipos de plantilla disponibles.
Autenticación: requerida (ADMIN).
Respuestas: 200 { data: [...] }.

GET /api/templates

Descripción: lista paginada de plantillas.
Autenticación: requerida (ADMIN).
Query: page, limit, search, tipo, is_active, is_system.
Respuestas: 200 paginado.

GET /api/templates/:id

Descripción: detalle de plantilla.
Autenticación: requerida (ADMIN).
Respuestas: 200; 404.

POST /api/templates

Descripción: crea una plantilla.
Autenticación: requerida (ADMIN).
Body: { "nombre", "description?", "tipo", "asunto", "cuerpo", "is_active": false }.
Respuestas: 200; 400.

PUT /api/templates/:id

Descripción: actualiza una plantilla.
Autenticación: requerida (ADMIN).
Respuestas: 200; 404; 409 si es de sistema y se intenta modificar el tipo.

DELETE /api/templates/:id

Descripción: elimina una plantilla (no de sistema).
Autenticación: requerida (ADMIN).
Respuestas: 200; 404; 409.

PATCH /api/templates/:id/activate

Descripción: activa/desactiva (desactiva las demás del mismo tipo).
Autenticación: requerida (ADMIN).
Respuestas: 200; 404.

POST /api/templates/:id/preview

Descripción: renderiza la plantilla con variables.
Autenticación: requerida (ADMIN).
Body: { "variables": { "nombre": "Ana" } }.
Respuestas: 200; 404.

GET /api/templates/active/:tipo

Descripción: plantilla activa de un tipo (EmailTemplateTipo).
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

18. Plantillas de documento

GET /api/document-templates

Descripción: lista paginada de plantillas de documento.
Autenticación: requerida (ADMIN, SUPERVISOR).
Query: page, limit, search, tipo, is_active, is_system.
Respuestas: 200 paginado.

GET /api/document-templates/types

Descripción: tipos y variables disponibles.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200.

GET /api/document-templates/:id

Descripción: detalle de plantilla.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

POST /api/document-templates

Descripción: crea una plantilla HTML (Handlebars).
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "nombre", "descripcion?", "tipo": "CONTROL_ASISTENCIA", "html" }.
Respuestas: 200; 400.

PUT /api/document-templates/:id

Descripción: actualiza una plantilla.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

POST /api/document-templates/:id/preview

Descripción: previsualiza con variables.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "variables": {} }.
Respuestas: 200; 404.

DELETE /api/document-templates/:id

Descripción: elimina una plantilla (no de sistema).
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404; 409.

PATCH /api/document-templates/:id/activate

Descripción: activa/desactiva.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas: 200; 404.

19. Configuración

GET /api/configuracion/colores-roles-usuarios

Descripción: mapa de colores por rol de usuario.
Autenticación: requerida (cualquier rol).
Respuestas: 200 { data: Record<string,string> }.

GET /api/configuracion/colores-miembros-tribunal

Descripción: mapa de colores de miembros de tribunal.
Autenticación: requerida (cualquier rol).
Respuestas: 200.

GET /api/configuracion/etiqueta-colores

Descripción: mapa de colores de etiquetas.
Autenticación: requerida (cualquier rol).
Respuestas: 200.

GET /api/configuracion/pagina-ayuda/check

Descripción: comprueba que la URL de la página de ayuda configurada (url_pagina_ayuda) responde. Hace la petición desde el servidor (evita CORS) con un timeout de 8 s. Devuelve la URL efectiva (valor configurado o el por defecto https://ayuda.siva.funcioconecta.com) y el estado obtenido. ok es true para respuestas 2xx/3xx.
Autenticación: requerida (cualquier rol).
Respuestas: 200 { data: { ok: boolean, url: string, status: number | null } }; status es null si la petición falló.

GET /api/configuracion

Descripción: lista paginada de parámetros del sistema.
Autenticación: requerida (ADMIN, SUPERVISOR).
Query: page, limit, search.
Respuestas: 200 paginado.

PUT /api/configuracion/:clave

Descripción: actualiza el valor de un parámetro por su clave. El SUPERVISOR no puede modificar las claves reservadas a ADMIN (ver Roles); entre ellas url_pagina_ayuda, que además debe ser una URL http(s) válida.
Autenticación: requerida (ADMIN, SUPERVISOR).
Params: clave (string).
Body: { "valor": "nuevo valor" }.
Respuestas: 200; 400; 403 si el SUPERVISOR intenta editar una clave reservada; 404.

20. Otros

PUT /api/penalizaciones/:id/levantar

Descripción: levanta (revoca) una penalización activa.
Autenticación: requerida (ADMIN, SUPERVISOR).
Body: { "motivo": "..." }.
Respuestas: 200; 400; 404.

GET /api/ubicaciones/usos

Descripción: ejercicios abiertos que usan una ubicación concreta.
Autenticación: requerida (ADMIN, SUPERVISOR).
Query: tipo (sede|edificio|aula), id (uuid).
Respuestas: 200 { data: { ejercicios: [...] } }; 400 si falta id.

GET /api/summary

Descripción: KPIs del dashboard.
Autenticación: requerida (ADMIN, SUPERVISOR).
Respuestas:

json

{
  "success": true,
  "data": {
    "totalVigilantes": 5001,
    "vigilantesActivos": 4900,
    "vigilantesBloqueados": 101,
    "totalConvocatorias": 6,
    "convocatoriasPorEstado": { "ABIERTA": 4, "CERRADA": 2 },
    "totalEjercicios": 17,
    "ejerciciosHoy": 0,
    "totalAsignaciones": 3200,
    "totalSedes": 23,
    "totalAulas": 144
  }
}

GET /api/health

Descripción: estado del servicio y de la base de datos.
Autenticación: no.
Respuestas: 200 { data: { status: "ok", timestamp, database: "connected" } }.

GET /api/files/download/:objectName

Descripción: descarga/stream de un fichero del almacenamiento local.
Autenticación: no.
Params: objectName (ruta codificada).
Respuestas: 200 binario; 404 si no existe.

GET /api/docs

Descripción: interfaz Swagger UI.
Autenticación: no.

GET /api/docs.json

Descripción: especificación OpenAPI en JSON.
Autenticación: no.

21. Jobs programados (no HTTP)

Job	Expresión	Descripción
`expirar-pendientes`	`0 * * * *`	Pasa a `SIN_RESPUESTA` los `VigilanteLlamamiento` pendientes con plazo vencido y cierra los llamamientos activos vencidos.
`expirar-penalizaciones`	`0 * * * *`	Marca como `finalizada` las penalizaciones vencidas.

API REST de SIVA ​

Convenciones generales ​

Roles ​

Códigos de error comunes ​

Paginación ​

Flujo de autenticación ​

Tabla resumen de endpoints ​

Autenticación — /api/auth ​

Usuarios — /api/users ​

Vigilantes — /api/vigilantes ​

Etiquetas — /api/tags ​

Sedes — /api/sedes ​

Edificios — /api/edificios ​

Aulas — /api/aulas ​

Plantas — /api/plantas ​

Convocatorias — /api/convocatorias ​

Tipos de ejercicio — /api/tipos-ejercicio ​

Tribunal — /api/tribunal-miembros ​

Ejercicios — /api/ejercicios ​

Asignación rápida (simulación) — /api/ejercicios ​

Asignaciones — /api/asignaciones ​

Llamamientos — /api ​

Notificaciones — /api ​

Plantillas de email — /api/templates ​

Plantillas de documento — /api/document-templates ​

Configuración — /api/configuracion ​

Otros ​

1. Autenticación ​

POST /api/auth/login ​

POST /api/auth/logout ​

POST /api/auth/refresh-token ​

POST /api/auth/change-password ​

POST /api/auth/forgot-password ​

POST /api/auth/reset-password ​

POST /api/auth/verify-email ​

GET /api/auth/me ​

2. Usuarios ​

GET /api/users/me ​

PUT /api/users/me ​

POST /api/users/me/avatar ​

DELETE /api/users/me/avatar ​

GET /api/users ​

GET /api/users/:id ​

POST /api/users ​

PUT /api/users/:id ​

DELETE /api/users/:id ​

PATCH /api/users/:id/status ​

3. Vigilantes ​

GET /api/vigilantes ​

GET /api/vigilantes/:id ​

GET /api/vigilantes/:id/historial-asistencia ​

GET /api/vigilantes/:id/penalizaciones ​

POST /api/vigilantes ​

PUT /api/vigilantes/:id ​

DELETE /api/vigilantes/:id ​

PUT /api/vigilantes/:id/toggle-bloqueado ​

POST /api/vigilantes/import/preview ​

POST /api/vigilantes/import/execute ​

4. Etiquetas ​

GET /api/tags ​

POST /api/tags ​

PUT /api/tags/:id ​

DELETE /api/tags/:id ​

5. Sedes ​

GET /api/sedes ​

GET /api/sedes/municipios ​

GET /api/sedes/provincias ​

GET /api/sedes/:id ​

POST /api/sedes ​

PUT /api/sedes/:id ​

DELETE /api/sedes/:id ​

PUT /api/sedes/:id/toggle-active ​

6. Edificios ​

GET /api/edificios ​

GET /api/edificios/:id ​

POST /api/edificios ​

PUT /api/edificios/:id ​

DELETE /api/edificios/:id ​

7. Aulas ​

GET /api/aulas ​

API REST de SIVA

Convenciones generales

Roles

Códigos de error comunes

Paginación

Flujo de autenticación

Tabla resumen de endpoints

Autenticación — `/api/auth`

Usuarios — `/api/users`

Vigilantes — `/api/vigilantes`

Etiquetas — `/api/tags`

Sedes — `/api/sedes`

Edificios — `/api/edificios`

Aulas — `/api/aulas`

Plantas — `/api/plantas`

Convocatorias — `/api/convocatorias`

Tipos de ejercicio — `/api/tipos-ejercicio`

Tribunal — `/api/tribunal-miembros`

Ejercicios — `/api/ejercicios`

Asignación rápida (simulación) — `/api/ejercicios`

Asignaciones — `/api/asignaciones`

Llamamientos — `/api`

Notificaciones — `/api`

Plantillas de email — `/api/templates`

Plantillas de documento — `/api/document-templates`

Configuración — `/api/configuracion`

Otros

1. Autenticación

POST /api/auth/login

POST /api/auth/logout

POST /api/auth/refresh-token

POST /api/auth/change-password

POST /api/auth/forgot-password

POST /api/auth/reset-password

POST /api/auth/verify-email

GET /api/auth/me

2. Usuarios

GET /api/users/me

PUT /api/users/me

POST /api/users/me/avatar

DELETE /api/users/me/avatar

GET /api/users

GET /api/users/:id

POST /api/users

PUT /api/users/:id

DELETE /api/users/:id

PATCH /api/users/:id/status

3. Vigilantes

GET /api/vigilantes

GET /api/vigilantes/:id

GET /api/vigilantes/:id/historial-asistencia

GET /api/vigilantes/:id/penalizaciones

POST /api/vigilantes

PUT /api/vigilantes/:id

DELETE /api/vigilantes/:id

PUT /api/vigilantes/:id/toggle-bloqueado

POST /api/vigilantes/import/preview

POST /api/vigilantes/import/execute

4. Etiquetas

GET /api/tags

POST /api/tags

PUT /api/tags/:id

DELETE /api/tags/:id

5. Sedes

GET /api/sedes

GET /api/sedes/municipios

GET /api/sedes/provincias

GET /api/sedes/:id

POST /api/sedes

PUT /api/sedes/:id

DELETE /api/sedes/:id

PUT /api/sedes/:id/toggle-active

6. Edificios

GET /api/edificios

GET /api/edificios/:id

POST /api/edificios

PUT /api/edificios/:id

DELETE /api/edificios/:id

7. Aulas

GET /api/aulas