← Volver a Back.API

💰 CajaController

Controlador especializado para la gestión completa del ciclo de vida de las cajas registradoras

📊 Resumen del Controlador

2
Servicios Inyectados
16
Endpoints Totales
8
Categorías de Operaciones
2
Tipos de Autenticación

El CajaController es un controlador especializado en la gestión completa del ciclo de vida de las cajas registradoras en el sistema RestMaster. Maneja operaciones críticas como apertura, cierre, validaciones y generación de arqueos con soporte dual de autenticación.

🎯 Funcionalidades Principales

  • Gestión del ciclo de caja - Apertura y cierre con validaciones (4 endpoints)
  • Estado de caja - Verificación en tiempo real del estado (2 endpoints)
  • Desglose de monedas - Gestión detallada de billetes y monedas (2 endpoints)
  • Configuración de monedas - Moneda principal y billetes disponibles (2 endpoints)
  • Validaciones de seguridad - Mesas abiertas y claves de cajero (2 endpoints)
  • Generación de arqueos - Reportes completos de caja (2 endpoints)
  • Autenticación dual - Tradicional y JWT para todos los endpoints
  • Integración con hardware - Soporte para cajas físicas BoxCashKeeper/BoxCashDro

🔧 Servicios Utilizados

Servicios Inyectados por Constructor:

  • ICajaService - Servicio principal de gestión de caja registradora
  • ILogger<CajaController> - Logging de errores y eventos

🔐 Tipos de Autenticación

El controlador soporta dos tipos de autenticación para cada operación:

  • Autenticación Tradicional: Mediante parámetros de consulta (initialCatalog, userID, password)
  • Autenticación JWT: Mediante token Bearer en el header Authorization

⚠️ Parámetros de Conexión

Los endpoints con autenticación tradicional requieren los siguientes parámetros:

  • initialCatalog (string): Nombre de la base de datos
  • userID (string, opcional): ID de usuario de la base de datos
  • password (string, opcional): Contraseña de la base de datos

📋 Categorías de Endpoints

📊 Estado de Caja

Verificación del estado actual de la caja (abierta/cerrada)
Status
GET

Endpoints: 2 métodos

  • GET /Estado (Tradicional)
  • GET /EstadoJwt (JWT)
Ver detalles →

🚪 Apertura de Caja

Apertura de una nueva caja con importe inicial y desglose
Operations
POST

Endpoints: 2 métodos

  • POST /Abrir (Tradicional)
  • POST /AbrirJwt (JWT)
Ver detalles →

🔒 Cierre de Caja

Cierre de la caja actual con importes finales y desglose
Operations
POST

Endpoints: 2 métodos

  • POST /Cerrar (Tradicional)
  • POST /CerrarJwt (JWT)
Ver detalles →

💰 Desglose de Monedas

Obtención del desglose detallado de monedas y billetes
Reports
GET

Endpoints: 2 métodos

  • GET /Desglose/{fecha}/{numeroCierre} (Tradicional)
  • GET /DesgloseJwt/{fecha}/{numeroCierre} (JWT)
Ver detalles →

🏦 Moneda Principal

Configuración de la moneda principal del sistema
Configuration
GET

Endpoints: 2 métodos

  • GET /MonedaPrincipal (Tradicional)
  • GET /MonedaPrincipalJwt (JWT)
Ver detalles →

💳 Billetes y Monedas

Lista completa de billetes y monedas configurados
Configuration
GET

Endpoints: 2 métodos

  • GET /BilletesMonedas (Tradicional)
  • GET /BilletesMonedasJwt (JWT)
Ver detalles →

🔍 Validación de Mesas

Validación de mesas abiertas antes del cierre
Validation
GET

Endpoints: 2 métodos

  • GET /ValidarMesasAbiertas (Tradicional)
  • GET /ValidarMesasAbiertasJwt (JWT)
Ver detalles →

🔐 Validación de Claves

Validación de claves de cajero
Security
GET

Endpoints: 2 métodos

  • GET /ValidarClaveCajero (Tradicional)
  • GET /ValidarClaveCajeroJwt (JWT)
Ver detalles →

📈 Generación de Arqueos

Generación de arqueos completos de caja
Reports
GET

Endpoints: 2 métodos

  • GET /GenerarArqueo (Tradicional)
  • GET /GenerarArqueoJwt (JWT)
Ver detalles →

🔗 Estructura de Rutas

Ruta Base: /Working/Caja

Todos los endpoints del controlador están bajo la ruta /Working/Caja, lo que indica que maneja datos de trabajo operativo del sistema.

Patrones de URL por Categoría:

📊 Códigos de Respuesta

✅ 200 - OK

Operación exitosa, datos devueltos correctamente

Usado en: GET exitosos, POST exitosos

❌ 400 - Bad Request

Datos de entrada inválidos o validación fallida

Usado en: Errores de validación en apertura/cierre

❌ 401 - Unauthorized

Token JWT inválido o expirado

Usado en: Endpoints JWT con autenticación fallida

❌ 500 - Internal Server Error

Error interno del servidor

Usado en: Errores de excepción no controlados

🔍 Características Técnicas

🎯 Características del Controlador

  • Async/Await: Todos los métodos son asíncronos para mejor rendimiento
  • Swagger Documentation: Documentación completa con Swagger/OpenAPI
  • Error Handling: Manejo centralizado de excepciones con logging
  • Dependency Injection: Inyección de servicios por constructor
  • RESTful Design: Diseño REST con verbos HTTP apropiados
  • Type Safety: Uso de tipos fuertemente tipados para respuestas
  • JWT Validation: Validación automática de tokens JWT
  • Logging: Logging estructurado de errores y eventos

⚠️ Consideraciones de Seguridad

  • Validación de JWT tokens en todos los endpoints protegidos
  • Validación de claves de cajero antes de operaciones críticas
  • Verificación de mesas abiertas antes del cierre de caja
  • Los errores internos se loguean pero no exponen información sensible
  • Se recomienda usar HTTPS en producción

📝 Patrones de Diseño Utilizados

  • Repository Pattern: Acceso a datos a través de servicios
  • Dependency Injection: Inversión de control para servicios
  • Async/Await Pattern: Programación asíncrona
  • Error Handling Pattern: Manejo centralizado de errores
  • RESTful API Design: Diseño de API REST estándar
  • Dual Authentication Pattern: Soporte para múltiples métodos de autenticación

📈 Estadísticas Detalladas

832
Líneas de Código
16
Métodos Públicos
2
Verbos HTTP
8
Categorías Funcionales

Distribución de Métodos HTTP:

Distribución por Tipo de Autenticación:

📋 Modelos de Datos

DTOs Utilizados

  • CajaAperturaRequest: Datos para apertura de caja
  • CajaCierreRequest: Datos para cierre de caja
  • ArqueoCajaResponse: Respuesta del arqueo de caja

⚠️ Validaciones Importantes

  • Verificación de caja ya abierta antes de apertura
  • Verificación de caja abierta antes de cierre
  • Validación de mesas abiertas antes del cierre
  • Validación de claves de cajero
  • Validación de tokens JWT

© 2024 RestMaster - CajaController - Documentación Completa