Resumen del alcance — Módulo Caja
Análisis Funcional: Módulo Caja — parte 1 de 7. Índice · Siguiente: Modelo de saldos →
El módulo Caja le agrega a la web app el control del efectivo físico de cada punto de venta: cuánta plata hay en el cajón, quién la puso, quién la sacó y contra qué transacción salió.
No reemplaza nada de lo que ya hacía la app — el Análisis Funcional original sigue vigente tal cual. Es una capa nueva que se enciende por país.
0.1 Qué problema resuelve y para quién
En Ecuador, cuando el cajero paga una transacción de Soterex, el efectivo lo controla el EPOS: el sistema propio de punto de venta que CIS ya opera ahí. La web app no necesita saber nada del cajón — le alcanza con descontar el prefondeo en USD y marcar la transacción como PAID.
Guatemala no tiene EPOS. Sin un sistema que lleve el efectivo del PDV, el cajero quedaba pagando contra un saldo que la app no conocía: la app sabía que la transacción se pagó, pero no si en el cajón había plata para pagarla ni cuánta quedó después. Eso es exactamente lo que el módulo Caja cubre.
Consecuencia de diseño, y es la regla más importante de todo el módulo:
El módulo Caja es opcional por país (flag
countries.modulo_caja, apagado por default). Con la bandera apagada, la app se comporta exactamente como antes de que el módulo existiera: no hay cajas, no hay apertura ni cierre, y el pago no valida ni escribe nada de caja. — Decisión #2 del plan v2 (2026-07-28), ADR-005. ✅ Implementado (TransactionController::pay()entra a la rama de caja solo si$country->modulo_caja).
Ecuador, que está en producción con su EPOS, no lo activa. Guatemala sí.
0.2 Qué incluye el módulo
| Capacidad | Estado |
|---|---|
| Varias cajas por sucursal, numeradas automáticamente — Caja 1, Caja 2… | ✅ Implementado |
| Alta y baja de cajas: una caja se desactiva y se reactiva (nunca se borra), con un panel «Administrar» en Estaciones / PDV | ✅ Implementado (G7, ADR-022) |
| Línea de país en Saldos: la plata que hay en las cajas de cada país, en su moneda, arriba de las tarjetas por PDV | ✅ Implementado (G6.C, ADR-022 §7) |
| Apertura y cierre de caja, con sesión abierta como precondición para operar | ✅ Implementado |
| Fondeo: sumar efectivo a una caja, con motivo | ✅ Implementado |
| Ajuste: corregir el saldo registrado contra el arqueo físico, en más o en menos, con motivo | ✅ Implementado |
| Descuento automático de la caja al pagar una transacción | ✅ Implementado |
| Tipo de cambio por país, con historial inmutable y auditoría | ✅ Implementado |
| Listado de movimientos por caja + export Excel/PDF con membrete | ✅ Implementado |
| Reporte de Cajas en Reportes: resumen por caja + detalle de movimientos, exportables | ✅ Implementado |
| Prefondeo País como capa propia, y el pago validando solo la caja | ✅ Implementado |
| Moneda de pago configurable por país — Guatemala paga en dólares | ✅ Implementado |
| Catálogo cerrado de motivos de fondeo y ajuste, con filtro en listado y export | ✅ Implementado en la pantalla de Caja; falta el filtro por motivo en Reportes → Cajas |
| Cierre diario: la caja opera solo el día en que se abrió; una sesión de un día anterior solo se puede cerrar | ✅ Implementado (B3, ADR-013) |
| Reporte de Cierres por día en Reportes: una fila por apertura de caja, con el saldo final del día, exportable | ✅ Implementado (B3.5) |
0.3 Qué explícitamente NO incluye
- No hay conteo de denominaciones. El cierre es por monto total, no por billetes y monedas (decisión #14 del plan v2). Un arqueo que no cuadra se resuelve con un
AJUSTE, no contando en pantalla. - No hay aprobación de pagos por Supervisor. Se decidió explícitamente no implementarla (decisión #7 del plan v2). No es una omisión: el flujo de pago no tiene paso de autorización.
- Tampoco hay autorización de Supervisor para abrir o cerrar caja. La hubo hasta E4b y se eliminó en la revisión del 2026-08-05: el control quedó en el ledger inmutable, no en una firma en el momento (ver 0.4).
- No hay borrado ni edición de movimientos. El ledger es inmutable; un error se corrige con un movimiento nuevo que lo compensa, nunca editando el anterior (ver Modelo de saldos §1.8).
- No hay borrado ni renombre de cajas. Se agregan y, desde G7, se desactivan y reactivan; una caja nunca se borra ni se renombra, y la numeración nunca se reutiliza, tampoco la de una caja de baja.
«No hay baja de cajas»fue cierto hasta el 2026-10-06 (ver R21 y 2.7). - No hay cierre automático a medianoche. El día se hace cumplir bloqueando, no cerrando solo: una caja que quedó abierta de ayer no paga, no se fondea y no se ajusta hasta que una persona la cierre y la abra de nuevo. Un cierre automático no podría esperar la papeleta firmada que exige el cierre ni tendría quién lo firme (ver 2.10).
- No gestiona la logística del efectivo. Los blindados, las transferencias bancarias y la relación con el banco viven afuera; la app registra que la plata llegó a la caja, no cómo viajó. Teresa fue explícita: "no va a haber un lugar donde se pongan los blindados, simplemente el blindado va a estar cuando llegue a la caja" (reunión 2026-08-05).
- No emite todavía los comprobantes membretados de apertura y cierre. Están decididos (decisiones #14 y #15 del plan v2) y las columnas existen en la base, pero nadie los genera hoy — llegan con E5, junto con la papeleta. Ver Preguntas Abiertas #7.
- No toca la integración con Soterex. El módulo Caja es control interno; lo que se le reporta a Soterex sale de la capa Holding, no de la caja.
0.4 Reglas de negocio de más alto nivel
Cada regla dice de dónde sale. Las veintitrés rigen hoy: las R9 a R17 llegaron con E4b, mergeada el 2026-08-06, las R18 y R19 con la entrega B3 del plan de ajustes v2 (2026-10-02), la R20 con la entrega G6 del plan de ajustes v3 (2026-10-06) y las R21 a R23 con la entrega G7 y la línea de país de G6.C del mismo plan (2026-10-06).
| # | Regla | Estado | Fuente |
|---|---|---|---|
| R1 | El módulo se activa por país; apagado, cero cambios de comportamiento | ✅ | Decisión #2 del plan v2, 2026-07-28 · ADR-005 |
| R2 | Ningún saldo se almacena — todos se derivan sumando su ledger | ✅ | ADR-005, 2026-07-31 |
| R3 | Los movimientos de caja son inmutables: se corrige compensando, nunca editando | ✅ | ADR-005, 2026-07-31 |
| R4 | La comisión nunca toca la caja — de la caja sale solo el principal | ✅ | Decisión #10 del plan v2, corregida 2026-07-31 |
| R5 | Solo Tesorería y Admin pueden fondear o ajustar una caja; el Supervisor ve los saldos y movimientos de las cajas de su PDV pero no fondea (C6) | ✅ | ADR-014 (reemplaza la decisión #11 del plan v2) · RoleSeeder (fondeo_caja) |
| R6 | No se puede pagar con la caja cerrada — hace falta una sesión abierta a nombre del operador | ✅ | E4-multi, decisión #3, 2026-08-04 |
| R7 | Cada pago descuenta la caja que abrió el propio operador, no "la caja del PDV" | ✅ | E4-multi, decisión #3, 2026-08-04 |
| R8 | El cierre es por monto total: registra el saldo final y no genera ningún movimiento — la plata se queda en la caja | ✅ | Decisión #14 del plan v2 · ADR-007 §5 |
| R9 | El saldo inicial de apertura se hereda del cierre anterior de esa caja — no se tipea, ni siquiera como sugerencia | ✅ | Reunión 2026-08-05 · ADR-007 §5 |
| R10 | La apertura y el cierre los hace un solo usuario, sin autorización de Supervisor | ✅ | Reunión 2026-08-05 · ADR-007 §4 |
| R11 | El prefondeo tiene tres capas: Holding, País y Caja | ✅ | Reunión 2026-08-05 · ADR-007 §1 |
| R12 | Al pagar se valida solo la caja; el prefondeo deja de bloquear | ✅ | Reunión 2026-08-05 · ADR-007 §2 |
| R13 | El prefondeo del país admite saldo negativo — es información contable, no un error | ✅ | Reunión 2026-08-05 · ADR-007 §2 |
| R14 | Fondear una caja por encima del prefondeo del país avisa, no bloquea | ✅ | Reunión 2026-08-05 · ADR-007 §3 |
| R15 | La moneda de pago es configurable por país; Guatemala paga en dólares | ✅ | Reunión 2026-08-05 · ADR-007 §6 |
| R16 | Los motivos de fondeo y ajuste salen de una lista cerrada, no de texto libre | ✅ | Reunión 2026-08-05 · plan E4b, C8 |
| R17 | Un usuario puede tener una sola caja abierta a la vez; un cambio de turno es cerrar y volver a abrir | ✅ | ADR-007 §5b, 2026-08-06 · índice cash_sessions_one_open_per_user |
| R18 | La caja opera solo el día en que se abrió. Una sesión abierta un día calendario anterior no paga, no se fondea y no se ajusta: solo se puede cerrar (y volver a abrir, heredando el saldo) | ✅ | Respuesta del cliente, 2026-10-01 · ADR-013 §1 |
| R19 | "Día" es la fecha calendario de America/Guatemala, no la de UTC. La regla vive en una sola función (CashSession::isFromPreviousDay()) | ✅ | ADR-013 §2 |
| R20 | Cada caja la cierra quien la abrió; la que abrió otra persona la cierran solo un Supervisor o un Admin del PDV de la caja. Se deriva de apertura_cierre_caja:write y fondeo_caja:read en una misma asignación, sin permiso nuevo. La pantalla dice quién tiene cada caja abierta | ✅ | Respuesta del cliente, 2026-10-02 (RV3-25, RV3-26, RV3-27) · decisiones D3-12 (B) y D3-13 (i) de Carlos, 2026-10-05 · ADR-021 (reemplaza en parte a ADR-013 §5) |
| R21 | Una caja se desactiva y se reactiva; nunca se borra. Conserva su número y todo su ledger, y el número no se reutiliza. No se desactiva con una sesión abierta ni con plata adentro, en cualquier moneda: primero se la deja en cero con un ajuste negativo de motivo «Retiro por baja de caja» (abrirla, retirar, cerrarla, desactivarla) | ✅ | Respuesta del cliente, 2026-10-02 (RV3-29, RV3-30) · decisión D3-14 (a) de Carlos, 2026-10-05 · ADR-022 §1, §3 y §4 |
| R22 | «Caja operable» es una sola definición —activa, de un PDV activo y de un país con módulo Caja—: solo esas cajas se ven en Saldos y se pueden abrir (422 CASH_BOX_INACTIVE). Lo que lee el ledger (Reportes → Cajas, Cierres por día, los extractos, «Distribuido en cajas») sigue viendo las de baja, marcadas Inactiva | ✅ | ADR-022 §2 |
| R23 | Saldos muestra una línea por país con la plata que hay en sus cajas, en su moneda de pago: coincide con «Distribuido en cajas» de Fondeo PDVs y, si el usuario no ve todos los PDV del país, dice «Total de tus PDV». Nunca suma países ni monedas | ✅ | Respuesta del cliente, 2026-10-02 (RV3-28) · valor por defecto de QC-15 (ver 06, pregunta #24) · ADR-022 §7 |
Sobre R18, el cliente lo pidió con estas palabras (Magaly Benavides, CIS-EC, mail del 2026-10-01): "Sí se requiere que haya una apertura y cierre diario de caja para control de saldos finales por día". Lo que quiere no es una formalidad sino el saldo final de cada día, y ese número solo existe si cada día tiene su propia sesión: con una caja abierta tres días seguidos el sistema sabe cuánto hay ahora, pero no cuánto había al cierre de ayer. Por eso la regla bloquea en vez de recomendar.
Sobre R10 y R9, que son las que más cambian la operatoria diaria, vale citar de dónde salieron:
- Diego Sánchez descartó la autorización del Supervisor al ver que cada movimiento queda auditado y es inmutable. Carlos lo cerró así en la reunión: "Sacamos los validadores para abrir caja y cerrar caja por parte de los supervisores".
- El saldo inicial heredado lo pidió Diego ("que le tome como saldo inicial el saldo del día anterior con el que haya cerrado esta caja") y Teresa lo justificó: "el que comience con el mismo saldo final del día anterior me parece que le da más seguridad al manejo del dinero". Ante la pregunta de Carlos de si convenía ofrecerlo como sugerencia editable, Diego fue tajante: "que lo tome automáticamente, no debería ser como sugerencia".
0.5 Actores
Actualizado 2026-10-02 (B6, ADR-014): hay cuatro perfiles y Tesorería ya es uno de ellos. El Backoffice se llama Cajero; el Supervisor deja de fondear y de editar el tipo de cambio (ve las cajas de su PDV); quien fondea, ajusta y carga los prefondeos es Tesorería (o el Admin). La versión anterior de esta sección decía lo contrario y quedó en el historial de git.
| Actor | Qué hace en este módulo | Permisos (seed real, RoleSeeder) |
|---|---|---|
| Cajero (el Backoffice de antes) | Abre su caja, paga transacciones contra ella, la cierra al terminar el turno. Es quien tiene el efectivo en la mano. Solo ve el saldo de la caja que él abrió, y no cierra la de un compañero. | caja L·E · apertura_cierre_caja L·E · tipo_cambio Ltipo_cambio (G8, 2026-10-07) · sin fondeo_caja |
| Supervisor | Hace lo del cajero y además ve los saldos y movimientos de todas las cajas de su PDV (totales por PDV incluidos), cierra la caja que dejó abierta un Cajero de su PDV y ve el extracto de sus PDVs en Fondeo PDVs. No fondea, no ajusta y | caja L·E · apertura_cierre_caja L·E · fondeo_caja L (sin E) · tipo_cambio Ltipo_cambio |
| Tesorería (Teresa, Diego — CIS-EC) | Fondea las cajas y corrige descuadres (ajuste), carga el prefondeo, edita el tipo de cambio, concilia el saldo del país contra el extracto bancario. Ve el saldo de las cajas pero no las abre ni las cierra, y no ve Pago ni Transacciones. | caja L · fondeo_caja L·E · tipo_cambio L·E · sin apertura_cierre_caja |
| Admin | Enciende el módulo en el país, define la moneda local, agrega cajas a una sucursal, y puede hacer todo lo anterior. | Todo, con Borrar |
La matriz completa, con todos los módulos y no solo los de Caja, vive en Matriz de Roles y Permisos §2.1.
0.6 Glosario del dominio
Son términos que se parecen entre sí y se confunden fácil. Vale leerlos antes de seguir — el resto del paquete los usa sin volver a definirlos.
| Término | Qué es |
|---|---|
| Prefondeo Holding (en el menú, «Prefondeo Soterex») | Pool en USD de la sociedad holding, que es a quien Soterex le transfiere la plata. Es el ledger que ya existe (prefunding_entries). Descuenta principal + comisión de cada pago. |
| Prefondeo País (en el menú, «Fondeo PDVs») | Pool en USD del país operativo. Descuenta solo el principal; nunca ve comisiones. Puede quedar negativo. Es lo que tesorería concilia contra el extracto bancario del país. |
| Caja operativa (o simplemente "caja") | El efectivo físico de una caja de un PDV. Su saldo es la suma de sus movimientos. Una sucursal puede tener varias. |
| Fondeo | Movimiento que suma efectivo a una caja: llegó plata nueva. Siempre positivo. Solo Tesorería/Admin. |
| Ajuste | Movimiento que corrige el saldo registrado para que coincida con la plata realmente contada. Puede ser positivo o negativo. Solo Tesorería/Admin. Carlos lo separó de fondeo en la reunión: "ojo, que esto es solo fondeo, todo aumenta; después están los ajustes, que esto puede ser positivo o negativo". |
| Apertura | Abrir la sesión de trabajo de una caja. Sin sesión abierta no se puede operar ni pagar. El saldo inicial se hereda del cierre anterior y no genera ningún asiento: la plata nunca salió de la caja. |
| Cierre | Cerrar la sesión. Registra el saldo final y no genera ningún asiento: la caja no queda en cero, el efectivo sigue ahí y la próxima apertura arranca con ese mismo saldo. Es lo único que se puede hacer con una sesión vencida. Lo hace quien la abrió o, si no está, un Supervisor o un Admin del PDV (cierre ajeno, que la auditoría marca). |
| Sesión vencida | Sesión que sigue abierta pero que se abrió un día calendario anterior al de hoy. No paga, no se fondea y no se ajusta; solo se cierra. En pantalla aparece como Caja vencida. Es un estado derivado, no una columna: lo calcula el backend (from_previous_day) cada vez que se consulta. |
| Día de caja | La fecha calendario de la sesión en la zona horaria de la app (America/Guatemala, UTC-6, sin horario de verano). Una caja abierta a las 20:00 de Guatemala se abrió "hoy" aunque en UTC ya sea mañana. |
| Saldo final del día | El closing_balance de la sesión que se abrió ese día (si la caja se abrió más de una vez ese día —cambio de turno—, el de la última). Coincide siempre con el saldo inicial de la sesión siguiente de esa caja, porque la apertura hereda el saldo. Es lo que muestra el reporte Cierres por día. |
| Arqueo | El conteo físico del efectivo del cajón. La app no lo hace: recibe su resultado en forma de ajuste (Faltante de arqueo / Sobrante de arqueo). |
| Blindado | El transporte de caudales que lleva efectivo hasta el PDV. En la app es un motivo de fondeo, no una entidad propia. |
| MTCN | Número de control de la transacción de Soterex. En Caja aparece en la línea de cada movimiento de tipo PAGO, para poder rastrear de qué transacción salió esa plata. |
| Principal | El monto de la transacción que se le entrega al beneficiario — transactions.amount. Es lo único que sale de la caja. |
| Comisión | Lo que Soterex le paga a CIS por la transacción — transactions.fee. La calcula y la devuelve Soterex, CIS no la configura (ADR-005). Es información restringida: nunca aparece en pantallas operativas, solo en Reportes y en el Dashboard de Tesorería y Admin (el Supervisor ya no la ve ahí desde B6). Nunca toca la caja ni el prefondeo del país. |
| Extracto (de tesorería) | El mismo dinero de un ledger leído como un estado de cuenta: una línea por movimiento, con débito o crédito y el saldo que quedó después. Hay cuatro —Soterex ↔ CIS Holding, CIS Holding, País y PDV— y son vistas derivadas: no guardan ni cambian ningún saldo. Ver el circuito en 1.10. |
| Disponible para distribuir | Lo que le queda al país para mandar a una caja: el saldo del país menos lo que ya está en sus cajas. Es el saldo corrido del extracto País y baja al fondear, a diferencia del saldo del país, que solo baja al pagar. |
| TC (tipo de cambio) | Unidades de moneda local por 1 USD. Historial inmutable por país: editar es insertar un registro nuevo, nunca sobreescribir. Solo aplica al pago. |
0.7 Cómo sigue
El documento que sigue, Modelo de saldos, es el más importante del paquete: explica cómo se mueve la plata entre las capas, con el ejemplo numérico que el cliente validó en la reunión. Si vas a tocar el módulo o a operarlo, empezá por ahí.
Análisis Funcional: Módulo Caja — parte 1 de 7. Índice · Siguiente: Modelo de saldos →

