🔍 Buscar Cajeros (JWT)

Busca cajeros en el sistema utilizando diferentes criterios de filtrado y autenticación JWT. Este endpoint permite realizar búsquedas avanzadas por nombre, apellidos, estado, fechas y otros parámetros, devolviendo resultados paginados con información adicional basada en los permisos del usuario.

ℹ️ Información

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

ℹ️ Nota Importante

Este endpoint requiere autenticación JWT. El token debe incluirse en el header Authorization como "Bearer {token}".

📋 Información del Endpoint

GET /api/cajeros/jwt/search

Busca cajeros en el sistema utilizando diferentes criterios de filtrado y autenticación JWT.

🔐 Headers de Autenticación

Header	Tipo	Requerido	Descripción
Authorization	string	Sí	Token JWT en formato "Bearer {token}"

📥 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)
includeStats	boolean	No	Incluir estadísticas de búsqueda (solo para usuarios con permisos)

📤 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
401 Unauthorized	Token JWT inválido o expirado	Token no proporcionado o inválido
403 Forbidden	Sin permisos para acceder a estadísticas	El usuario no tiene permisos para includeStats
500 Internal Server Error	Error interno del servidor	Error en la base de datos o procesamiento

🔧 Ejemplos de Uso

Ejemplo 1: Búsqueda General con JWT

Petición

GET /api/cajeros/jwt/search?searchTerm=maria&page=1&pageSize=10
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

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: Búsqueda con Estadísticas (Usuario con Permisos)

Petición

GET /api/cajeros/jwt/search?estado=A&includeStats=true
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

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"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "totalItems": 1,
      "totalPages": 1,
      "hasNextPage": false,
      "hasPreviousPage": false
    },
    "statistics": {
      "totalCajeros": 15,
      "cajerosActivos": 12,
      "cajerosInactivos": 3,
      "promedioAntiguedad": "2.5 años",
      "ultimaAlta": "2024-03-20T00:00:00"
    }
  }
}

Ejemplo 3: Error - Token JWT Inválido

Petición

GET /api/cajeros/jwt/search?searchTerm=maria
Authorization: Bearer invalid_token

Respuesta de Error (401 Unauthorized)

{
  "success": false,
  "message": "Token JWT inválido o expirado",
  "error": "Invalid token format"
}

ℹ️ Notas Importantes

Autenticación JWT: Este endpoint requiere un token JWT válido en el header Authorization.
Formato del token: Debe incluirse como "Bearer {token}" en el header Authorization.
Permisos: El usuario debe tener permisos para buscar cajeros. Para estadísticas se requieren permisos adicionales.
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).
Estadísticas: El parámetro includeStats requiere permisos especiales y proporciona información adicional.
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.

🔒 Seguridad

Autenticación: Requiere token JWT válido
Autorización: Verifica permisos del usuario para buscar cajeros
Estadísticas: Requiere permisos adicionales para acceder a estadísticas
Auditoría: Se registran las búsquedas para fines de auditoría
Validación: Se validan todos los parámetros de entrada

⚡ 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.
Estadísticas: Las estadísticas se calculan de forma eficiente usando agregaciones.