API REST para materiales del catálogo de la biblioteca

Los endpoints bajo /api/materiales gestionan el catálogo completo de la biblioteca: libros, revistas, DVDs, periódicos y otros materiales. Todas las operaciones requieren autenticación y se ejecutan transaccionalmente junto con los modelos relacionados de autor y categoría.

Todas las rutas de este recurso requieren autenticación mediante Bearer token. Incluye la cabecera Authorization: Bearer <token> en cada solicitud. Las peticiones sin token o con token inválido recibirán una respuesta 401 Unauthorized.

GET /api/materiales

Devuelve una lista paginada de materiales del catálogo. Soporta filtros combinables por tipo, estado, autor y categoría, además de búsqueda de texto libre que coincide contra titulo, isbn y editorial. Los resultados se ordenan alfabéticamente por titulo.

curl -X GET "https://api.biblioteca.com/api/materiales?tipo=LIBRO&estado=DISPONIBLE&page=1&limit=20" \
  -H "Authorization: Bearer <token>"

Query Parameters

page

integer

default:"1"

Número de página a recuperar. La primera página es 1.

limit

integer

default:"20"

Cantidad de registros por página.

string

Texto libre. Busca coincidencias parciales en los campos titulo, isbn y editorial simultáneamente.

tipo

string

Filtra por tipo de material. Valores aceptados: LIBRO, REVISTA, DVD, PERIODICO, OTRO.

estado

string

Filtra por estado del material. Valores aceptados: DISPONIBLE, PRESTADO, EN_REPARACION, DADO_DE_BAJA.

autorId

integer

Filtra todos los materiales asociados a un autor específico por su ID numérico.

categoriaId

integer

Filtra todos los materiales pertenecientes a una categoría específica por su ID numérico.

Response

{
  "success": true,
  "message": "Datos obtenidos correctamente",
  "data": [
    {
      "id": 1,
      "titulo": "Cien Años de Soledad",
      "tipo": "LIBRO",
      "estado": "DISPONIBLE",
      "isbn": "978-0-06-088328-7",
      "anioPubl": 1967,
      "editorial": "Editorial Sudamericana",
      "descripcion": "Novela del realismo mágico.",
      "stock": 3,
      "autorId": 5,
      "categoriaId": 2,
      "autor": {
        "nombre": "Gabriel",
        "apellido": "García Márquez"
      },
      "categoria": {
        "nombre": "Literatura Latinoamericana"
      }
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 142,
    "totalPages": 8
  }
}

GET /api/materiales/:id

Devuelve el detalle completo de un material por su ID. Incluye el objeto autor completo, el objeto categoria completo y la lista de préstamos con estado ACTIVO con los datos del socio que los tiene.

curl -X GET "https://api.biblioteca.com/api/materiales/1" \
  -H "Authorization: Bearer <token>"

Path Parameters

integer

required

ID numérico único del material.

Response

{
  "success": true,
  "message": "Operación exitosa",
  "data": {
    "id": 1,
    "titulo": "Cien Años de Soledad",
    "tipo": "LIBRO",
    "estado": "DISPONIBLE",
    "isbn": "978-0-06-088328-7",
    "anioPubl": 1967,
    "editorial": "Editorial Sudamericana",
    "descripcion": "Novela del realismo mágico.",
    "stock": 3,
    "autorId": 5,
    "categoriaId": 2,
    "autor": {
      "id": 5,
      "nombre": "Gabriel",
      "apellido": "García Márquez",
      "nacionalidad": "Colombiana",
      "biografia": "Escritor y periodista colombiano..."
    },
    "categoria": {
      "id": 2,
      "nombre": "Literatura Latinoamericana"
    },
    "prestamos": [
      {
        "id": 18,
        "estado": "ACTIVO",
        "fechaPrestamo": "2024-11-01T10:00:00.000Z",
        "fechaDevolucion": "2024-12-01T10:00:00.000Z",
        "socio": {
          "nombre": "María",
          "apellido": "López"
        }
      }
    ]
  }
}

404 Not Found si el ID no corresponde a ningún material registrado.

POST /api/materiales

Registra un nuevo material en el catálogo. Los campos titulo, tipo, autorId y categoriaId son obligatorios. Si se proporciona un isbn, debe ser único en el sistema.

curl -X POST "https://api.biblioteca.com/api/materiales" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "titulo": "El Coronel no tiene quien le escriba",
    "tipo": "LIBRO",
    "autorId": 5,
    "categoriaId": 2,
    "isbn": "978-0-06-112009-9",
    "anioPubl": 1961,
    "editorial": "Era",
    "descripcion": "Una historia de dignidad y espera.",
    "stock": 2
  }'

Body Parameters

titulo

string

required

Título completo del material. No puede estar vacío. Se recorta de espacios en los extremos.

tipo

string

required

Tipo de material. Debe ser exactamente uno de: LIBRO, REVISTA, DVD, PERIODICO, OTRO.

autorId

integer

required

ID numérico del autor existente en el sistema. Debe ser un entero mayor o igual a 1.

categoriaId

integer

required

ID numérico de la categoría existente en el sistema. Debe ser un entero mayor o igual a 1.

isbn

string

Código ISBN del material. Opcional, pero si se envía debe ser único en todo el catálogo.

anioPubl

integer

Año de publicación. Debe ser un entero entre 1000 y el año en curso (inclusive).

editorial

string

Nombre de la editorial o casa publicadora.

descripcion

string

Descripción o sinopsis del material.

stock

integer

Número de ejemplares disponibles. Debe ser un entero mayor o igual a 1. Si se omite, el sistema aplica el valor por defecto del esquema de base de datos.

Response `201 Created`

{
  "success": true,
  "message": "Material registrado correctamente",
  "data": {
    "id": 57,
    "titulo": "El Coronel no tiene quien le escriba",
    "tipo": "LIBRO",
    "estado": "DISPONIBLE",
    "isbn": "978-0-06-112009-9",
    "anioPubl": 1961,
    "editorial": "Era",
    "descripcion": "Una historia de dignidad y espera.",
    "stock": 2,
    "autorId": 5,
    "categoriaId": 2,
    "autor": {
      "nombre": "Gabriel",
      "apellido": "García Márquez"
    },
    "categoria": {
      "nombre": "Literatura Latinoamericana"
    }
  }
}

Error Responses

Código	Motivo
`400 Bad Request`	Falta un campo requerido o algún valor no pasa la validación (p. ej., `tipo` inválido, `stock` menor a `1`).
`409 Conflict`	El `isbn` proporcionado ya está registrado en el catálogo.

PUT /api/materiales/:id

Actualiza uno o más campos de un material existente. Todos los campos del cuerpo son opcionales; sólo se modifican los que se envíen.

curl -X PUT "https://api.biblioteca.com/api/materiales/57" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "editorial": "Oveja Negra",
    "stock": 4
  }'

Path Parameters

integer

required

ID numérico del material a actualizar.

Body Parameters

titulo

string

Nuevo título del material.

tipo

string

Nuevo tipo. Debe ser uno de: LIBRO, REVISTA, DVD, PERIODICO, OTRO.

autorId

integer

ID del nuevo autor asociado. Debe ser un entero mayor o igual a 1.

categoriaId

integer

ID de la nueva categoría asociada. Debe ser un entero mayor o igual a 1.

isbn

string

Nuevo ISBN. Debe ser único en el catálogo si se modifica.

anioPubl

integer

Nuevo año de publicación. Debe ser un entero entre 1000 y el año en curso.

editorial

string

Nueva editorial.

descripcion

string

Nueva descripción o sinopsis.

stock

integer

Nuevo valor de stock. Debe ser un entero mayor o igual a 1.

Response

{
  "success": true,
  "message": "Material actualizado correctamente",
  "data": {
    "id": 57,
    "titulo": "El Coronel no tiene quien le escriba",
    "tipo": "LIBRO",
    "estado": "DISPONIBLE",
    "isbn": "978-0-06-112009-9",
    "anioPubl": 1961,
    "editorial": "Oveja Negra",
    "descripcion": "Una historia de dignidad y espera.",
    "stock": 4,
    "autorId": 5,
    "categoriaId": 2,
    "autor": {
      "nombre": "Gabriel",
      "apellido": "García Márquez"
    },
    "categoria": {
      "nombre": "Literatura Latinoamericana"
    }
  }
}

404 Not Found si el ID no existe.

DELETE /api/materiales/:id

Elimina permanentemente un material del catálogo. La operación falla con 409 Conflict si el material tiene préstamos con estado ACTIVO en ese momento.

curl -X DELETE "https://api.biblioteca.com/api/materiales/57" \
  -H "Authorization: Bearer <token>"

Path Parameters

integer

required

ID numérico del material a eliminar.

Response

{
  "success": true,
  "message": "Operación exitosa",
  "data": {
    "message": "Material eliminado correctamente"
  }
}

Error Responses

Código	Motivo
`404 Not Found`	El ID no corresponde a ningún material registrado.
`409 Conflict`	El material tiene uno o más préstamos con estado `ACTIVO`. Registra la devolución antes de eliminar.

Autenticación

Recursos

API REST para materiales del catálogo de la biblioteca

GET /api/materiales

Query Parameters

Response

GET /api/materiales/:id

Path Parameters

Response

POST /api/materiales

Body Parameters

Response `201 Created`

Error Responses

PUT /api/materiales/:id

Path Parameters

Body Parameters

Response

DELETE /api/materiales/:id

Path Parameters

Response

Error Responses

Build docs developers (and LLMs) love

Autenticación

Recursos

Documentation Index

​GET /api/materiales

​Query Parameters

​Response

​GET /api/materiales/:id

​Path Parameters

​Response

​POST /api/materiales

​Body Parameters

​Response 201 Created

​Error Responses

​PUT /api/materiales/:id

​Path Parameters

​Body Parameters

​Response

​DELETE /api/materiales/:id

​Path Parameters

​Response

​Error Responses

Build docs developers (and LLMs) love

GET /api/materiales

Query Parameters

Response

GET /api/materiales/:id

Path Parameters

Response

POST /api/materiales

Body Parameters

Response `201 Created`

Error Responses

PUT /api/materiales/:id

Path Parameters

Body Parameters

Response

DELETE /api/materiales/:id

Path Parameters

Response

Error Responses