Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/camiloivcode/biblioteca-la-palabra/llms.txt

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

Todos los endpoints bajo /api/users requieren autenticación con Bearer token y que el usuario autenticado tenga el rol ADMIN. Los usuarios con rol BIBLIOTECARIO reciben 403 Forbidden en cualquier solicitud a estos endpoints.
Acceso exclusivo para ADMIN. El middleware requireRole('ADMIN') se aplica globalmente a todo el router /api/users. Un token válido de un usuario BIBLIOTECARIO resultará en:
{
  "success": false,
  "message": "No tienes permisos para realizar esta acción"
}
Obtén tu token de acceso ADMIN a través del endpoint POST /api/auth/login.

​
GET /api/users

Retorna el listado de todos los usuarios del sistema, ordenados por fecha de creación descendente (más recientes primero). El campo password nunca se incluye en ninguna respuesta de este router. 
curl -X GET https://api.biblioteca.com/api/users \
  -H "Authorization: Bearer <token_admin>"
Respuesta 200 OK 
{
  "success": true,
  "message": "Operación exitosa",
  "data": [
    {
      "id": 2,
      "nombre": "Lucía Fernández",
      "email": "lucia@biblioteca.com",
      "role": "BIBLIOTECARIO",
      "activo": true,
      "createdAt": "2024-05-20T09:15:00.000Z"
    },
    {
      "id": 1,
      "nombre": "Admin Principal",
      "email": "admin@biblioteca.com",
      "role": "ADMIN",
      "activo": true,
      "createdAt": "2024-01-10T08:00:00.000Z"
    }
  ]
}
​
data[].id
integer
Identificador único del usuario.
​
data[].nombre
string
Nombre completo del usuario.
​
data[].email
string
Dirección de correo electrónico. Única en el sistema.
​
data[].role
string
Rol del usuario. Valores posibles: ADMIN o BIBLIOTECARIO.
​
data[].activo
boolean
Estado de la cuenta. Si es false, el usuario no puede iniciar sesión.
​
data[].createdAt
string (ISO 8601)
Fecha y hora de creación del registro.

​
GET /api/users/:id

Retorna los datos de un usuario específico por su id. La contraseña nunca se expone. 
curl -X GET https://api.biblioteca.com/api/users/2 \
  -H "Authorization: Bearer <token_admin>"
Respuesta 200 OK 
{
  "success": true,
  "message": "Operación exitosa",
  "data": {
    "id": 2,
    "nombre": "Lucía Fernández",
    "email": "lucia@biblioteca.com",
    "role": "BIBLIOTECARIO",
    "activo": true,
    "createdAt": "2024-05-20T09:15:00.000Z"
  }
}
Error 404 Not Found — Si no existe un usuario con el id indicado. 
{
  "success": false,
  "message": "Usuario no encontrado"
}

​
POST /api/users

Crea un nuevo usuario del sistema. El email debe ser único. La contraseña se almacena hasheada con bcryptjs (12 rondas de salt); nunca se devuelve en texto plano. 
curl -X POST https://api.biblioteca.com/api/users \
  -H "Authorization: Bearer <token_admin>" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Lucía Fernández",
    "email": "lucia@biblioteca.com",
    "password": "Segura123",
    "role": "BIBLIOTECARIO"
  }'

​
Cuerpo de la solicitud

​
nombre
string
required
Nombre completo del usuario. No puede estar vacío. Se aplica trim automáticamente.
​
email
string
required
Dirección de correo electrónico válida. Debe ser única en el sistema. Se normaliza a minúsculas automáticamente.
​
password
string
required
Contraseña del usuario. Requisitos obligatorios:
  • Mínimo 8 caracteres
  • Al menos 1 letra mayúscula
  • Al menos 1 dígito numérico
Ejemplo válido: Palabra7, Admin2024, BiblioX9
​
role
string
required
Rol del usuario dentro del sistema. Valores permitidos: ADMIN o BIBLIOTECARIO.
  • ADMIN — acceso total, incluyendo gestión de usuarios.
  • BIBLIOTECARIO — acceso operativo (catálogo, socios, préstamos, reportes).
Respuesta 201 Created 
{
  "success": true,
  "message": "Usuario creado correctamente",
  "data": {
    "id": 3,
    "nombre": "Lucía Fernández",
    "email": "lucia@biblioteca.com",
    "role": "BIBLIOTECARIO",
    "activo": true,
    "createdAt": "2024-06-01T11:00:00.000Z"
  }
}
Error 409 Conflict — Si ya existe un usuario registrado con ese email. 
{
  "success": false,
  "message": "Ya existe un usuario con ese email"
}
Error 422 Unprocessable Entity — Si la contraseña no cumple los requisitos, el email no es válido, el rol no es ADMIN/BIBLIOTECARIO, o nombre está vacío. 
{
  "success": false,
  "message": "Errores de validación",
  "errors": [
    {
      "field": "password",
      "message": "La contraseña debe tener al menos una mayúscula y un número"
    }
  ]
}

​
PUT /api/users/:id

Actualiza los datos de un usuario existente. Todos los campos son opcionales; solo se modifican los que se incluyan. Ten en cuenta que el campo password no forma parte de la validación de este endpoint (no hay reglas de longitud ni formato aplicadas). Sin embargo, si se incluye password en el cuerpo, el servicio lo detecta y lo almacena hasheado con bcryptjs (12 rondas). Si no se incluye, el campo es eliminado del payload antes de la actualización y la contraseña existente no cambia. 
curl -X PUT https://api.biblioteca.com/api/users/2 \
  -H "Authorization: Bearer <token_admin>" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Lucía Fernández Torres",
    "role": "ADMIN"
  }'

​
Cuerpo de la solicitud

​
nombre
string
Nuevo nombre completo. No puede enviarse vacío si se incluye. Se aplica trim.
​
email
string
Nueva dirección de correo. Debe ser un email válido. Se normaliza a minúsculas automáticamente.
​
role
string
Nuevo rol. Valores permitidos: ADMIN o BIBLIOTECARIO.
Respuesta 200 OK 
{
  "success": true,
  "message": "Usuario actualizado correctamente",
  "data": {
    "id": 2,
    "nombre": "Lucía Fernández Torres",
    "email": "lucia@biblioteca.com",
    "role": "ADMIN",
    "activo": true
  }
}
Error 404 Not Found — Si no existe un usuario con el id indicado. Error 422 Unprocessable Entity — Si email o role tienen un valor inválido.

​
PATCH /api/users/:id/toggle

Alterna el estado activo del usuario: si está activo lo desactiva, y viceversa. No requiere cuerpo en la solicitud. 
curl -X PATCH https://api.biblioteca.com/api/users/2/toggle \
  -H "Authorization: Bearer <token_admin>"
Un usuario con activo: false no puede iniciar sesión. Al intentarlo, el middleware de autenticación responde con 403 Forbidden y el mensaje Cuenta desactivada. Contacta al administrador. Esta es la forma recomendada de deshabilitar temporalmente el acceso sin eliminar la cuenta.
Restricción de auto-modificación. Un administrador no puede desactivar su propia cuenta. Si el id del path coincide con el id del token autenticado, el servidor responde con 403 Forbidden:
{
  "success": false,
  "message": "No puedes desactivar tu propia cuenta"
}
Respuesta 200 OK — Tras desactivar un usuario: 
{
  "success": true,
  "message": "Usuario desactivado",
  "data": {
    "id": 2,
    "nombre": "Lucía Fernández Torres",
    "activo": false
  }
}
Respuesta 200 OK — Tras reactivar un usuario: 
{
  "success": true,
  "message": "Usuario activado",
  "data": {
    "id": 2,
    "nombre": "Lucía Fernández Torres",
    "activo": true
  }
}
​
data.activo
boolean
Nuevo estado del usuario tras ejecutar el toggle. El mensaje de la respuesta refleja si fue activado o desactivado.

​
DELETE /api/users/:id

Elimina permanentemente un usuario del sistema. La operación es irreversible. 
curl -X DELETE https://api.biblioteca.com/api/users/2 \
  -H "Authorization: Bearer <token_admin>"
Restricción de auto-eliminación. Un administrador no puede eliminar su propia cuenta. Si el id del path coincide con el del token autenticado, se retorna 403 Forbidden:
{
  "success": false,
  "message": "No puedes eliminar tu propia cuenta"
}
Respuesta 200 OK 
{
  "success": true,
  "message": "Operación exitosa",
  "data": {
    "message": "Usuario eliminado correctamente"
  }
}
Error 404 Not Found — Si no existe un usuario con el id indicado.

Build docs developers (and LLMs) love

Get started for freeTalk to us