API REST para préstamos y devoluciones de materiales

Los endpoints bajo /api/prestamos gestionan el ciclo completo de préstamo de materiales: alta, devolución y actualización de mora. El servidor aplica reglas de negocio en orden antes de confirmar cualquier operación. La fecha de devolución esperada se calcula automáticamente a 30 días desde la fecha del préstamo (DIAS_PRESTAMO = 30). El estado del socio y el material se actualizan transaccionalmente junto con el registro del préstamo.

Todas las rutas de este recurso requieren autenticación mediante Bearer token. Incluye la cabecera Authorization: Bearer <token> en cada solicitud. Un token inválido o ausente devuelve 401 Unauthorized.

GET /api/prestamos

Devuelve una lista paginada de préstamos. Cada elemento incluye los datos del socio (id, nombre, apellido, dni) y del material (id, titulo, tipo, isbn) de forma anidada. Los resultados se ordenan del más reciente al más antiguo.

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

Query Parameters

page

integer

default:"1"

Número de página a recuperar.

limit

integer

default:"20"

Cantidad de registros por página.

estado

string

Filtra por estado del préstamo. Valores aceptados: ACTIVO, DEVUELTO, MORA.

socioId

integer

Devuelve únicamente los préstamos del socio con ese ID.

materialId

integer

Devuelve únicamente los préstamos asociados al material con ese ID.

Response

{
  "success": true,
  "message": "Datos obtenidos correctamente",
  "data": [
    {
      "id": 18,
      "estado": "ACTIVO",
      "fechaPrestamo": "2024-11-01T10:00:00.000Z",
      "fechaDevolucion": "2024-12-01T10:00:00.000Z",
      "fechaDevReal": null,
      "observaciones": null,
      "socioId": 12,
      "materialId": 1,
      "socio": {
        "id": 12,
        "nombre": "María",
        "apellido": "López",
        "dni": "30456789"
      },
      "material": {
        "id": 1,
        "titulo": "Cien Años de Soledad",
        "tipo": "LIBRO",
        "isbn": "978-0-06-088328-7"
      }
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 53,
    "totalPages": 3
  }
}

GET /api/prestamos/:id

Devuelve el detalle completo de un préstamo por su ID. Incluye el objeto socio completo y el objeto material con sus relaciones autor y categoria anidadas.

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

Path Parameters

integer

required

ID numérico único del préstamo.

Response

{
  "success": true,
  "message": "Operación exitosa",
  "data": {
    "id": 18,
    "estado": "ACTIVO",
    "fechaPrestamo": "2024-11-01T10:00:00.000Z",
    "fechaDevolucion": "2024-12-01T10:00:00.000Z",
    "fechaDevReal": null,
    "observaciones": "El socio solicitó renovación en su momento.",
    "socioId": 12,
    "materialId": 1,
    "socio": {
      "id": 12,
      "nombre": "María",
      "apellido": "López",
      "dni": "30456789",
      "email": "maria.lopez@email.com",
      "estado": "ACTIVO"
    },
    "material": {
      "id": 1,
      "titulo": "Cien Años de Soledad",
      "tipo": "LIBRO",
      "isbn": "978-0-06-088328-7",
      "estado": "PRESTADO",
      "autor": {
        "id": 5,
        "nombre": "Gabriel",
        "apellido": "García Márquez"
      },
      "categoria": {
        "id": 2,
        "nombre": "Literatura Latinoamericana"
      }
    }
  }
}

404 Not Found si el ID no corresponde a ningún préstamo registrado.

POST /api/prestamos

Crea un nuevo préstamo. El servidor ejecuta tres validaciones de negocio en orden antes de persistir el registro. Si alguna falla, la operación se cancela por completo. La fecha de devolución esperada se asigna automáticamente a 30 días desde el momento de la creación (DIAS_PRESTAMO = 30). Al crear el préstamo, si todos los ejemplares del material quedan prestados, su estado se actualiza automáticamente a PRESTADO dentro de la misma transacción.

El servidor valida tres reglas de negocio antes de crear el préstamo. Si alguna no se cumple, la respuesta es 409 Conflict:

Estado del socio: el socio debe tener estado ACTIVO. Los socios con estado MOROSO o SUSPENDIDO no pueden recibir préstamos.
Límite de préstamos activos: el socio no puede tener más de 3 préstamos (MAX_PRESTAMOS_ACTIVOS = 3) con estado ACTIVO o MORA al mismo tiempo.
Disponibilidad del material: el material debe tener estado DISPONIBLE y la cantidad de préstamos simultáneos activos o en mora debe ser menor al stock total del material.

curl -X POST "https://api.biblioteca.com/api/prestamos" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "socioId": 12,
    "materialId": 1,
    "observaciones": "El socio solicitó el material en persona."
  }'

Body Parameters

socioId

integer

required

ID numérico del socio que realiza el préstamo. Debe ser un entero mayor o igual a 1.

materialId

integer

required

ID numérico del material a prestar. Debe ser un entero mayor o igual a 1.

observaciones

string

Notas opcionales sobre el préstamo. El valor se recorta de espacios en los extremos antes de guardarse.

Response `201 Created`

{
  "success": true,
  "message": "Préstamo registrado correctamente",
  "data": {
    "id": 19,
    "estado": "ACTIVO",
    "fechaPrestamo": "2024-11-15T14:30:00.000Z",
    "fechaDevolucion": "2024-12-15T14:30:00.000Z",
    "fechaDevReal": null,
    "observaciones": "El socio solicitó el material en persona.",
    "socioId": 12,
    "materialId": 1,
    "socio": {
      "nombre": "María",
      "apellido": "López"
    },
    "material": {
      "titulo": "Cien Años de Soledad"
    }
  }
}

Error Responses

Código	Motivo
`400 Bad Request`	Falta `socioId` o `materialId`, o alguno no es un entero válido mayor o igual a `1`.
`404 Not Found`	El socio o el material no existen en el sistema.
`409 Conflict`	El socio está `MOROSO` o `SUSPENDIDO`, ya alcanzó el límite de `3` préstamos activos o en mora, o el material no está `DISPONIBLE` / no tiene ejemplares libres.

PATCH /api/prestamos/:id/devolver

Registra la devolución de un préstamo. El servidor actualiza el estado del préstamo a DEVUELTO, asigna la fechaDevReal con la fecha y hora actuales, y restaura el estado del material a DISPONIBLE. Si el socio ya no tiene préstamos en mora tras esta devolución, su estado también vuelve a ACTIVO automáticamente. Esta operación no requiere cuerpo en la petición.

curl -X PATCH "https://api.biblioteca.com/api/prestamos/18/devolver" \
  -H "Authorization: Bearer <token>"

Path Parameters

integer

required

ID numérico del préstamo a devolver.

Response

{
  "success": true,
  "message": "Devolución registrada correctamente",
  "data": {
    "id": 18,
    "estado": "DEVUELTO",
    "fechaPrestamo": "2024-11-01T10:00:00.000Z",
    "fechaDevolucion": "2024-12-01T10:00:00.000Z",
    "fechaDevReal": "2024-11-28T09:15:00.000Z",
    "observaciones": null,
    "socioId": 12,
    "materialId": 1,
    "socio": {
      "nombre": "María",
      "apellido": "López"
    },
    "material": {
      "titulo": "Cien Años de Soledad"
    }
  }
}

Error Responses

Código	Motivo
`404 Not Found`	El ID no corresponde a ningún préstamo.
`409 Conflict`	El préstamo ya tiene estado `DEVUELTO`.

PATCH /api/prestamos/actualizar-mora

Recorre todos los préstamos con estado ACTIVO cuya fechaDevolucion sea anterior a la fecha y hora actuales, los marca como MORA y actualiza el estado de los socios afectados a MOROSO. La actualización se ejecuta en una única transacción atómica. Este endpoint no requiere cuerpo en la petición y devuelve el número de préstamos actualizados.

Se recomienda llamar a este endpoint antes de generar reportes de socios morosos o listados de préstamos vencidos, para asegurar que la información está al día. Puede integrarse en un job programado (cron) o invocarse manualmente desde el panel de administración.

curl -X PATCH "https://api.biblioteca.com/api/prestamos/actualizar-mora" \
  -H "Authorization: Bearer <token>"

Response — préstamos actualizados

{
  "success": true,
  "message": "Operación exitosa",
  "data": {
    "actualizados": 5,
    "message": "5 préstamo(s) actualizados a mora"
  }
}

Response — sin préstamos vencidos

{
  "success": true,
  "message": "Operación exitosa",
  "data": {
    "actualizados": 0,
    "message": "No hay préstamos en mora"
  }
}

Autenticación

Recursos

API REST para préstamos y devoluciones de materiales

GET /api/prestamos

Query Parameters

Response

GET /api/prestamos/:id

Path Parameters

Response

POST /api/prestamos

Body Parameters

Response `201 Created`

Error Responses

PATCH /api/prestamos/:id/devolver

Path Parameters

Response

Error Responses

PATCH /api/prestamos/actualizar-mora

Response — préstamos actualizados

Response — sin préstamos vencidos

Build docs developers (and LLMs) love

Autenticación

Recursos

Documentation Index

​GET /api/prestamos

​Query Parameters

​Response

​GET /api/prestamos/:id

​Path Parameters

​Response

​POST /api/prestamos

​Body Parameters

​Response 201 Created

​Error Responses

​PATCH /api/prestamos/:id/devolver

​Path Parameters

​Response

​Error Responses

​PATCH /api/prestamos/actualizar-mora

​Response — préstamos actualizados

​Response — sin préstamos vencidos

Build docs developers (and LLMs) love

GET /api/prestamos

Query Parameters

Response

GET /api/prestamos/:id

Path Parameters

Response

POST /api/prestamos

Body Parameters

Response `201 Created`

Error Responses

PATCH /api/prestamos/:id/devolver

Path Parameters

Response

Error Responses

PATCH /api/prestamos/actualizar-mora

Response — préstamos actualizados

Response — sin préstamos vencidos