🔍 Buscar Cajeros

Busca cajeros en el sistema utilizando diferentes criterios de filtrado. Este endpoint permite realizar búsquedas avanzadas por nombre, apellidos, estado, fechas y otros parámetros, devolviendo resultados paginados.

ℹ️ Información

Este endpoint soporta búsqueda por texto libre, filtros específicos y paginación para manejar grandes volúmenes de datos.

📋 Información del Endpoint

GET /api/cajeros/search

Busca cajeros en el sistema utilizando diferentes criterios de filtrado.

📥 Parámetros de Consulta

Parámetro	Tipo	Requerido	Descripción
searchTerm	string	No	Término de búsqueda general (busca en nombre y apellidos)
nombre	string	No	Filtrar por nombre específico
apellidos	string	No	Filtrar por apellidos específicos
estado	string	No	Filtrar por estado (A=Activo, B=Baja)
fechaAltaDesde	string	No	Fecha de alta desde (ISO 8601)
fechaAltaHasta	string	No	Fecha de alta hasta (ISO 8601)
fechaBajaDesde	string	No	Fecha de baja desde (ISO 8601)
fechaBajaHasta	string	No	Fecha de baja hasta (ISO 8601)
page	int	No	Número de página (por defecto: 1)
pageSize	int	No	Tamaño de página (por defecto: 20, máximo: 100)
sortBy	string	No	Campo para ordenar (nombre, apellidos, fechaAlta, estado)
sortOrder	string	No	Orden de clasificación (asc, desc)

📤 Códigos de Respuesta

Código	Descripción	Ejemplo
200 OK	Búsqueda completada exitosamente	Se devuelven los resultados con paginación
400 Bad Request	Parámetros de búsqueda inválidos	Fechas en formato incorrecto o parámetros inválidos
500 Internal Server Error	Error interno del servidor	Error en la base de datos o procesamiento

🔧 Ejemplos de Uso

Ejemplo 1: Búsqueda General

Petición

GET /api/cajeros/search?searchTerm=maria&page=1&pageSize=10

Respuesta Exitosa (200 OK)

{
  "success": true,
  "message": "Búsqueda completada",
  "data": {
    "items": [
      {
        "id": 1,
        "nombre": "María",
        "apellidos": "García López",
        "estado": "A",
        "fechaAlta": "2024-01-15T00:00:00",
        "fechaBaja": null,
        "observaciones": "Cajero principal"
      },
      {
        "id": 7,
        "nombre": "Mariana",
        "apellidos": "Rodríguez",
        "estado": "A",
        "fechaAlta": "2024-03-20T00:00:00",
        "fechaBaja": null,
        "observaciones": null
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 10,
      "totalItems": 2,
      "totalPages": 1,
      "hasNextPage": false,
      "hasPreviousPage": false
    }
  }
}

Ejemplo 2: Filtro por Estado y Fechas

Petición

GET /api/cajeros/search?estado=A&fechaAltaDesde=2024-01-01&fechaAltaHasta=2024-12-31&sortBy=fechaAlta&sortOrder=desc

Respuesta Exitosa (200 OK)

{
  "success": true,
  "message": "Búsqueda completada",
  "data": {
    "items": [
      {
        "id": 7,
        "nombre": "Mariana",
        "apellidos": "Rodríguez",
        "estado": "A",
        "fechaAlta": "2024-03-20T00:00:00",
        "fechaBaja": null,
        "observaciones": null
      },
      {
        "id": 1,
        "nombre": "María",
        "apellidos": "García López",
        "estado": "A",
        "fechaAlta": "2024-01-15T00:00:00",
        "fechaBaja": null,
        "observaciones": "Cajero principal"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "totalItems": 2,
      "totalPages": 1,
      "hasNextPage": false,
      "hasPreviousPage": false
    }
  }
}

Ejemplo 3: Búsqueda con Paginación

Petición

GET /api/cajeros/search?page=2&pageSize=5&sortBy=apellidos&sortOrder=asc

Respuesta Exitosa (200 OK)

{
  "success": true,
  "message": "Búsqueda completada",
  "data": {
    "items": [
      {
        "id": 8,
        "nombre": "Luis",
        "apellidos": "Fernández",
        "estado": "A",
        "fechaAlta": "2023-08-10T00:00:00",
        "fechaBaja": null,
        "observaciones": null
      },
      {
        "id": 9,
        "nombre": "Ana",
        "apellidos": "González",
        "estado": "B",
        "fechaAlta": "2022-05-15T00:00:00",
        "fechaBaja": "2024-06-30T00:00:00",
        "observaciones": "Baja voluntaria"
      }
    ],
    "pagination": {
      "page": 2,
      "pageSize": 5,
      "totalItems": 12,
      "totalPages": 3,
      "hasNextPage": true,
      "hasPreviousPage": true
    }
  }
}

Ejemplo 4: Búsqueda Sin Resultados

Petición

GET /api/cajeros/search?nombre=Juanito&estado=A

Respuesta Exitosa (200 OK)

{
  "success": true,
  "message": "No se encontraron cajeros con los criterios especificados",
  "data": {
    "items": [],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "totalItems": 0,
      "totalPages": 0,
      "hasNextPage": false,
      "hasPreviousPage": false
    }
  }
}

ℹ️ Notas Importantes

Búsqueda por texto: El parámetro searchTerm busca en nombre y apellidos de forma flexible.
Filtros combinados: Se pueden combinar múltiples filtros para búsquedas más específicas.
Paginación: Por defecto devuelve 20 elementos por página, máximo 100.
Ordenamiento: Se puede ordenar por nombre, apellidos, fechaAlta o estado.
Fechas: Las fechas deben estar en formato ISO 8601 (YYYY-MM-DDTHH:mm:ss).
Estado: Solo se aceptan los valores "A" (Activo) y "B" (Baja).
Búsqueda case-insensitive: Las búsquedas de texto no distinguen entre mayúsculas y minúsculas.
Resultados vacíos: Si no hay resultados, se devuelve una lista vacía con información de paginación.

⚡ Rendimiento

Índices: La búsqueda utiliza índices optimizados en nombre, apellidos y estado.
Paginación: Se recomienda usar paginación para grandes volúmenes de datos.
Filtros: Los filtros específicos son más eficientes que la búsqueda por texto general.
Caché: Los resultados pueden estar cacheados para mejorar el rendimiento.