Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/JuanM84/gestor-visitas/llms.txt

Use this file to discover all available pages before exploring further.

La API del Túnel Subfluvial es una interfaz REST construida con Node.js, Express 5 y TypeScript, respaldada por una base de datos PostgreSQL. Expone todos los recursos necesarios para gestionar visitas guiadas, usuarios, estadísticas, configuración, auditoría e instituciones a través de rutas prefijadas en /api/. Todos los endpoints, salvo el inicio de sesión, requieren autenticación mediante JWT Bearer token.

​
URL base y configuración de entorno

El servidor escucha en el puerto definido por la variable de entorno PORT. Si no está definida, usa el puerto 3000 por defecto. 
http://localhost:3000   (desarrollo por defecto)
Variable de entornoPropósitoValor por defecto
PORTPuerto en que escucha el servidor3000
FRONTEND_URLOrigen permitido por CORShttp://localhost:5173
JWT_SECRETClave secreta para firmar los tokens JWT(requerida)
JWT_EXPIRYDuración del token JWT24h
DATABASE_URLURL de conexión completa a PostgreSQL (p. ej. en Render). Si está definida, tiene precedencia sobre las variables individuales.(opcional si se usan las vars individuales)
DB_USERUsuario de PostgreSQLpostgres
DB_HOSTHost del servidor PostgreSQLlocalhost
DB_NAMENombre de la base de datostunel_subfluvial
DB_PASSWORDContraseña del usuario de PostgreSQL(requerida en local)
DB_PORTPuerto de PostgreSQL5432
JWT_SECRET es obligatoria; sin ella el servidor rechazará todas las peticiones autenticadas. Para la base de datos, define DATABASE_URL (entornos cloud) o las variables individuales DB_USER, DB_HOST, DB_NAME, DB_PASSWORD y DB_PORT (entorno local).

​
Autenticación

La API usa JSON Web Tokens (JWT) transmitidos como Bearer token en la cabecera Authorization. El único endpoint público es POST /api/auth/login; todos los demás requieren un token válido. 
Authorization: Bearer <token>
El token se obtiene en el login y contiene el id, nombre y rol del usuario. La duración del token se controla con la variable JWT_EXPIRY (por defecto 24h). Consulta la página de Autenticación para el flujo completo.

​
Formato de las peticiones y respuestas

Todas las peticiones y respuestas usan application/json. Incluye siempre la cabecera Content-Type en las peticiones con cuerpo. 
Content-Type: application/json

​
Formato de error estándar

Cuando una petición falla, la API devuelve un objeto JSON con una sola clave error: 
{
  "error": "Descripción del error"
}

​
Formato de éxito

La estructura de la respuesta exitosa varía según el endpoint. Consulta la documentación de cada grupo de rutas para los esquemas específicos.

​
Códigos de estado HTTP

CódigoSignificadoCuándo se usa
200 OKÉxitoPetición procesada correctamente
201 CreatedRecurso creadoPOST que crea un nuevo recurso
400 Bad RequestPetición inválidaCampos requeridos ausentes o datos incorrectos
401 UnauthorizedNo autenticadoToken ausente, inválido o expirado
403 ForbiddenSin permisosEl rol del usuario no está autorizado
404 Not FoundNo encontradoEl recurso solicitado no existe
500 Internal Server ErrorError del servidorError inesperado en el servidor

​
Configuración CORS

El servidor tiene CORS habilitado para el origen configurado en FRONTEND_URL. Los métodos y cabeceras permitidos son:
  • Métodos: GET, POST, PUT, PATCH, DELETE, OPTIONS
  • Cabeceras: Content-Type, Authorization
Las peticiones desde un origen distinto al configurado en FRONTEND_URL serán rechazadas por el navegador. Asegúrate de definir esta variable correctamente en producción.

​
Control de acceso por rol

La API implementa control de acceso basado en roles (RBAC) con dos roles disponibles:
RolDescripción
AdminAcceso completo a todos los endpoints, incluyendo gestión de usuarios, estadísticas y configuración
GuíaAcceso limitado; puede gestionar visitas y recursos propios de su función
El middleware verificarRol protege los endpoints exclusivos de administradores. Si un usuario con rol Guía intenta acceder a un recurso reservado para Admin, recibirá una respuesta 403 Forbidden: 
{
  "error": "Acceso denegado. No tienes permisos suficientes para realizar esta acción."
}

​
Health check

Usa este endpoint para verificar que el servidor está en línea sin necesidad de autenticación. GET /api/health 
{
  "status": "ok",
  "message": "API del Túnel Subfluvial funcionando"
}

​
Grupos de endpoints disponibles

Autenticación

Inicio de sesión y obtención del token JWT. Único endpoint público de la API.

Visitas

Creación, consulta, modificación y cancelación de visitas guiadas al túnel.

Gestores

Administración del personal gestor: listado, alta, actualización y baja.

Usuarios

Gestión de usuarios del sistema, incluyendo cambio de contraseña y activación.

Estadísticas y Exportación

Informes estadísticos por rango de fechas y exportación de datos en distintos formatos.

Configuración

Lectura y escritura de parámetros del sistema, como el timeout de sesión.

Días Inhábiles

Gestión del calendario de días en los que no se realizan visitas.

Instituciones

Alta y listado de instituciones educativas o grupos visitantes registrados.

Auditoría

Consulta del registro de auditoría de acciones realizadas en el sistema.
Para explorar un grupo de endpoints, selecciona la tarjeta correspondiente. Cada página incluye parámetros, cuerpos de petición y ejemplos con curl.

Build docs developers (and LLMs) love

Get started for freeTalk to us