API de socios: registro, búsqueda, edición y préstamos

Los endpoints bajo /api/socios permiten gestionar el padrón completo de socios de la biblioteca: consultar, registrar, actualizar y eliminar socios, además de acceder al historial de préstamos de cada uno. Todos los endpoints aplican el middleware de autenticación a nivel de router — no existe ninguna ruta pública dentro de este grupo.

Todos los endpoints requieren el encabezado Authorization: Bearer <accessToken>. Obtén el token a través de POST /api/auth/login.

Formato de respuesta estándar

Los endpoints de listado utilizan la envoltura paginada:

{
  "success": true,
  "message": "Datos obtenidos correctamente",
  "data": [ ... ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Los endpoints de recurso único, creación y actualización utilizan la envoltura estándar:

{
  "success": true,
  "message": "Descripción de la operación",
  "data": { ... }
}

GET /api/socios

Autenticación requerida: Sí Devuelve la lista paginada de todos los socios registrados. Admite búsqueda de texto libre sobre nombre, apellido, dni y email. Los resultados se ordenan alfabéticamente por apellido. Cada socio en el listado incluye el conteo total de sus préstamos (_count.prestamos).

Query params

page

integer

Número de página a recuperar. Por defecto 1.

limit

integer

Cantidad de socios por página. Por defecto 20.

string

Texto libre para filtrar. Busca coincidencias parciales en nombre, apellido, dni y email.

estado

string

Filtra socios por estado (p. ej. ACTIVO, INACTIVO). Si se omite, devuelve socios de todos los estados.

Response

success

boolean

true si la operación fue exitosa.

message

string

"Datos obtenidos correctamente"

data

array

Array de objetos socio. Ver estructura en el ejemplo.

Ejemplo

curl -X GET "https://api.bibliotecalapalabra.com/api/socios?page=1&limit=20&search=garcía" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

{
  "success": true,
  "message": "Datos obtenidos correctamente",
  "data": [
    {
      "id": 42,
      "nombre": "Laura",
      "apellido": "García",
      "dni": "30456789",
      "email": "laura.garcia@ejemplo.com",
      "telefono": "+54 9 11 5678-1234",
      "direccion": "Av. Corrientes 1234, CABA",
      "estado": "ACTIVO",
      "createdAt": "2024-03-01T09:00:00.000Z",
      "updatedAt": "2024-06-15T14:30:00.000Z",
      "_count": {
        "prestamos": 7
      }
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}

Errores

Código	Motivo
`401`	Token ausente, inválido o expirado.

GET /api/socios/:id

Autenticación requerida: Sí Devuelve el detalle completo de un socio por su ID. Incluye los últimos 10 préstamos del socio (con el título del material asociado a cada uno) y el conteo total de préstamos.

Path params

integer

required

ID numérico del socio.

Response

success

boolean

true si el socio fue encontrado.

message

string

"Operación exitosa"

data

object

Show data

integer

ID único del socio.

nombre

string

Nombre del socio.

apellido

string

Apellido del socio.

dni

string

Documento Nacional de Identidad (único en el sistema).

string | null

Correo electrónico del socio. Puede ser null.

telefono

string | null

Teléfono de contacto. Puede ser null.

direccion

string | null

Domicilio del socio. Puede ser null.

estado

string

Estado del socio (p. ej. ACTIVO, INACTIVO).

prestamos

array

Los últimos 10 préstamos del socio, ordenados por fechaPrestamo descendente. Cada objeto incluye los datos del préstamo y el campo material.titulo.

_count

object

Contiene prestamos (integer): total histórico de préstamos del socio.

createdAt

string (ISO 8601)

Fecha de registro del socio.

updatedAt

string (ISO 8601)

Fecha de la última modificación.

Ejemplo

curl -X GET https://api.bibliotecalapalabra.com/api/socios/42 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

{
  "success": true,
  "message": "Operación exitosa",
  "data": {
    "id": 42,
    "nombre": "Laura",
    "apellido": "García",
    "dni": "30456789",
    "email": "laura.garcia@ejemplo.com",
    "telefono": "+54 9 11 5678-1234",
    "direccion": "Av. Corrientes 1234, CABA",
    "estado": "ACTIVO",
    "prestamos": [
      {
        "id": 201,
        "fechaPrestamo": "2024-06-10T10:00:00.000Z",
        "fechaDevolucion": "2024-06-24T10:00:00.000Z",
        "estado": "DEVUELTO",
        "material": {
          "titulo": "Cien años de soledad"
        }
      }
    ],
    "_count": { "prestamos": 7 },
    "createdAt": "2024-03-01T09:00:00.000Z",
    "updatedAt": "2024-06-15T14:30:00.000Z"
  }
}

Errores

Código	Motivo
`401`	Token ausente, inválido o expirado.
`404`	No existe ningún socio con el ID indicado.

GET /api/socios/:id/prestamos

Autenticación requerida: Sí Devuelve el historial completo de préstamos de un socio, ordenados por fechaPrestamo de forma descendente (el más reciente primero). A diferencia de GET /api/socios/:id, aquí no hay límite de 10 registros. Cada préstamo incluye el titulo y tipo del material asociado.

Path params

integer

required

ID numérico del socio.

Response

success

boolean

true si la operación fue exitosa.

message

string

"Operación exitosa"

data

array

Array con todos los préstamos del socio. Cada objeto incluye los campos del préstamo y el objeto material con titulo y tipo.

Ejemplo

curl -X GET https://api.bibliotecalapalabra.com/api/socios/42/prestamos \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

{
  "success": true,
  "message": "Operación exitosa",
  "data": [
    {
      "id": 201,
      "socioId": 42,
      "materialId": 15,
      "fechaPrestamo": "2024-06-10T10:00:00.000Z",
      "fechaDevolucion": "2024-06-24T10:00:00.000Z",
      "estado": "DEVUELTO",
      "material": {
        "titulo": "Cien años de soledad",
        "tipo": "LIBRO"
      }
    },
    {
      "id": 187,
      "socioId": 42,
      "materialId": 8,
      "fechaPrestamo": "2024-05-01T10:00:00.000Z",
      "fechaDevolucion": "2024-05-15T10:00:00.000Z",
      "estado": "DEVUELTO",
      "material": {
        "titulo": "El Aleph",
        "tipo": "LIBRO"
      }
    }
  ]
}

Errores

Código	Motivo
`401`	Token ausente, inválido o expirado.
`404`	No existe ningún socio con el ID indicado.

POST /api/socios

Autenticación requerida: Sí Registra un nuevo socio en el sistema. El dni debe ser único — si ya existe un socio con ese documento, la operación falla con 409 Conflict. HTTP 201 Created se devuelve al crear el socio exitosamente.

Request body

nombre

string

required

Nombre del socio. No puede estar vacío. Se aplica trim automático.

apellido

string

required

Apellido del socio. No puede estar vacío. Se aplica trim automático.

dni

string

required

Documento Nacional de Identidad del socio. Debe ser único en el sistema. Se aplica trim automático.

string

Correo electrónico del socio. Opcional. Si se provee, debe ser un email válido. Se normaliza automáticamente. Los valores falsy ("", null) son tratados como ausentes.

telefono

string

Teléfono de contacto. Opcional. Se aplica trim automático.

direccion

string

Domicilio del socio. Opcional. Se aplica trim automático.

Response

HTTP 201 Created

success

boolean

true si el socio fue creado exitosamente.

message

string

"Socio registrado correctamente"

data

object

Objeto del socio recién creado con todos sus campos.

Ejemplo

curl -X POST https://api.bibliotecalapalabra.com/api/socios \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Carlos",
    "apellido": "Rodríguez",
    "dni": "28901234",
    "email": "carlos.rodriguez@ejemplo.com",
    "telefono": "+54 9 11 4321-8765",
    "direccion": "Calle Falsa 123, Buenos Aires"
  }'

{
  "success": true,
  "message": "Socio registrado correctamente",
  "data": {
    "id": 58,
    "nombre": "Carlos",
    "apellido": "Rodríguez",
    "dni": "28901234",
    "email": "carlos.rodriguez@ejemplo.com",
    "telefono": "+54 9 11 4321-8765",
    "direccion": "Calle Falsa 123, Buenos Aires",
    "estado": "ACTIVO",
    "createdAt": "2024-07-20T11:00:00.000Z",
    "updatedAt": "2024-07-20T11:00:00.000Z"
  }
}

Errores

Código	Motivo
`401`	Token ausente, inválido o expirado.
`409`	Ya existe un socio registrado con el mismo DNI.
`422`	Faltan campos requeridos (`nombre`, `apellido`, `dni`) o el email tiene formato inválido.

PUT /api/socios/:id

Autenticación requerida: Sí Actualiza los datos de un socio existente. Todos los campos del body son opcionales — solo se modifican los campos que se envíen. La validación de ruta cubre únicamente nombre, apellido y email: si se incluyen, no pueden ser cadenas vacías (nombre, apellido) y el email debe ser válido.

Path params

integer

required

ID numérico del socio a actualizar.

Request body

nombre

string

Nuevo nombre del socio. Opcional. Si se incluye, no puede estar vacío. Se aplica trim automático.

apellido

string

Nuevo apellido del socio. Opcional. Si se incluye, no puede estar vacío. Se aplica trim automático.

string

Nuevo email del socio. Opcional. Si se incluye, debe ser un email válido. Los valores falsy son tratados como ausentes.

Response

success

boolean

true si el socio fue actualizado.

message

string

"Socio actualizado correctamente"

data

object

Objeto del socio actualizado con todos sus campos persistidos.

Ejemplo

curl -X PUT https://api.bibliotecalapalabra.com/api/socios/58 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "carlos.nuevo@ejemplo.com",
    "apellido": "Rodríguez Pérez"
  }'

{
  "success": true,
  "message": "Socio actualizado correctamente",
  "data": {
    "id": 58,
    "nombre": "Carlos",
    "apellido": "Rodríguez Pérez",
    "dni": "28901234",
    "email": "carlos.nuevo@ejemplo.com",
    "telefono": "+54 9 11 4321-8765",
    "direccion": "Calle Falsa 123, Buenos Aires",
    "estado": "ACTIVO",
    "createdAt": "2024-07-20T11:00:00.000Z",
    "updatedAt": "2024-07-21T08:45:00.000Z"
  }
}

Errores

Código	Motivo
`401`	Token ausente, inválido o expirado.
`404`	No existe ningún socio con el ID indicado.
`422`	`nombre` o `apellido` están vacíos, o el email tiene formato inválido.

DELETE /api/socios/:id

Autenticación requerida: Sí Elimina un socio del sistema de forma permanente. La operación falla con 409 Conflict si el socio tiene préstamos con estado ACTIVO en ese momento — el socio debe devolver todos los materiales antes de poder ser eliminado.

Esta operación es irreversible. El socio y todos sus datos serán eliminados permanentemente de la base de datos.

Path params

integer

required

ID numérico del socio a eliminar.

Response

success

boolean

true si el socio fue eliminado.

message

string

"Operación exitosa"

data

object

Show data

message

string

"Socio eliminado correctamente"

Ejemplo

curl -X DELETE https://api.bibliotecalapalabra.com/api/socios/58 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

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

Errores

Código	Motivo
`401`	Token ausente, inválido o expirado.
`404`	No existe ningún socio con el ID indicado.
`409`	El socio tiene uno o más préstamos con estado `ACTIVO`. Debe devolver los materiales antes de poder ser eliminado.

Autenticación

Recursos

API de socios: registro, búsqueda, edición y préstamos

Formato de respuesta estándar

GET /api/socios

Query params

Response

Ejemplo

Errores

GET /api/socios/:id

Path params

Response

Ejemplo

Errores

GET /api/socios/:id/prestamos

Path params

Response

Ejemplo

Errores

POST /api/socios

Request body

Response

Ejemplo

Errores

PUT /api/socios/:id

Path params

Request body

Response

Ejemplo

Errores

DELETE /api/socios/:id

Path params

Response

Ejemplo

Errores

Build docs developers (and LLMs) love

Autenticación

Recursos

Documentation Index

​Formato de respuesta estándar

​GET /api/socios

​Query params

​Response

​Ejemplo

​Errores

​GET /api/socios/:id

​Path params

​Response

​Ejemplo

​Errores

​GET /api/socios/:id/prestamos

​Path params

​Response

​Ejemplo

​Errores

​POST /api/socios

​Request body

​Response

​Ejemplo

​Errores

​PUT /api/socios/:id

​Path params

​Request body

​Response

​Ejemplo

​Errores

​DELETE /api/socios/:id

​Path params

​Response

​Ejemplo

​Errores

Build docs developers (and LLMs) love

Formato de respuesta estándar

GET /api/socios

Query params

Response

Ejemplo

Errores

GET /api/socios/:id

Path params

Response

Ejemplo

Errores

GET /api/socios/:id/prestamos

Path params

Response

Ejemplo

Errores

POST /api/socios

Request body

Response

Ejemplo

Errores

PUT /api/socios/:id

Path params

Request body

Response

Ejemplo

Errores

DELETE /api/socios/:id

Path params

Response

Ejemplo

Errores