Flujos de Caja
Análisis Funcional: Módulo Caja — parte 3 de 7. ← Anterior · Índice · Siguiente: Diagramas de Actividad →
Un flujo por operación, describiendo el sistema tal como corre hoy en main — E4b (ADR-007) mergeó el 2026-08-06, más de un mes después de la reunión con el cliente del 2026-08-05 que lo definió. Donde algo cambió respecto de lo que E4/E4-multi habían implementado originalmente, queda una nota de Historia — no para llevar la cuenta de versiones, sino porque el porqué de una decisión a veces solo se entiende sabiendo qué reemplazó.
Quién puede hacer qué
Permisos reales del seed (backend/database/seeders/RoleSeeder.php:36-114). Todos se evalúan por país: el gate grueso está en la ruta (backend/routes/api.php:100-197, un grupo Route::middleware('perm:<módulo>,<acción>') por fila de esta tabla) y el fino en CashBoxController::authorizeStationScope() (backend/app/Http/Controllers/CashBoxController.php:621), que compara contra el país de la sucursal dueña de la caja y, desde el 2026-08-06, contra los PDVs a los que el usuario tiene alcance (ver 06, pregunta #5).
Actualizada el 2026-10-02 (B6, ADR-014): cuatro perfiles. El Backoffice es el Cajero; el Supervisor ya no fondea ni edita el tipo de cambio ni carga prefondeos (solo ve las cajas de su PDV); Tesorería los hace. Pagar es
pago:writey cancelartransacciones:delete.
Actualizada el 2026-10-07 (G8, D3-11): el tipo de cambio es solo de Tesorería y Admin. El Cajero y el Supervisor, que desde B6 lo leían, ya no (403 por API y sin el ítem en el menú): la fila «Cargar tipo de cambio» de la tabla y 2.8 lo reflejan. El pago no lo necesita: lo lee por su cuenta.
| Acción | Permiso | Cajero | Supervisor | Tesorería | Admin |
|---|---|---|---|---|---|
| Ver cajas, saldo y movimientos | caja:read | ✅ solo la suya | ✅ todas las de su PDV | ✅ | ✅ |
| Abrir y cerrar caja | apertura_cierre_caja:write | ✅ la que abrió él | ✅ la que abrió él | ❌ | ✅ |
| Cerrar la caja que abrió otra persona | apertura_cierre_caja:write y fondeo_caja:read en una misma asignación que cubra el PDV de la caja (G6, ADR-021) | ❌ | ✅ solo en su PDV | ❌ | ✅ |
| Ver los totales por PDV y los saldos ajenos | fondeo_caja:read | ❌ | ✅ | ✅ | ✅ |
| Fondear y ajustar caja (y la bóveda del PDV, L3) | fondeo_caja:write | ❌ | ❌ | ✅ | ✅ |
| Pasar plata entre cajas y con la bóveda (L3, ADR-029) | traspaso_caja:write | ❌ | ✅ solo en sus PDV | ✅ | ✅ |
| Ver y cargar el tipo de cambio | tipo_cambio:read · tipo_cambio:write | ❌ | ❌ | ✅ | ✅ |
| Cargar asientos de Prefondeo Soterex (Holding) | prefondeo:write | ❌ | ❌ | ✅ | ✅ |
| Cargar asientos de Fondeo PDVs (Prefondeo País) | prefondeo_pais:write | ❌ | ❌ | ✅ | ✅ |
| Ver los extractos de la Holding y del país | prefondeo:read · prefondeo_pais:read | ❌ | ❌ | ✅ | ✅ |
| Ver el extracto de un PDV (Fondeo PDVs › PDV) | fondeo_caja:read | ❌ | ✅ solo sus PDVs | ✅ | ✅ |
| Agregar, desactivar y reactivar cajas de un PDV | abm_estaciones:write | ❌ | ❌ | ❌ | ✅ |
| Pagar una transacción | pago:write | ✅ | ✅ | ❌ | ✅ |
| Cancelar una transacción | transacciones:delete | ❌ | ❌ | ❌ | ✅ |
| Reporte de Cajas (resumen, detalle y Cierres por día) | reportes:read | ❌ | ✅ | ✅ | ✅ |
2.1 Apertura de caja
POST /caja/{cashBox}/apertura (CashBoxController.php:124). Requiere apertura_cierre_caja:write en el país de la sucursal. Un solo usuario, sin reautenticación de ningún tipo: la abre el operador con su propia sesión.
Reglas y validaciones:
- Un solo usuario, sin autorización de Supervisor. No existe el código
SUPERVISOR_INVALIDni el camposupervisor_id_token: la columnaopened_by_supervisor_idsigue en la tabla (las sesiones históricas la tienen) pero quedónullabley ya no se escribe (backend/database/migrations/2026_08_06_100000_e4b1_caja_sin_supervisor_y_motivos_cerrados.php:24). - El saldo inicial se hereda, no se tipea.
CashBoxService::inheritedOpeningBalance()(backend/app/Services/CashBoxService.php:79) es literalmentebalance()— el saldo que el ledger de esta caja ya tiene — y se muestra en el modal como dato de solo lectura, no editable ni siquiera como sugerencia. Si la plata física no coincide, se corrige con un AJUSTE (2.4); si entra plata nueva, con un FONDEO (2.3) — nunca editando el saldo de apertura. - Sin movimiento de apertura. No se crea ningún
DEPOSITO_APERTURA(CashBoxController.php:176-180): la plata nunca salió de la caja porque el cierre ya no la retira (ver 2.2), así que crear un depósito acá la duplicaría. - Una sola sesión abierta por caja Y por usuario. Dos índices únicos parciales en la base:
cash_sessions_one_open_per_box(backend/database/migrations/2026_07_31_152554_create_cash_sessions_table.php:38, cubre dos aperturas de la misma caja) ycash_sessions_one_open_per_user(backend/database/migrations/2026_08_06_130000_e4b_una_sola_caja_abierta_por_usuario.php:30, cubre dos aperturas del mismo usuario sobre cajas distintas — un caso que ningúnlockForUpdatede este método alcanza a serializar, porque son filas diferentes). El controller chequea las dos cosas explícitamente antes de insertar (CashBoxController.php:132-164) y elcatchdeQueryExceptionreconoce ambos índices por nombre como defensa en profundidad (:196-218). Ver 3.4. - Todo ocurre dentro de una transacción de base de datos: si algo falla, no queda ni sesión ni cambio de estado.
- Una caja que no es operable no se abre (G7.3, ADR-022 §2). «Operable» es una sola definición,
CashBox::scopeOperable(): la caja está activa, es de un PDV activo y ese PDV es de un país con módulo Caja. Saldos solo ofrece esas cajas, y si el pedido llega igual la apertura responde 422CASH_BOX_INACTIVEcon el texto de cuál de las tres razones no se cumple («está desactivada», «su PDV está inactivo», «su país no opera con módulo Caja»), para que quien la intenta sepa a quién pedírselo. La caja se lee de nuevo con el bloqueo tomado, no la que resolvió la ruta, porque es el mismo lock que toma el PATCH que la desactiva: si gana la apertura, desactivar ve la sesión abierta y responde 409; si gana desactivar, la apertura leeactive = falsey responde 422 (2.7). - El 409 dice quién la tiene (G6.A1, RV3-26). El rechazo ocurre antes de escribir nada, así que la sesión del primero queda intacta, y el mensaje nombra a la persona: "La Caja 1 de Mixco Plaza la tiene abierta" seguido de su correo, o "Ya tenés abierta la Caja 1 de Mixco Plaza" si la tiene el propio usuario. Trae también
opened_by({id, email}). El correo lo ve cualquiera que vea la lista de cajas de ese PDV (QC-14, valor por defecto hasta que el cliente lo confirme): el cajero necesita saber a quién pedirle que libere la caja. - Abrir de nuevo es la salida de una caja vencida (B3, ver 2.10). Mientras la sesión de ayer siga
OPEN, la caja no se puede abrir otra vez (CASH_ALREADY_OPEN, y la pantalla ni ofrece el botón): primero se la cierra. La apertura que sigue hereda el saldo como siempre, así que cerrar y abrir no mueve plata. La fecha de apertura de la sesión nueva es la que define "su día".
Historia. Hasta el 2026-08-05 esto pedía un monto tipeado por el operador y la confirmación in-band de un Supervisor —el control vivía en esa firma— con el código
SUPERVISOR_INVALIDsi el segundo usuario no era Supervisor o no tenía el permiso (ADR-005). La revisión con el cliente lo simplificó: el ledger inmutable ya daba la trazabilidad que se buscaba con la firma, y exigir a un Supervisor físicamente en el PDV sumaba fricción diaria sin agregar nada. Diego (tesorería), sobre el saldo: "que lo tome automáticamente, no debería ser como sugerencia". Ver ADR-007 §4 y §5.
2.2 Cierre de caja
POST /caja/{cashBox}/cierre (CashBoxController.php:221), mismo permiso que la apertura. Sin confirmación de Supervisor: el cierre siempre fue de un solo usuario. Desde G6 (ADR-021) la cierra quien la abrió, o un Supervisor o un Admin del PDV: para cualquier otra persona, aunque tenga el permiso de cerrar su caja, responde 403.
Reglas y validaciones:
- Cierre por monto total, no por conteo. El sistema no pide arquear ni tipear nada: toma el saldo que él mismo lleva (
CashBoxService::balance(),backend/app/Services/CashBoxService.php:31, que sumaamount_localde todos los movimientos de la caja en su moneda de pago vigente, no solo los de la sesión). - El cierre ya no genera ningún movimiento. No existe más el
RETIRO_CIERRE: antes barría la caja a cero porque la plata se retiraba de verdad al cerrar; ahora que el saldo se hereda, ese ida y vuelta contable no representaba ningún movimiento real y dejaba la caja mostrando cero entre el cierre y la apertura siguiente, con la plata físicamente en el PDV (CashBoxController.php:240-249). - La caja no queda en cero. Sigue mostrando exactamente el mismo saldo que tenía, que es lo que la apertura siguiente hereda. La invariante vieja —"la suma de los movimientos de una sesión cerrada es cero"— ya no existe: cualquier tabla o texto que la dé por válida está desactualizado.
- El
closing_balancequeda guardado en la sesión: es lo que se audita y lo que hereda la apertura siguiente (CashBoxController.php:253). - El cierre exige la documentación completa de los pagos de esa sesión (A6.3, confirmado por el cliente): si algún pago pagado desde esa sesión tiene la papeleta firmada, o uno de los documentos de transferencia (desde G3, solo en las
PAIDviejas que se pagaron así), sin subir, responde422 PENDING_PAYMENT_DOCUMENTScon el MTCN y lo que falta de cada uno, sin montos ni datos personales. Solo se mira la sesión que se cierra, no las anteriores. La apertura y el pago siguiente no se bloquean por esto. - El cierre no mira el día. Es justamente lo único que se puede hacer con una sesión vencida (2.10), así que funciona igual cuando la sesión es de hace una hora o de hace un mes. El
closing_balancede una sesión vencida es el saldo del cierre contable de su día: desde la medianoche nada pudo escribir en esa caja. - Quién puede cerrar (G6.B1, D3-12 B y D3-13 i).
PermissionService::canCloseCashSession()deja pasar a (1) quien abrió la sesión, o (2) quien reúnaapertura_cierre_caja:writeyfondeo_caja:readdentro de una misma asignación que cubra el PDV de la caja: el Supervisor de ese PDV y el Admin. No pasa otro Cajero del mismo PDV, ni Tesorería, ni un Supervisor de otro PDV, ni quien sea Cajero de este PDV y Supervisor de otro (cada capacidad tiene que venir de la misma asignación). No hay una celda nueva en la matriz: se deriva de permisos que ya existen. Es la regla que reemplaza a la de ADR-013 §5, donde cerraba cualquiera con el permiso y que servía para que un compañero destrabara la caja de quien no vino. - El orden de los controles: alcance por PDV (403
PERMISSION_DENIED), sin sesión abierta (409CASH_NOT_OPEN), dueño o supervisor (403CASH_CLOSE_NOT_OWNER), documentos pendientes (422PENDING_PAYMENT_DOCUMENTS). El 403 va antes de los documentos a propósito: quien no es dueño ni supervisa no tiene por qué enterarse de qué pagos de otro tienen documentos sin subir. Para quien sí puede cerrar, el bloqueo por documentos rige igual, y el Supervisor puede subir los soportes que faltan (ADR-011 §4). - A quien le cierran la caja,
pay()le respondeNO_CASH_BOX_OPEN_FOR_USERhasta que vuelve a abrirla. Es una consecuencia explícita y auditada de que un Supervisor o un Admin la cerró; la reapertura hereda el saldo, así que no se pierde nada. La auditoría deCASH_SESSION_CLOSEDsuma el booleanocierre_ajeno, sin montos.
Historia. Hasta el 2026-08-05 el cierre creaba un
RETIRO_CIERREpor el saldo total en negativo y dejaba la caja en cero exacto; la apertura siguiente volvía a pedir un monto tipeado sin ninguna relación con ese cierre. La revisión con el cliente decidió arrastrar el saldo en vez de barrerlo: "que comience con el mismo saldo final del día anterior le da más seguridad al manejo del dinero" (Teresa). La alternativa evaluada —conservar elRETIRO_CIERREy recrear unDEPOSITO_APERTURApor el mismo monto al abrir— se descartó por costo, no por concepto: terminó implementándose sin ningún movimiento de por medio, más simple que las dos opciones consideradas en su momento (ADR-007, Alternatives).
2.3 Fondeo de caja
Dos vías, un solo fondeo (J3, 2026-10-13). Además de la solapa Fondeo de Saldos, la pestaña PDV de Fondeo PDVs (
PrefondeoPaisView.vue) tiene un formulario Fondear caja para Tesorería y Admin: elige una caja con sesión abierta hoy del PDV mirado, monto y motivo, y llama al mismoPOST /caja/{cashBox}/fondeo. No agrega ningún camino de plata: el backend aplica el mismo alcance (authorizeStationScope),CASH_SESSION_CLOSED, la regla de ADR-013 y el avisoOVER_COUNTRY_PREFUNDING. Plata en tránsito que el PDV confirma al abrir no existe (es G13.B).
POST /caja/{cashBox}/fondeo (CashBoxController.php:273). Permiso fondeo_caja:write: en el seed lo tienen solo Tesorería y Admin (hasta B6 era Supervisor y Admin); el Cajero lo tiene en false en los tres flags, y el Supervisor solo en lectura, así que ninguno de los dos ve el bloque de movimiento manual (frontend/src/views/CajaView.vue:439).
Reglas y validaciones:
- El fondeo solo suma (
min:0.01). Sacar plata del cajón no es un fondeo negativo: es un ajuste (2.4). - Exige sesión abierta, y abierta hoy. Una caja cerrada no acepta movimientos de ningún tipo, y una abierta de un día anterior tampoco (
CASH_SESSION_FROM_PREVIOUS_DAY, ver 2.10): sin esto el saldo final de un día seguiría moviéndose después de terminado. - El motivo sale de un catálogo cerrado, no de texto libre:
Fondeo inicial,Blindado,Transferencia financiero,Otro(CashMovement::MOTIVOS_FONDEO,backend/app/Models/CashMovement.php:32-37). ElegirOtroexigemotivo_detalle(CashBoxController::validateMontoYMotivo(),:472-495); un motivo fuera del catálogo se rechaza con 422.GET /caja/motivos?type=FONDEO(CashBoxController::motivos(),:508-513) expone ese catálogo fijo al frontend — ya no hace unSELECT DISTINCTsobre lo cargado antes. - Fondear no descuenta ningún otro saldo. Mover plata del país al cajón es distribución, no gasto: ni el Prefondeo País ni el Holding se tocan (
CountryPrefundingService::distributedInCashBoxes(),backend/app/Services/CountryPrefundingService.php:50-71, es justamente la suma que hace que ese número no baje). - Aviso posterior, no bloqueante. Si el fondeo deja el disponible para distribuir del país (saldo del país menos lo ya repartido en sus cajas) en negativo, el backend igual responde 201 y agrega un
warningcon códigoOVER_COUNTRY_PREFUNDING(CashBoxController::overDistributionWarning(),:406-425). No es una confirmación previa: el movimiento ya se creó cuando se calcula el aviso. Diego (tesorería) lo pidió textual: "como una alerta más que un validador".
2.4 Ajuste de caja
POST /caja/{cashBox}/ajuste (CashBoxController.php:336). Comparte el permiso del fondeo (fondeo_caja:write) a propósito: un ajuste puede restar plata, que es más sensible que fondear, así que quedó con el mismo nivel de restricción, no con uno más permisivo.
Reglas y validaciones:
- El ajuste suma o resta (
not_in:0), a diferencia del fondeo. - Nunca puede dejar la caja en negativo (
CashBoxController.php:360-366): el error devuelve el saldo actual para que el operador vea contra qué está ajustando. - Exige sesión abierta y abierta hoy (
CASH_SESSION_FROM_PREVIOUS_DAYsi es de un día anterior): el chequeo corre antes de mirar el saldo, igual que en el fondeo. - El motivo también sale de un catálogo cerrado:
Faltante de arqueo,Sobrante de arqueo,Retiro por baja de caja(G7, ver abajo) yOtro(CashMovement::MOTIVOS_AJUSTE,backend/app/Models/CashMovement.php).Blindadoqueda deliberadamente fuera —un blindado siempre suma, es fondeo, no ajuste— yOtroexigemotivo_detalleigual que en fondeo. Si tesorería termina queriendoBlindadotambién acá, es agregar una constante (ver 06, pregunta #2). Retiro por baja de cajasaca plata y solo puede ser negativo (G7, decisión D3-14 a de Carlos, ADR-022 §4). Es el camino para dejar una caja en cero antes de desactivarla: con ese motivo un monto positivo da 422 (los demás motivos de ajuste no tienen signo, unFaltante de arqueopositivo es un error de carga que hoy pasa). Es motivo de ajuste únicamente: el fondeo lo rechaza como a cualquier motivo fuera de su catálogo. No hubo migración de datos, porque el catálogo es una constante del dominio y no una tabla. Lo aprobó Carlos; la aprobación de Tesorería, a quien le corresponde el catálogo, sigue abierta (06, pregunta #23).- Nunca se edita ni se borra un movimiento previo. Corregir es agregar un movimiento nuevo: el ledger es inmutable por diseño (ADR-005).
Historia. Hasta el 2026-08-05 el motivo de fondeo y ajuste era texto libre con autocompletado (
NSelecten modofilterable+tag, alimentado por unSELECT DISTINCT motivosobre lo ya cargado). El cliente lo cerró en la reunión porque la misma operación entraba como "blindado" o "transferencia de dinero" según quién la tipeara, y después no se podía agrupar nada. Los motivos libres ya cargados se migraron: los que coincidían con una entrada del catálogo se normalizaron, el resto pasó aOtroconservando el texto original enmotivo_detalle(backend/database/migrations/2026_08_06_100000_e4b1_caja_sin_supervisor_y_motivos_cerrados.php).
2.5 Varias cajas en una sucursal: cuál se opera y de cuál sale la plata
Una sucursal puede tener varias cajas físicas numeradas 1, 2, 3… (cash_boxes.number, único junto con station_id). Son dos decisiones distintas y desacopladas: qué caja se mira en pantalla, y qué caja paga.
- La elección no se persiste entre sesiones: cada vez que se entra a Caja con más de una disponible, se vuelve a elegir. Con una sola caja no se agrega fricción — se entra directo.
- El botón "Cambiar de caja" solo aparece si hay más de una (
frontend/src/views/CajaView.vue:395). - El listado respeta el alcance del usuario por país y por PDV, con el mismo
PermissionServiceque el resto de la app (CashBoxController::disponibles(),:49-88).
De qué caja sale la plata al pagar — con varias cajas por sucursal ya no se puede derivar del PDV, así que se deriva de quién está pagando:
- Una caja abierta por persona a la vez ya no es un supuesto: es una regla forzada. Desde el 2026-08-06,
USER_ALREADY_HAS_OPEN_CASH_BOX(2.1) y el índice únicocash_sessions_one_open_per_usergarantizan que nadie tenga dos sesionesOPENa su nombre — ver 06, pregunta #4. Cambio de turno sigue siendo cerrar y volver a abrir. - Que otro operador tenga abierta otra caja de la misma sucursal es irrelevante: cada pago descuenta la caja de quien paga, nunca la del otro.
- La caja tiene que ser del mismo país que la transacción (
CASH_BOX_COUNTRY_MISMATCH,TransactionController::applyCashBoxDiscount(),:342-355) — sin esto, un usuario con alcance en dos países con módulo Caja podía pagar una transacción de un país descontando la caja del otro, al TC del otro. Pero dentro de un mismo país, el cruce PDV↔caja sigue sin validarse: el PDV que se atribuye a la transacción se resuelve por separado (TransactionController::resolveStationForResolution()) y no se compara contra la sucursal de la caja que paga. Fue una omisión deliberada del diseño de E4-multi — ver Hallazgos. - Desde G4.1 (2026-10-06, ADR-020) la caja también dice en qué PDV se pagó, cuando no hay otro que lo diga.
applyCashBoxDiscountdevuelve el PDV de la caja ypay()lo usa como PDV de la transacción solo si la persona no tiene PDV activo ni un único PDV en su alcance (2+ PDV sin activo, o alcance sin acotar como el del Admin), y la transacción no lo trae ya fijado por un primer documento. El PDV activo gana sobre el de la caja: el cruce sigue siendo posible y sigue sin validarse (pregunta #6, pendiente de QC-9). Un PDV vacío en un pago con Caja ya no puede pasar: o lo resolvió el PDV de la persona, o lo da la caja.
2.6 Pago de una transacción
PATCH /transacciones/{transaction}/pay (TransactionController.php:182), permiso transacciones:write. Con modulo_caja apagado en el país, el bloque de caja no corre y el flujo es el de M1 más la validación de Prefondeo País.
Qué descuenta cada capa:
| Capa | Qué descuenta | Moneda | Puede quedar negativa | Bloquea el pago |
|---|---|---|---|---|
| Prefondeo Holding | principal + comisión | USD (global, todos los países) | Sí — nada lo valida ni lo avisa hoy (ADR-007 §1, nota ⑴; el aviso hacia esta capa lo propone ADR-010, Status: Proposed, sin implementar) | No |
| Prefondeo País | solo el principal | USD | Sí | Solo en países sin módulo Caja (Ecuador, con EPOS) |
| Caja de la sucursal | solo el principal | USD o moneda local, según pago_en_moneda_local del país | No | Sí — con módulo Caja activo, es la única validación |
- El pago de caja es siempre efectivo (G3, 2026-10-05). El medio de pago se valida antes de abrir la transacción de base de datos: cualquier otro que no sea
EFECTIVOresponde422sin tocar la caja ni el prefondeo. Hasta G3 la pantalla ofrecía la transferencia y el descuento de caja corría igual, porqueapplyCashBoxDiscount()no leía el medio (RV3-13): la caja reportaba menos efectivo del que tenía. Ver ADR-011, actualización G3. - Con módulo Caja activo,
INSUFFICIENT_PREFUNDINGya no puede ocurrir. La única validación de saldo es la caja del operador — el saldo del país puede estar en cero por una transferencia en trámite mientras el PDV tiene plata, y perder la transacción por eso sería un problema administrativo, no de fondos (TransactionController.php:218-231). En países sin módulo Caja —Ecuador, que opera con su EPOS— se mantiene la validación, ahora contra el Prefondeo País (:226-244): decisión consciente y confirmada por Carlos, no una omisión. (06, pregunta #8). - La caja tiene que ser del mismo país que la transacción,
CASH_BOX_COUNTRY_MISMATCH(TransactionController.php:342-355) — ver 2.5. - La sesión tiene que ser de hoy.
CASH_SESSION_FROM_PREVIOUS_DAYcorta el pago antes de mirar el país, el tipo de cambio o el saldo, y sin escribir nada. Solo rige en países con módulo Caja: sin él,pay()no mira ninguna sesión. Ver 2.10. - Si el país paga en dólares (
pago_en_moneda_local = false, default), no se exige TC vigente:NO_EXCHANGE_RATEno puede dispararse y el monto descontado es el nominal, sin conversión (:357-371). Guatemala está en este caso hoy. - La comisión nunca toca la caja. Es una decisión de negocio, no un detalle: el cajón físico paga lo que recibe el beneficiario, nada más (
TransactionController.php:310-313). - El TC se congela en el movimiento solo si hubo conversión (
exchange_ratequedanullsi el país paga en dólares): una reimpresión posterior usa ese valor, no el vigente al momento de reimprimir (:393-395). - Atomicidad real: el descuento de caja ocurre dentro del mismo
DB::transactionque el cambio de estado. Si la caja no alcanza, no queda ni movimiento ni transacción pagada. Ver 3.1. - La comisión nunca se devuelve en las respuestas operativas, y el error de prefondeo omite a propósito el monto requerido: junto al monto ya visible, restando se obtendría la comisión.
2.7 Alta y baja de cajas en una sucursal
Vive en el ABM de Estaciones, con permiso abm_estaciones:write, o sea solo Admin (backend/routes/api.php; StationController::agregarCaja() y StationController::actualizarCaja()). Desde el 2026-10-06 (entrega G7, ADR-022) una caja se agrega, se desactiva y se reactiva; nunca se borra.
El alta
- Las cajas no se nombran a mano: son "Caja 1", "Caja 2"… dentro de su sucursal. La numeración es secuencial y no reutiliza números, tampoco los de una caja de baja: toma el
max(number) + 1de todas las cajas de la sucursal (CashBoxService::addCashBoxForStation(),backend/app/Services/CashBoxService.php). Si la última era la Caja 3 y se desactiva, la próxima es la Caja 4. - Activar el módulo en el país es un solo paso para el Admin: la sincronización de cajas ocurre sola (
CountryController::update(), víaCashBoxService::ensureCashBoxesForCountry()). - El alta valida (H3-06, G7.4): un país sin módulo Caja da 422
CASH_MODULE_DISABLEDy una sucursal inactiva da 422STATION_INACTIVE. Antes agregaba una caja que ninguna pantalla podía mostrar. - Mover una sucursal a un país con módulo Caja le crea la Caja 1, y solo cuando cambia de país: un Admin que dio de baja la Caja 1 a propósito no la ve volver al renombrar la sucursal.
La baja y la reactivación
PATCH /admin/estaciones/{station}/cajas/{cashBox} con { "active": bool }, mismo permiso que el alta. El panel Administrar de la celda Cajas lo usa (4.6).
- Reactivar es el mismo PATCH con
active: true: sin los controles de la baja y con suCASH_BOX_ACTIVATED. La caja vuelve con su número, su ledger y su saldo (que era cero cuando se la desactivó). - No se desactiva con plata en ninguna moneda.
CashBoxService::balance()mira solo la moneda de pago vigente del país, y el efectivo que quedó en una anterior (el país cambió de moneda) solo sale porresidualBalances(): una caja con quetzales adentro y dólares en cero tiene el cajón lleno ybalance()en cero.CashBoxService::hasBalance()mira las dos fuentes. - El rechazo no dice cuánto hay. Quien administra estaciones (
abm_estaciones) no es por eso quien ve los saldos de las cajas. - El camino con plata son cuatro pasos y los hacen perfiles distintos: un Cajero, un Supervisor o un Admin abre la caja (Tesorería no tiene
apertura_cierre_caja), Tesorería o un Admin ajusta (fondeo_caja:write) con el motivoRetiro por baja de caja(monto negativo, ver 2.4), alguien con permiso de cierre la cierra (2.2) y un Admin la desactiva. Es incómodo a propósito: sacar plata de una caja deja la traza de siempre. - Desactivar y abrir se serializan. Si la apertura gana, el PATCH ve la sesión abierta y responde 409; si gana el PATCH, la apertura lee
active = falsey responde 422 (2.1). - Desactivar una sucursal con una caja abierta da 409
STATION_HAS_OPEN_CASH_BOX, y con plata en sus cajas 409STATION_HAS_CASH_BALANCE, solo en el guardado que la desactiva (el formulario reenvíaactiveen cada guardado) y solo si la sucursal está activa y es de un país con módulo Caja (si ya estaba inactiva, o su país no tiene módulo, sus cajas ya no son operables: frenar ahí dejaría al Admin sin salida). Lo mismo vale para cambiar la sucursal de país. Es la regla de la baja de una caja aplicada a toda vía por la que una caja deja de ser operable: sin ella, la plata o la sesión de esa caja desaparecían de Saldos sin que nadie pudiera retirarla ni cerrarla desde la pantalla. Desactivar una sucursal no desactiva sus cajas: las dos banderas son independientes, la caja sigue activa pero deja de ser operable mientras la sucursal esté inactiva, y vuelve sola al reactivarla. - Apagar el módulo Caja de un país tiene la misma regla: 409
COUNTRY_HAS_OPEN_CASH_BOXoCOUNTRY_HAS_CASH_BALANCEsi alguna caja de una sucursal activa del país tiene una sesión abierta o plata adentro. - Auditoría:
CASH_BOX_ADDED,CASH_BOX_DEACTIVATEDyCASH_BOX_ACTIVATED, con{station_id, number}y sin montos.
2.8 Tipo de cambio: carga, vigencia y el caso de pago en dólares
GET/POST /tipo-cambio/{country} (backend/app/Http/Controllers/ExchangeRateController.php), permiso tipo_cambio: lo leen y lo escriben solo Tesorería y Admin. El Cajero y el Supervisor solo leen (hasta B6 escribía el Supervisor; desde G8, 2026-10-07, ni el Cajero ni el Supervisor lo ven: 403, y la pantalla no está en su menú).
- El historial es inmutable: cada edición es un alta. El registro viejo sigue existiendo con su tasa original, que es lo que hace auditable una reimpresión.
- Vigente = el más reciente con
effective_from <= now()(backend/app/Services/ExchangeRateService.php:15). - La tasa se expresa como unidades de moneda local por 1 USD, con 6 decimales.
- El selector de países de esta pantalla lista solo los países con módulo Caja activo, y se sirve por un endpoint propio para no obligar a tener permisos de ABM de Países (
ExchangeRateController::paises(),:34-41). - No se puede programar un tipo de cambio futuro desde la UI:
store()fija siempreeffective_from = now()(:67), aunque el modelo yExchangeRateService::current()soportan vigencias futuras — ver Hallazgos. - Guatemala no tiene autorización para cambio de divisa, así que paga en dólares:
countries.pago_en_moneda_local(defaultfalse) lo determina por país (backend/database/migrations/2026_08_06_110000_e4b2_moneda_de_pago_por_pais.php). Con la bandera apagada,NO_EXCHANGE_RATEno puede dispararse — la pantalla de Tipo de Cambio sigue existiendo tal cual, lista para cuando Guatemala obtenga la autorización o aparezca el esquema de casa de cambio tercerizada que mencionó el cliente como segunda instancia. En pantalla, la columna "TC aplicado" se oculta cuando ningún movimiento del rango tiene tasa cargada (CashBoxController::reporte(),:554-567).
2.9 Prefondeo: Holding, País y sus saldos
Desde el 2026-08-06 el prefondeo son dos pantallas y dos capas, no una — apareció la Holding por el contrato nuevo con Soterex. Ver el detalle contable completo en 01, Modelo de saldos y el ejemplo numérico en 3.2.
Prefondeo Holding — GET/POST /prefondeo (PrefundingController), permiso prefondeo: es la tabla prefunding_entries que ya existía en E4, renombrada en concepto y en UI, no en base de datos. Descuenta principal + comisión y el saldo que se muestra es la suma global de todos los países (PrefundingService::globalBalance(), backend/app/Services/PrefundingService.php:40-49) — el ledger conserva country_id en cada asiento y cada pago para el desglose por país que se le informa a Soterex, pero el número que ve la pantalla es el total. (2026-10-07, G12: el total es el de quien lee todos los países; quien lee menos ve el saldo de sus países y un aviso. Ver la Actualización de ADR-007 §1.)
Prefondeo País — GET/POST /prefondeo-pais (backend/app/Http/Controllers/CountryPrefundingController.php), permiso prefondeo_pais: Tesorería y Admin escriben; el Cajero y el Supervisor no acceden (hasta B6 escribía el Supervisor). Tabla nueva country_prefunding_entries, con carga manual por tesorería.
- Descuenta solo principales, nunca la comisión — se liquida a fin de mes entre Holding y Soterex, el país no la ve (
CountryPrefundingService::balance(),backend/app/Services/CountryPrefundingService.php:28-38). - Admite saldo negativo. Si la caja paga y el país estaba en cero, queda en rojo reflejando la deuda real con la Holding — es información contable válida, no un error.
- El saldo no alcanza por sí solo. Mover plata del país a una caja no descuenta este saldo (es distribución, no gasto), así que la pantalla muestra tres números:
CountryPrefundingService::breakdown()(:84-94) — saldo del país, distribuido en cajas (suma de los saldos de todas sus cajas, filtrando por la moneda de pago vigente,distributedInCashBoxes(),:50-71) y disponible para distribuir (la resta de los dos anteriores, que también puede ser negativo si las cajas ya tienen más plata de la que el país tiene contablemente). Ver la implementación de pantalla en 4.4. - Fondear una caja no toca ni el Prefondeo País ni la Holding. Es distribución banco→cajón, no gasto.
- No hay vínculo formal entre un asiento de la Holding y el de País que lo originó —
country_prefunding_entriesno referencia aprefunding_entries. Son dos cargas manuales independientes. Ver 06, pregunta #11.
2.10 Caja vencida: la caja opera solo el día en que se abrió
Entrega B3 del plan de ajustes v2, ADR-013. El cliente pidió "apertura y cierre diario de caja para control de saldos finales por día": hasta entonces nada obligaba a cerrar, y pay() podía descontar de una caja abierta hacía un mes.
Una sesión OPEN cuyo día de apertura —en hora de America/Guatemala— es anterior al de hoy es una sesión vencida. Lo único que se puede hacer con ella es cerrarla:
| Operación sobre una caja con sesión vencida | Resultado |
|---|---|
Pagar (pay(), solo países con módulo Caja) | 422 CASH_SESSION_FROM_PREVIOUS_DAY, antes de descontar nada |
| Fondear | 422 CASH_SESSION_FROM_PREVIOUS_DAY |
| Ajustar | 422 CASH_SESSION_FROM_PREVIOUS_DAY |
| Cerrar | Solo quien la abrió, un Supervisor o un Admin del PDV; el resto recibe 403 CASH_CLOSE_NOT_OWNER. Después, igual que siempre, incluido el bloqueo por PENDING_PAYMENT_DOCUMENTS |
| Abrir de nuevo, ya cerrada | Funciona igual: hereda el saldo |
| Subir documentos pendientes | Sigue permitido |
| Leer (listado, movimientos, reportes) | Sin cambios |
El 422 trae el código, un mensaje con la fecha ("Esta caja quedó abierta desde el 01/10/2026. Cerrala y abrila de nuevo para operar hoy."), opened_on (Y-m-d), cash_box_id y country_id (el de la caja: este corte va antes que el de país de la transacción, así que no es necesariamente el de la transacción rechazada).
Cinco reglas que conviene tener presentes:
- "Día" es la fecha de Guatemala, no la de UTC. A las 18:00 locales ya es mañana en UTC: una regla calculada en UTC cerraría la caja en plena tarde.
opened_ates untimestampsin zona que se guarda como hora de pared local, y la regla compara contra esa hora. Vive en una sola función,CashSession::isFromPreviousDay(), y es la que consultanpay(), fondeo, ajuste,GET /caja/disponiblesyGET /caja/totales-pdv. - Bloquea, no cierra solo. No hay cron: el scheduler está apagado en staging, y un cierre automático no puede esperar la papeleta firmada que exige el cierre ni tiene quién lo firme. Alguien tiene que cerrar la caja.
- Fondeo y ajuste se bloquean igual que el pago, porque escriben en el ledger: si pudieran moverlo después de terminado el día, el
closing_balanceno sería el del cierre contable de ayer sino el del momento en que alguien se acuerde de cerrar. - Una caja abierta hoy que cruza la medianoche queda vencida. Si el cajero abrió a las 18:00 y sigue pagando a las 00:02, su siguiente pago da 422. Es el costo de la regla: hay que cerrar y abrir de nuevo, y como el saldo se hereda, la plata no se mueve.
- La cierra quien la abrió, o un Supervisor o un Admin del PDV (G6, ADR-021; hasta entonces cerraba cualquiera con
apertura_cierre_caja:writesobre el PDV, y era la salida de la caja de un cajero que no vino). La auditoría marca el cierre como tardío, registra quién la había abierto y sumacierre_ajeno. Para la caja vencida de un cajero ausente, el compañero Cajero ya no la destraba: la destraba el Supervisor del PDV o el Admin (si el PDV no tiene Supervisor, solo el Admin: ver la pregunta #22). Si hay un pago con la papeleta firmada sin subir, no se puede cerrar hasta subirla —y mientras tanto tampoco se puede pagar con esa caja—: las dos cosas pasan juntas y la pantalla las dice juntas. El bloqueo del pago siguiente por documentos pendientes no existe; lo que bloquea es el día.
Los países sin módulo Caja no cambian: no hay sesión que mirar.
Qué ve el operador. Un aviso fijo —no un toast— en Caja (con el botón de cierre a mano) y en Pago (con link a Caja), el badge Caja vencida y el formulario de movimiento manual deshabilitado con el motivo escrito. Está en 4.2.7 y 4.3.1.
Qué ve el Supervisor. En la vista de totales por PDV de Caja, una línea por cada PDV que tiene cajas abiertas desde un día anterior, y en Reportes la pestaña Cierres por día (4.5.1), una fila por apertura de caja con el saldo final del día. Las sesiones sin cerrar salen como Sin cerrar · Vencida o Sin cerrar · En curso, sin saldo final (también en el Excel y el PDF).
Al desplegar. Toda caja que esté abierta desde un día anterior queda vencida en el momento del deploy (en staging pueden quedar sesiones de las pruebas de QA abiertas). Hay que cerrarlas una vez. No es un bug: es la regla aplicándose a los datos existentes. Desde G6, además, las que abrió un usuario de prueba solo las cierra quien las abrió, un Supervisor o un Admin: la regla de quién cierra rige desde el deploy, sin migración, y no cambia ningún permiso.
2.11 La bóveda del PDV y los traspasos (L3)
Entrega L3 de la ronda del 14/10, ADR-029. Cada PDV con módulo Caja tiene una bóveda (la caja 0): el fondo del PDV, al que llega la plata de Tesorería y desde el que se reparte a las cajas. Ver el circuito en 1.10.
Quién la ve. Supervisor, Tesorería y Admin (los que ven todas las cajas de su PDV). El Cajero nunca: /caja/disponibles no se la manda y el historial de la bóveda le da 403. Qué no puede hacer la bóveda: abrirse y cerrarse (422 CASH_BOX_IS_VAULT), pagar (la misma 422, también si una sesión de bóveda llegara de otro lado), activarse o desactivarse desde Estaciones/PDV. Dónde queda registrado: el historial de cada caja («Traspaso hacia Caja 2», «Traspaso desde Bóveda»), Reportes → Cajas (una fila «Bóveda» y la columna «Traspasos»), y Auditoría (CASH_TRANSFERRED). Dos caminos para llegar a una caja. Tesorería puede seguir fondeando directo una caja abierta desde Saldos (atajo, QC-43): el camino principal es la bóveda.
Hallazgos para preguntas abiertas
Cosas que el código hace y ninguna documentación explica, o donde código y planes se contradicen. No las resolví — quedan para el documento de Preguntas Abiertas.
- La caja que paga no se valida contra el PDV de la transacción, solo contra su país.(Parcialmente atendido el 2026-10-06 por G4.1: la caja llena el PDV cuando ninguna otra regla lo resuelve; ver 2.5 y ADR-020. Lo que sigue abajo es lo que persiste.)
TransactionController::resolveStationForResolution()resuelve el PDV que se atribuye a la transacción por un camino separado de la caja que paga, y no se comparan. El diseño de E4-multi documenta y acepta el desacople PDV↔caja dentro de una sucursal; el cruce multipaís ya se cerró conCASH_BOX_COUNTRY_MISMATCH(2.5-2.6), pero el caso dentro de un mismo país sigue abierto. Ver 06, pregunta #6. Nadie valida quién cierra la caja.— ✅ Resuelto el 2026-10-06 (G6, ADR-021).cierre()no exigía que fuera el mismo usuario que la abrió: cualquiera conapertura_cierre_caja:writeen ese país podía cerrar la caja de otro operador —y al hacerlo, lo dejaba sin poder pagar hasta que volviera a abrir—. Con B3 había pasado a ser una ventaja buscada, porque la caja vencida de un cajero ausente la destrababa un compañero (ADR-013 §5). El cliente pidió lo contrario (RV3-25, 2026-10-02) y Carlos eligió la variante B: cierra quien abrió, el Supervisor del PDV y el Admin. Lo que queda abierto es el caso del PDV sin Supervisor (06, pregunta #22).- Fondeo y ajuste siguen exigiendo sesión abierta. Si llega un blindado fuera de turno o se detecta un faltante después del cierre, hoy no hay forma de registrarlo sin volver a abrir la caja — y con el saldo arrastrándose entre sesiones (2.1-2.2), ese desfasaje pesa más que antes. Desde B3 pesa un poco más: si la caja quedó de ayer, antes de registrar el movimiento hay que cerrarla y abrirla de nuevo (2.10). Ver 06, pregunta #11.
— ✅ Resuelto el 2026-10-06 (G7.4, ADR-022 §5).agregarCajano verifica que el país tenga el módulo Caja activoagregarCajano verificaba que el país tuviera el módulo Caja (StationController.php:117), a diferencia del alta de sucursal (:56), ni que la sucursal estuviera activa: se podían crear cajas en países sin módulo Caja, que aparecían en la base y nadie miraba. Ahora da 422CASH_MODULE_DISABLEDo 422STATION_INACTIVE. Los otros dos huecos que dejó a la vista la baja de cajas (H3-06) se cerraron en la misma entrega: desactivar una sucursal con una caja abierta da 409STATION_HAS_OPEN_CASH_BOX, y mover una sucursal a un país con módulo Caja le crea la Caja 1 (2.7). Queda un caso sin determinar: Escuintla Norte aparecía con 0 cajas en una captura del cliente y la causa no se confirmó (hipótesis, confianza baja:StationSeederla creó sin pasar porStationController::store, que es lo que crea la Caja 1). Una sucursal así no se arregla sola: «+ agregar caja» le crea la Caja 1 (el máximo de ninguna caja es 0).CASH_NOT_OPENsigue diciendo "esta sucursal" cuando el alcance real es la caja (CashBoxController.php:236).CASH_ALREADY_OPENya se corrigió a "esta caja" (:140,:206) al escribir este análisis — la inconsistencia entre los dos mensajes es nueva: antes los dos decían "sucursal" por igual, ahora uno quedó corregido y el otro no.- El asiento de Prefondeo País (y el de Holding) no aceptan fecha. El Análisis Funcional original §3.4 dice que el Supervisor completa "país, monto, fecha", pero ni
PrefundingController::store()niCountryPrefundingController::store()validan una fecha: siempre es el momento de la carga. Contradicción documentación↔código, no resuelta acá. - No se puede programar un tipo de cambio futuro.
ExchangeRateController::store()fija siempreeffective_from = now()(:67), aunque el modelo yExchangeRateService::current()soportan vigencias futuras. Cargar el TC del día siguiente por adelantado es imposible desde la UI. - La Holding puede quedar negativa y nada lo valida ni lo avisa. A diferencia del Prefondeo País (que sí admite y muestra el negativo) y de la Caja (que nunca puede ir a negativo), la Holding no tiene ningún chequeo — es la asimetría que documenta ADR-010 (Status: Proposed, sin implementar): hay aviso hacia abajo (país→caja,
OVER_COUNTRY_PREFUNDING) pero nada hacia arriba (Holding).

