Skip to content

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:write y cancelar transacciones: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ónPermisoCajeroSupervisorTesoreríaAdmin
Ver cajas, saldo y movimientoscaja:read✅ solo la suya✅ todas las de su PDV✅✅
Abrir y cerrar cajaapertura_cierre_caja:write✅ la que abrió él✅ la que abrió él❌✅
Cerrar la caja que abrió otra personaapertura_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 ajenosfondeo_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 cambiotipo_cambio:read · tipo_cambio:write❌ solo lectura❌ solo lectura✅✅
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ísprefondeo: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 PDVabm_estaciones:write❌❌❌✅
Pagar una transacciónpago:write✅✅❌✅
Cancelar una transaccióntransacciones: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_INVALID ni el campo supervisor_id_token: la columna opened_by_supervisor_id sigue en la tabla (las sesiones históricas la tienen) pero quedó nullable y 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 literalmente balance() — 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) y cash_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ún lockForUpdate de 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 el catch de QueryException reconoce 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 422 CASH_BOX_INACTIVE con 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 lee active = false y 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_INVALID si 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 suma amount_local de 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_balance queda 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 PAID viejas que se pagaron así), sin subir, responde 422 PENDING_PAYMENT_DOCUMENTS con 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_balance de 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úna apertura_cierre_caja:write y fondeo_caja:read dentro 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 (409 CASH_NOT_OPEN), dueño o supervisor (403 CASH_CLOSE_NOT_OWNER), documentos pendientes (422 PENDING_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 responde NO_CASH_BOX_OPEN_FOR_USER hasta 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 de CASH_SESSION_CLOSED suma el booleano cierre_ajeno, sin montos.

Historia. Hasta el 2026-08-05 el cierre creaba un RETIRO_CIERRE por 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 el RETIRO_CIERRE y recrear un DEPOSITO_APERTURA por 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 mismo POST /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 aviso OVER_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). Elegir Otro exige motivo_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 un SELECT DISTINCT sobre 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 warning con código OVER_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_DAY si 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) y Otro (CashMovement::MOTIVOS_AJUSTE, backend/app/Models/CashMovement.php). Blindado queda deliberadamente fuera —un blindado siempre suma, es fondeo, no ajuste— y Otro exige motivo_detalle igual que en fondeo. Si tesorería termina queriendo Blindado también acá, es agregar una constante (ver 06, pregunta #2).
  • Retiro por baja de caja saca 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, un Faltante de arqueo positivo 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 (NSelect en modo filterable+tag, alimentado por un SELECT DISTINCT motivo sobre 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ó a Otro conservando el texto original en motivo_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 PermissionService que 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 único cash_sessions_one_open_per_user garantizan que nadie tenga dos sesiones OPEN a 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. applyCashBoxDiscount devuelve el PDV de la caja y pay() 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:

CapaQué descuentaMonedaPuede quedar negativaBloquea el pago
Prefondeo Holdingprincipal + comisiónUSD (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íssolo el principalUSDSíSolo en países sin módulo Caja (Ecuador, con EPOS)
Caja de la sucursalsolo el principalUSD o moneda local, según pago_en_moneda_local del paísNoSí — 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 EFECTIVO responde 422 sin tocar la caja ni el prefondeo. Hasta G3 la pantalla ofrecía la transferencia y el descuento de caja corría igual, porque applyCashBoxDiscount() 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_PREFUNDING ya 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_DAY corta 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_RATE no 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_rate queda null si 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::transaction que 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) + 1 de 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ía CashBoxService::ensureCashBoxesForCountry()).
  • El alta valida (H3-06, G7.4): un país sin módulo Caja da 422 CASH_MODULE_DISABLED y una sucursal inactiva da 422 STATION_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 su CASH_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 por residualBalances(): una caja con quetzales adentro y dólares en cero tiene el cajón lleno y balance() 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 motivo Retiro 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 = false y responde 422 (2.1).
  • Desactivar una sucursal con una caja abierta da 409 STATION_HAS_OPEN_CASH_BOX, y con plata en sus cajas 409 STATION_HAS_CASH_BALANCE, solo en el guardado que la desactiva (el formulario reenvía active en 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_BOX o COUNTRY_HAS_CASH_BALANCE si alguna caja de una sucursal activa del país tiene una sesión abierta o plata adentro.
  • Auditoría: CASH_BOX_ADDED, CASH_BOX_DEACTIVATED y CASH_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 siempre effective_from = now() (:67), aunque el modelo y ExchangeRateService::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 (default false) 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_RATE no 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_entries no referencia a prefunding_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 vencidaResultado
Pagar (pay(), solo países con módulo Caja)422 CASH_SESSION_FROM_PREVIOUS_DAY, antes de descontar nada
Fondear422 CASH_SESSION_FROM_PREVIOUS_DAY
Ajustar422 CASH_SESSION_FROM_PREVIOUS_DAY
CerrarSolo 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 cerradaFunciona igual: hereda el saldo
Subir documentos pendientesSigue 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:

  1. "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_at es un timestamp sin 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 consultan pay(), fondeo, ajuste, GET /caja/disponibles y GET /caja/totales-pdv.
  2. 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.
  3. 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_balance no sería el del cierre contable de ayer sino el del momento en que alguien se acuerde de cerrar.
  4. 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.
  5. La cierra quien la abrió, o un Supervisor o un Admin del PDV (G6, ADR-021; hasta entonces cerraba cualquiera con apertura_cierre_caja:write sobre 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 suma cierre_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.

  1. 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ó con CASH_BOX_COUNTRY_MISMATCH (2.5-2.6), pero el caso dentro de un mismo país sigue abierto. Ver 06, pregunta #6.
  2. 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 con apertura_cierre_caja:write en 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).
  3. 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.
  4. agregarCaja no verifica que el país tenga el módulo Caja activo — ✅ Resuelto el 2026-10-06 (G7.4, ADR-022 §5). agregarCaja no 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 422 CASH_MODULE_DISABLED o 422 STATION_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 409 STATION_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: StationSeeder la creó sin pasar por StationController::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).
  5. CASH_NOT_OPEN sigue diciendo "esta sucursal" cuando el alcance real es la caja (CashBoxController.php:236). CASH_ALREADY_OPEN ya 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.
  6. 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() ni CountryPrefundingController::store() validan una fecha: siempre es el momento de la carga. Contradicción documentación↔código, no resuelta acá.
  7. No se puede programar un tipo de cambio futuro. ExchangeRateController::store() fija siempre effective_from = now() (:67), aunque el modelo y ExchangeRateService::current() soportan vigencias futuras. Cargar el TC del día siguiente por adelantado es imposible desde la UI.
  8. 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).

← Anterior · Índice · Siguiente: Diagramas de Actividad →

Documentación viva — se actualiza junto con el código, no es un anexo aparte.