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/categorias requieren autenticación mediante Bearer token JWT. Tanto usuarios con rol ADMIN como BIBLIOTECARIO tienen acceso completo a estos endpoints.
Incluye el token obtenido en /api/auth/login en el encabezado Authorization:
Authorization: Bearer <tu_token_jwt>
Sin él, el servidor responde con 401 Unauthorized. Si el token ha expirado, recibirás el mensaje Sesión expirada. Por favor, inicia sesión nuevamente.

​
GET /api/categorias

Retorna el listado completo de categorías del catálogo, ordenadas alfabéticamente por nombre. Cada categoría incluye el conteo de materiales asociados. 
curl -X GET https://api.biblioteca.com/api/categorias \
  -H "Authorization: Bearer <token>"
Respuesta 200 OK 
{
  "success": true,
  "message": "Operación exitosa",
  "data": [
    {
      "id": 1,
      "nombre": "Ciencias Naturales",
      "descripcion": "Biología, química, física y ciencias de la tierra",
      "icono": "science",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "_count": {
        "materiales": 14
      }
    },
    {
      "id": 2,
      "nombre": "Historia",
      "descripcion": "Historia universal y local",
      "icono": "history",
      "createdAt": "2024-01-15T10:31:00.000Z",
      "_count": {
        "materiales": 8
      }
    }
  ]
}
​
data
array
Array de objetos categoría, ordenado por nombre ascendente.
​
data[].id
integer
Identificador único de la categoría.
​
data[].nombre
string
Nombre único de la categoría.
​
data[].descripcion
string | null
Descripción opcional de la categoría.
​
data[].icono
string | null
Identificador de icono Material Symbols. Ver lista de valores válidos en POST /api/categorias.
​
data[].createdAt
string (ISO 8601)
Fecha y hora de creación del registro.
​
data[]._count.materiales
integer
Número de materiales del catálogo asignados a esta categoría.

​
GET /api/categorias/:id

Retorna una categoría específica. A diferencia de GET /api/categorias, este endpoint incluye el listado resumido de los materiales vinculados (en lugar del simple conteo). 
curl -X GET https://api.biblioteca.com/api/categorias/1 \
  -H "Authorization: Bearer <token>"
Respuesta 200 OK 
{
  "success": true,
  "message": "Operación exitosa",
  "data": {
    "id": 1,
    "nombre": "Ciencias Naturales",
    "descripcion": "Biología, química, física y ciencias de la tierra",
    "icono": "science",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "materiales": [
      { "id": 5, "titulo": "El origen de las especies" },
      { "id": 12, "titulo": "Física conceptual" }
    ]
  }
}
​
data.materiales
array
Lista de materiales asociados. Cada elemento contiene únicamente id y titulo.
Error 404 Not Found — Si no existe una categoría con el id indicado. 
{
  "success": false,
  "message": "Categoría no encontrada"
}

​
POST /api/categorias

Crea una nueva categoría. El campo nombre debe ser único en el sistema. El campo icono debe ser uno de los valores predefinidos de Material Symbols soportados. 
curl -X POST https://api.biblioteca.com/api/categorias \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Tecnología",
    "descripcion": "Informática, programación y electrónica",
    "icono": "computer"
  }'

​
Cuerpo de la solicitud

​
nombre
string
required
Nombre de la categoría. Debe ser único. Se recortan espacios en blanco al inicio y al final (trim).
​
descripcion
string
Descripción opcional de la categoría. Se aplica trim automáticamente.
​
icono
string
Identificador del icono de Material Symbols. Debe ser exactamente uno de los valores de la lista de iconos válidos a continuación.

​
Iconos válidos

menu_book       history         science         lightbulb
palette         computer        calculate       public
music_note      emoji_events    category        book
biotech         architecture    psychology      sports_esports
language        travel_explore  newspaper       theater_comedy
pets            restaurant      sailing         stadium
volcano         forest
Respuesta 201 Created 
{
  "success": true,
  "message": "Categoría creada correctamente",
  "data": {
    "id": 3,
    "nombre": "Tecnología",
    "descripcion": "Informática, programación y electrónica",
    "icono": "computer",
    "createdAt": "2024-06-01T14:22:00.000Z"
  }
}
Error 409 Conflict — Si ya existe una categoría con el mismo nombre. 
{
  "success": false,
  "message": "Ya existe una categoría con ese nombre"
}
Error 422 Unprocessable Entity — Si el valor de icono no está en la lista de iconos válidos, o si nombre está vacío. 
{
  "success": false,
  "message": "Errores de validación",
  "errors": [
    { "field": "icono", "message": "Icono inválido" }
  ]
}

​
PUT /api/categorias/:id

Actualiza uno o más campos de una categoría existente. Todos los campos son opcionales; solo se modifican los que se incluyan en el cuerpo. 
curl -X PUT https://api.biblioteca.com/api/categorias/3 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "descripcion": "Informática, programación, redes y electrónica",
    "icono": "biotech"
  }'

​
Cuerpo de la solicitud

​
nombre
string
Nuevo nombre para la categoría. Se aplica trim automáticamente.
​
descripcion
string
Nueva descripción. Se aplica trim automáticamente.
​
icono
string
Nuevo icono. Debe ser uno de los valores listados en POST /api/categorias.
Respuesta 200 OK 
{
  "success": true,
  "message": "Categoría actualizada",
  "data": {
    "id": 3,
    "nombre": "Tecnología",
    "descripcion": "Informática, programación, redes y electrónica",
    "icono": "biotech",
    "createdAt": "2024-06-01T14:22:00.000Z"
  }
}
Error 404 Not Found — Si no existe una categoría con el id indicado. Error 422 Unprocessable Entity — Si se envía un valor de icono inválido.

​
DELETE /api/categorias/:id

Elimina permanentemente una categoría. La operación falla si la categoría tiene materiales asociados. Desvincula o reasigna primero los materiales antes de intentar eliminarla. 
curl -X DELETE https://api.biblioteca.com/api/categorias/3 \
  -H "Authorization: Bearer <token>"
Restricción de integridad referencial. No es posible eliminar una categoría que tenga materiales asociados. El endpoint retorna 409 Conflict en ese caso. Para proceder, primero reasigna o elimina todos los materiales vinculados a esta categoría. Puedes verificar el recuento en GET /api/categorias/:id.
Respuesta 200 OK 
{
  "success": true,
  "message": "Operación exitosa",
  "data": {
    "message": "Categoría eliminada correctamente"
  }
}
Error 409 Conflict — Si la categoría tiene materiales asociados. 
{
  "success": false,
  "message": "No se puede eliminar una categoría con materiales asociados"
}
Error 404 Not Found — Si no existe una categoría con el id indicado.

Build docs developers (and LLMs) love

Get started for freeTalk to us