Skip to content

Secuencias de Pantalla — Módulo Caja ​

Análisis Funcional: Módulo Caja — parte 5 de 7. ← Anterior · Índice · Siguiente: UX de múltiples cajas y fondeo →

Este documento recorre pantalla por pantalla el módulo Caja tal como corre hoy (E4, E4-multi y E4b en main, más la entrega B3 de la caja vencida, los extractos de tesorería de B7 y, desde el 2026-10-06, el panel Administrar de las cajas y la línea de país de Saldos, G7 y G6.C): la ruta real, el permiso que la gatea, qué muestra, qué acciones ofrece, en qué estados puede quedar y a dónde lleva cada acción. Cada afirmación sobre comportamiento cita el archivo y la línea donde vive.

Lo que sigue sin implementar queda marcado explícitamente como 📋 propuesta de UX, sin implementar cuando es un diseño de este propio paquete de documentos que nadie pidió todavía, o como 📌 pendiente cuando es una pieza que el cliente sí pidió pero no entró en ningún alcance cerrado — nunca se marca así algo que ya corre en producción.


4.1 Mapa de navegación ​

Lectura del mapa: los nombres son los del menú desde B6 (ADR-014): Saldos es la pantalla de Caja (grupo Caja, junto a Pago y Reporte individual); Prefondeo Soterex (antes Prefondeo Holding), Fondeo PDVs (antes Prefondeo País) y Tipo de cambio forman el grupo Tesorería, y Parámetros (antes Ubicaciones) conserva Países, Estaciones / PDV y Catálogos. Tipo de cambio dejó de ser una pestaña de Administración: tiene ruta propia y lo editan Tesorería y Admin (el Cajero y el Supervisor lo leen: desde G8, 2026-10-07, es solo de Tesorería y Admin). El módulo Caja no es un flujo lineal — es una pantalla operativa (/caja) alimentada por dos pantallas de configuración de Admin, por el Tipo de cambio y por el Fondeo PDVs, y consumida por una pantalla de operación (/pago) que casi no tiene vínculo visual con ella: la flecha punteada «Sin caja abierta a tu nombre» es un camino que el usuario tiene que descubrir leyendo un mensaje de error, no un link. La excepción, desde B3, es la caja vencida: Pago muestra un aviso fijo con un link a Caja — ver 4.3. Prefondeo se convirtió en dos pantallas separadas desde el 2026-08-06 (/prefondeo y /prefondeo-pais) — dos ítems de sidebar independientes, sin layout compartido entre ellas — y desde B7 cada una tiene pestañas con extractos (4.4).


4.2 Caja: ruta /caja ​

Ruta: /caja, nombre caja (frontend/src/router/index.ts:64-69). Gate de entrada: meta.module = 'caja', acción Leer. El guard global rebota a la primera ruta legible del usuario si no la tiene (frontend/src/router/index.ts:331-334). Ítem de sidebar: "Saldos" (antes "Caja", B6), ícono Banknote, visible solo con caja:read (frontend/src/layouts/AppLayout.vue:85).

Gates internos (la pantalla se ve entera, las acciones no):

AcciónPermisoDónde se evalúa
Ver saldo, movimientos y exportarcaja:readRuta + CashBoxController::authorizeStationScope (backend/app/Http/Controllers/CashBoxController.php:621-638)
Abrir / Cerrar cajaapertura_cierre_caja:writeCajaView.vue:20 (canOperate) y CashBoxController.php:124,221
Cerrar la caja que abrió otra personaLo anterior y que el backend diga session.can_close (quien abrió, o Supervisor o Admin del PDV: apertura_cierre_caja:write y fondeo_caja:read en una misma asignación)PermissionService::canCloseCashSession(), usada por cierre() (403 CASH_CLOSE_NOT_OWNER) y por disponibles() (can_close, que además exige el alcance de apertura_cierre_caja:write sobre el PDV, como la ruta) — ADR-021
Fondear / Ajustarfondeo_caja:writeCajaView.vue:21 (canFund) y CashBoxController.php:273,336

4.2.1 Entrada y estados de carga ​

Al montar, la pantalla dispara en paralelo GET /caja/disponibles y GET /caja/motivos para FONDEO y AJUSTE (CajaView.vue:349-351). /caja/disponibles devuelve todas las cajas operables de todas las sucursales donde el usuario tiene caja:read, cada una con saldo, moneda y sesión abierta (CashBoxController::disponibles(), :49-88). Desde G6 la sesión trae también quién la abrió (opened_by: {id, email}) y si quien mira puede cerrarla (can_close); opened_by_supervisor_id dejó de viajar.

EstadoCondiciónQué se veCita
Cargandoloading = trueTexto centrado "Cargando..."CajaView.vue:361
Error de cargaFalla /caja/disponibles"No se pudo cargar el estado de la caja. Probá de nuevo." en rojo, sin botón de reintentoCajaView.vue:77,362
VacíocashBoxes vacío o null"No se pudo determinar una caja con módulo Caja activo para tu usuario."CajaView.vue:363-365
Selectormás de una caja y ninguna elegidaGrilla de tarjetas, una por cajaCajaView.vue:31,368-387
Operativauna sola caja (auto) o tarjeta clickeadaVista de saldo + movimientosCajaView.vue:71-72,390
Sin permiso de rutacaja:read ausenteNunca llega: el guard redirige antes de montarrouter/index.ts:331-334

«Operable» es la definición de ADR-022 §2: la caja está activa, es de un PDV activo y de un país con módulo Caja. Una caja que un Admin desactivó no figura acá, ni como tarjeta ni en el selector.

El estado vacío es el mismo mensaje para cuatro causas distintas: el país no tiene modulo_caja, la sucursal no tiene cajas dadas de alta, todas las que tiene están dadas de baja, o el usuario no tiene sucursales asignadas. Ver Hallazgos.

4.2.2 Selector de cajas ​

Aparece solo con más de una caja disponible. Cada tarjeta es un <button> con: nombre de la sucursal (uppercase, chico), "Caja N", saldo con su moneda, un badge Caja abierta / Caja cerrada con la paleta semántica (status-success / status-cancelled) (CajaView.vue:368-387) y, si la caja está abierta, quién la tiene (G6.A3): "Abierta por vos" o "Abierta por" y el correo. Desde B3 hay un tercer estado: Caja vencida (ámbar), para una sesión que se abrió un día anterior, con una línea debajo — "Abierta desde el 01/10/2026" (ver 4.2.7).

┌──────────────────────┐  ┌──────────────────────┐  ┌──────────────────────┐
│ CENTRAL              │  │ CENTRAL              │  │ SUCURSAL NORTE       │
│ Caja 1               │  │ Caja 2               │  │ Caja 1               │
│ 12.500,00            │  │ —                    │  │ 3.200,00             │
│ ● Caja abierta       │  │ ● Caja abierta       │  │ ○ Caja cerrada       │
│ Abierta por vos      │  │ Abierta por          │  │                      │
│                      │  │ ana@cislatam.test    │  │                      │
└──────────────────────┘  └──────────────────────┘  └──────────────────────┘
┌──────────────────────┐
│ CENTRAL              │   Una caja abierta de un día anterior se ve así:
│ Caja 3               │
│ 4.100,00             │
│ ▲ Caja vencida       │
│ Abierta por vos      │
│ Abierta desde el     │
│ 01/10/2026           │
└──────────────────────┘
  • Elegir una tarjeta → vista operativa de esa caja + GET /caja/{id}/movimientos (CajaView.vue:83-86).
  • La elección no se persiste entre visitas a la pantalla: cada entrada a /caja con más de una caja vuelve a pedirla (decisión #2 del diseño de múltiples cajas). El porqué está en 5.1.
  • Con una sola caja no hay selector ni botón "Cambiar de caja" — se entra directo, exactamente como antes de E4-multi (CajaView.vue:71-72).
  • Sí distingue "abierta por vos" de "abierta por otro" (G6.A3, RV3-27; era la propuesta de 5.1.3): una línea de texto debajo del badge, no un tercer color. Viaja aunque el saldo esté oculto —en la Caja 2 del ejemplo, vista por el Cajero que tiene la Caja 1, el saldo es — y aun así ve quién la tiene—, porque saber quién opera una caja no abre la plata, y el cajero necesita saber a quién pedirle que la libere. Si el backend no pudo resolver al usuario, dice "Abierta por otro usuario" en vez de inventar un correo.

Perfiles mezclados: las cajas que ningún total alcanza. GET /caja/totales-pdv trae solo los PDV donde el usuario tiene fondeo_caja:read (ADR-021 §4), pero la pantalla entra por los totales cuando el usuario tiene ese permiso en algún lado. Un Supervisor de A que es Cajero de B vería solo la tarjeta de A y ninguna entrada a las cajas de B. Por eso, debajo de las tarjetas de totales, la pantalla suma «Otras cajas a tu alcance» con las cajas de /caja/disponibles cuyo PDV no tiene tarjeta, con las mismas tarjetas del selector y sin saldo (—); elegir una lleva a su vista operativa y de ahí se vuelve a los totales. Si los totales fallan, se dice el error y todas las cajas se ofrecen así. No se resolvió sumando esos PDV a totales-pdv: reabriría la fuga de saldos de H3-03.

La línea de país (G6.C, RV3-28). En los totales por PDV, arriba de las tarjetas, hay una franja por país con la plata que hay en sus cajas, en su moneda de pago: «Guatemala · USD 24,878.53» (GET /caja/totales-pdv trae un bloque countries[], uno por país del alcance del usuario, con country, currency, total y scope_complete; ADR-022 §7). Es lo que el cliente dibujó sobre la captura de Saldos y el mismo número que Distribuido en cajas en Fondeo PDVs: con el alcance completo el total es CountryPrefundingService::distributedInCashBoxes(), una definición y no dos que algún día discrepen.

SituaciónQué dice la línea
El usuario ve todos los PDV del país que tienen alguna caja (scope_complete)El nombre del país: «Guatemala · USD 24,878.53»
Ve solo una parte (por ejemplo, es Supervisor de un PDV y no de los otros)«Total de tus PDV · USD 4,198.46»: la suma de sus tarjetas, nunca la del país entero, que mostraría plata de PDV que no puede ver
Varios países y alcance parcial en alguno«Total de tus PDV en Guatemala», para que dos líneas no digan lo mismo
Varios paísesUna franja por país, cada una en su moneda; nunca se suma entre países ni entre monedas
País sin cajas visibles, o sin totales (fondeo_caja:read ausente)No hay línea

Al bajar a las cajas de un PDV la línea no se muestra: es de la pantalla de totales. Las tarjetas por PDV no incluyen las cajas de baja (no son operables), pero el total del país sí cuenta lo que haya en el ledger: una caja de baja está siempre en cero, así que no agrega ni quita nada. Con una excepción: un PDV inactivo tampoco tiene tarjeta (sus cajas no son operables) y su plata sí está en el ledger, así que la línea puede ser mayor que la suma de las tarjetas. Desde G7 no se desactiva un PDV con plata en sus cajas (STATION_HAS_CASH_BALANCE), de modo que hoy solo pasa con un PDV que ya estaba inactivo antes de este cambio. Queda abierta una confirmación con el cliente (QC-15, 06, pregunta #24): que la cifra sea el total de las cajas y no el disponible para distribuir.

4.2.3 Vista operativa ​

Dos columnas (md:grid-cols-[1fr_1.4fr]): tarjeta de saldo y acciones a la izquierda, panel de movimientos a la derecha (CajaView.vue:390).

┌─ CENTRAL · Caja 1 ──────── Cambiar de caja ─┐ ┌─ Desde [ ] Hasta [ ] [Excel] [PDF] ───────┐
│                                             │ ├───────────────────────────────────────────┤
│  12.500,00                                  │ │ TIPO      │    MONTO │ CUÁNDO   │ QUIÉN   │
│  ● Caja abierta                             │ ├───────────────────────────────────────────┤
│                                             │ │ Pago      │  -775,00 │ 02/08 10 │ back@…  │
│  [ Cerrar caja ]                            │ │   TC 7.7500                                │
│  ─────────────────────────────────────────  │ │   MTCN 8834201921                          │
│  MOVIMIENTO MANUAL                          │ │ Fondeo    │  +100,00 │ 02/08 09 │ super@… │
│  [ Fondeo ][ Ajuste ]                       │ │   Fondeo inicial                            │
│  [ Monto            ]                       │ └───────────────────────────────────────────┘
│  [ Motivo ▾                        ]        │ │ 8 movimientos          [Anterior][Siguiente]│
│  [        Fondear         ]                 │ └───────────────────────────────────────────┘
└─────────────────────────────────────────────┘

Botón "Cambiar de caja" — solo con más de una caja disponible; vuelve al selector recargando /caja/disponibles (refresca saldos de paso) sin recargar la página (CajaView.vue:92-94,394-400).

Saldo — número grande, 2 decimales, formateado con Intl.NumberFormat('es-GT') con su moneda: desde el 2026-08-06, /caja/disponibles devuelve currency (CashBoxController.php:78, comentario explícito: "sin esto el frontend no puede rotular los montos") y CajaView.vue la usa tanto en el saldo (:50,55-57,402) como en cada movimiento con su propia moneda histórica (:591). La deuda que documentaba la versión anterior de este análisis —la moneda ausente en toda la pantalla— está resuelta.

Saldo residual en otra moneda — si el país cambió de moneda de pago y quedó plata en la anterior, una línea de advertencia lo muestra aparte, sin que desaparezca del cajón (CashBoxController::residualBalances(), CashBoxService.php:50-62; render en CajaView.vue:405-411).

Badge de estado — Caja abierta (verde) / Caja cerrada (gris) / Caja vencida (ámbar, B3), derivado de selected.session y de su from_previous_day. Debajo, con la caja abierta, una línea con la fecha y la hora de apertura en hora de Guatemala y quién la abrió — "Abierta el 02/10/2026 08:15 por vos" o "…por ana@cislatam.test" — que es el día con el que el backend decide si la caja venció.

Botón principal, mutuamente excluyente (CajaView.vue:422-437):

Estado de la cajaBotónEstilo
CerradaAbrir cajaSólido, acento de marca
Abierta, y can_close verdaderoCerrar cajaContorno, alert-danger
Abierta por otro, y can_close falsoNinguno: en su lugar, una línea "La abrió ana@cislatam.test: solo esa persona, un Supervisor o un Admin pueden cerrarla." con un ícono de informaciónTarjeta gris, data-test="cierre-ajeno"
VencidaNinguno acá: el Cerrar caja (o, si no puede cerrarla, a quién pedírselo) vive en el aviso fijo de arriba (4.2.7)—

Sin apertura_cierre_caja:write no se renderiza ninguno de los dos (CajaView.vue:422). Cerrar caja exige las dos cosas: ese permiso y session.can_close. El backend calcula can_close con la misma función que decide el 403 de cierre() (el alcance sobre el PDV y la regla del dueño), así que la pantalla no ofrece el botón donde el backend lo va a rechazar: refleja, no deduce (ADR-013 §6, ADR-021).

Bloque "Movimiento manual" — visible solo con fondeo_caja:write y caja abierta (CajaView.vue:439); con la caja vencida se ve pero queda deshabilitado, con el motivo escrito (4.2.7). Es un solo formulario compartido por Fondeo y Ajuste, con un toggle segmentado arriba (:442-457). El criterio de diseño completo está en 5.2. El motivo sale de un NSelect cerrado —sin tag ni filterable— alimentado por el catálogo del backend (:494-499), y "Otro" despliega un campo de detalle obligatorio (:500-507).

Aviso de fondeo por encima del prefondeo disponible del país — banner inline persistente dentro de la tarjeta de saldo, con ícono TriangleAlert, que se muestra cuando el fondeo devuelve un warning y se descarta con el botón × (CajaView.vue:470-490). No hay auto-dismiss ni notificación de éxito duplicada: si hay warning, la notificación flotante "Caja fondeada" no se dispara (:288-294).

Panel de movimientos — GET /caja/{id}/movimientos, columnas Tipo / Monto / Cuándo / Quién. Los pagos muestran TC y MTCN inline debajo del tipo (CajaView.vue:575-580), y cualquier movimiento con motivo lo muestra en una línea chica atenuada, con el detalle si es "Otro" (:583-585). El monto se colorea verde si es ≥ 0 y rojo si es negativo (:587-592).

Paginado. El backend pagina de a 25 (CashBoxController::movimientos(), :100-102) y desde el 2026-08-06 la pantalla sí renderiza controles: total de movimientos, página actual y botones Anterior/Siguiente cuando hay más de una página (CajaView.vue:121-139,599-629). La versión anterior de este análisis documentaba esto como un bug de UI sin resolver — ya no lo es.

Estados del panel de movimientos:

EstadoQué se veCita
CargandoFila única "Cargando..."CajaView.vue:564-566
Vacío"Sin movimientos todavía."CajaView.vue:567-569
ErrorNinguno — falla en silencio y deja la tabla vacía, indistinguible del estado vacío realCajaView.vue:130-138

Export — rango datetime-local desde/hasta (default: hoy 00:00 → ahora) y dos botones, Excel y PDF. El rango incluye hora a propósito: un arqueo de turno necesita minutos, no días (CajaView.vue:316-339, CashBoxController::reporte(), :531-606). Errores del export se muestran inline debajo de los botones (CajaView.vue:551). El PDF sale con membrete de marca vía ReportExportService, igual que Reportes y Auditoría. El export no ofrece filtrar ni exportar por tipo o motivo desde esta pantalla, aunque el backend ya acepta esos filtros (ver Hallazgos y 5.3.4).

4.2.4 Modal "Abrir caja" ​

Un solo paso, sin autorización de Supervisor y sin monto editable (CajaView.vue:635-672).

┌────────────────────────────────┐
│ Abrir caja                     │
│                                │
│ Saldo inicial                  │
│ 12.500,00                      │
│ Es el saldo con el que quedó   │
│ la caja al cerrar la última    │
│ vez.                           │
│                                │
│ Si la plata que hay en la caja │
│ no coincide con este monto,    │
│ abrí igual y registrá la       │
│ diferencia como un ajuste. Si  │
│ entra plata nueva, cargala     │
│ como fondeo.                   │
│                                │
│ [ Abrir caja ] [ Cancelar ]    │
└────────────────────────────────┘
  • El saldo mostrado es selected.balance — el mismo saldo derivado que ya trae /caja/disponibles, que es exactamente lo que hereda la apertura (CajaView.vue:642).
  • No distingue la primera apertura de una caja (saldo 0 "de verdad") de una apertura normal con saldo heredado: el texto es el mismo en los dos casos, a diferencia de lo que diseñaba 5.6 para el caso de primera apertura.
  • No muestra la procedencia del saldo heredado (fecha y usuario del cierre anterior) — el texto es genérico ("Es el saldo con el que quedó la caja al cerrar la última vez"), sin la fecha/hora ni el email que proponía el documento 5. Ver Hallazgos.
  • Un solo botón primario (Abrir caja) y Cancelar; sin paso intermedio.
  • USER_ALREADY_HAS_OPEN_CASH_BOX se muestra inline dentro del modal (CajaView.vue:654). CASH_ALREADY_OPEN (otra persona abrió esa caja después de que se cargó la pantalla; G6.A1) cierra el modal, muestra una notificación "La caja ya está abierta" con el mensaje del backend —"La Caja 1 de Central la tiene abierta ana@cislatam.test."— y vuelve a pedir la caja, que ya no ofrece Abrir caja: reintentar daría lo mismo.
  • Es un <div class="fixed inset-0"> a mano, sin role="dialog", aria-modal, focus trap ni cierre con Escape (:635) — la reescritura de E4b no aprovechó para migrarlo a NModal. Sigue siendo la misma deuda de accesibilidad que documentaba la versión anterior de este análisis, ahora sobre un modal más simple. Ver 5.8.3.

4.2.5 Modal "Cerrar caja" ​

ConfirmDialog (NModal + NCard con role="alertdialog"), texto: "Se va a registrar el saldo final de la caja y no vas a poder cargar más movimientos hasta volver a abrirla. La plata queda en la caja: la próxima apertura arranca con ese mismo saldo.", botón de confirmación en variante danger (CajaView.vue:674-683). Si la caja la abrió otra persona (solo la ve quien puede cerrarla: un Supervisor o un Admin), el diálogo suma al final: "Esta caja la abrió ana@cislatam.test: esa persona no va a poder pagar hasta volver a abrirla. El cierre queda registrado a tu nombre." El nombre se fija al abrir la confirmación y no se lee de la caja elegida: al terminar el cierre la pantalla se refresca, y el diálogo, que todavía se está yendo, no tiene que cambiar de texto delante de quien lo confirmó. Si el backend responde 403 CASH_CLOSE_NOT_OWNER (la pantalla se había quedado con un can_close viejo), muestra su mensaje y vuelve a pedir la caja, que ya no ofrece el botón.

Este texto ya refleja el modelo con arrastre de saldo — la mención antigua a "un retiro" y a que "la caja va a quedar en cero" se sacó cuando se implementó E4b.1, y el mensaje sobre un comprobante de cierre que no existe (ver 06, pregunta #9) se eliminó junto con ella: la notificación de éxito hoy es un simple Caja cerrada (:206), sin mencionar ningún comprobante.

Al confirmar, el backend registra closing_balance sin crear ningún movimiento (CashBoxController::cierre(), :221-271). A diferencia del diseño propuesto en 5.6.4, el diálogo implementado no repite el monto exacto ni el nombre de la caja en el cuerpo — es un texto fijo, no interpolado.

4.2.6 Errores del backend, y dónde los ve el usuario ​

Cada código de error del backend es un estado de UI distinto:

CódigoHTTPOrigenDónde apareceTexto que ve el usuario
CASH_ALREADY_OPEN409CashBoxController::cajaYaAbierta()Notificación flotante "La caja ya está abierta"; el modal se cierra y la pantalla se pone al día"La Caja 1 de Central la tiene abierta ana@cislatam.test." — o "Ya tenés abierta la Caja 1 de Central." si es la propia (G6.A1)
USER_ALREADY_HAS_OPEN_CASH_BOX409CashBoxController.php:156-163,209-214Inline en el modal de apertura"Ya tenés la caja N de {sucursal} abierta a tu nombre. Cerrala antes de abrir otra." — o, si le cambiaron la asignación y ya no tiene acceso a ese PDV (G6): "Tenés la caja N de {sucursal} abierta a tu nombre y ya no tenés acceso a ese PDV para cerrarla: pedile a un Supervisor o un Admin de {sucursal} que la cierre antes de abrir otra."
CASH_NOT_OPEN409CashBoxController.php:233-237Notificación flotante de error; al cerrar, la pantalla se refresca (la cerró otra persona antes: con G6 la pueden cerrar el dueño y un Supervisor o Admin)"No hay una sesión de caja abierta para esta sucursal."
CASH_SESSION_CLOSED422CashBoxController.php:285-289 (fondeo), :348-352 (ajuste)Inline bajo el formulario de movimiento manual"No se puede fondear/ajustar una caja sin sesión abierta."
CASH_SESSION_FROM_PREVIOUS_DAY422CashBoxController::fondeo() y ajuste(), vía CashBoxService::fromPreviousDayError()La pantalla se refresca y aparece el aviso fijo de caja vencida; el mensaje inline se descarta"Esta caja quedó abierta desde el 01/10/2026. Cerrala y abrila de nuevo para operar hoy."
CASH_CLOSE_NOT_OWNER403CashBoxController::cierre(), tras encontrar la sesión y antes del control de documentos (G6.B2)Notificación flotante de error "No se pudo cerrar la caja"; la pantalla se refresca y deja de ofrecer el botón"Esta caja la abrió otra persona. Solo quien la abrió, un Supervisor o un Admin pueden cerrarla."
PENDING_PAYMENT_DOCUMENTS422CashBoxController::cierre()Notificación flotante y, con la caja vencida, también fijo dentro del aviso"No se pudo cerrar la caja: hay pagos de esta sesión con documentación pendiente (MTCN: documentos…). Subí lo que falta y volvé a cerrar."
ADJUSTMENT_WOULD_GO_NEGATIVE422CashBoxController.php:360-365Inline bajo el formulario"Este ajuste dejaría la caja en saldo negativo."
PERMISSION_DENIED403CashBoxController.php:626-634,640-646Inline o notificación según la acción"No tenés permiso para esta acción sobre esta caja."

Ya no existe SUPERVISOR_INVALID: no hay segundo usuario que autenticar en la apertura.

CASH_ALREADY_OPEN dice "esta caja" en vez de "esta sucursal" —se corrigió al implementar E4b.1— y, desde G6, quién la tiene. CASH_NOT_OPEN sigue diciendo "esta sucursal": quedó desactualizado y es ahora la única inconsistencia entre los dos mensajes (antes los dos decían lo mismo por igual). Ver Hallazgos.

El aviso de fondeo por encima del prefondeo disponible del país (OVER_COUNTRY_PREFUNDING) no es un error: responde 201, el movimiento ya se creó, y se muestra como banner persistente dentro de la tarjeta de saldo, no en esta tabla de errores. Ver 4.2.3 y 5.4.

4.2.7 Caja vencida (B3) ​

Una caja con la sesión abierta de un día anterior (ADR-013, reglas R18 y R19 del resumen). La pantalla no calcula si una caja está vencida: el backend manda from_previous_day y opened_on en GET /caja/disponibles, y la pantalla los refleja. Cuatro lugares cambian:

1. Aviso fijo, arriba de todo. No es un toast: no se va solo ni tiene "X". Va antes del aviso de documentos pendientes, porque ese puede tener una lista de decenas de pagos y dejaría el aviso fuera de pantalla.

┌──────────────────────────────────────────────────────────────────────────────┐
│ ▲ Esta caja quedó abierta desde el 01/10/2026. Cerrala y abrila de nuevo     │
│   para operar hoy.                                                           │
│   Hasta que la cierres no se puede pagar, fondear ni ajustar. Al abrirla de  │
│   nuevo el saldo se mantiene.                                                │
│                                                                              │
│   [ Cerrar caja ]                                                            │
└──────────────────────────────────────────────────────────────────────────────┘
  • El botón Cerrar caja del aviso es el único mientras la caja está vencida (el de la tarjeta de saldo se oculta: dos botones iguales en la misma pantalla confunden). Se muestra solo si quien mira puede cerrarla: tiene apertura_cierre_caja:write y el backend dice can_close (la abrió él, o es Supervisor o Admin del PDV; ADR-021). Si no, el aviso no trae botón y dice a quién pedírselo, en vez de dejar al usuario sin salida:
    • Si la caja la abrió otra persona y quien mira no puede cerrarla (un Cajero compañero): el aviso lo reduce a "Esta caja quedó abierta desde el 01/10/2026." y "Hasta que se cierre no se puede pagar, fondear ni ajustar con ella." —no le dice "cerrala", que no es suyo— y agrega "Esta caja la abrió ana@cislatam.test: solo esa persona, un Supervisor o un Admin pueden cerrarla. Pedile a un Supervisor o un Admin que la cierre." Sin la línea de pagos pendientes ni el link a Pago, que hablan de la caja propia.
    • Si su usuario no tiene apertura_cierre_caja:write (por ejemplo, solo Tesorería): "Tu usuario no puede cerrar cajas: pedile a un Supervisor o un Admin que la cierre."
  • Con documentos pendientes, el aviso suma una línea: "Además tenés N pagos con documentación pendiente. Si alguno es de esta caja, no se puede cerrar hasta que subas lo que falta. Están listados abajo." El N es una estimación —los pagos pendientes de todo el usuario, no solo de esta sesión—, por eso dice "si alguno es de esta caja". Con acceso a Pago, un link "Ver los pagos pendientes" lleva a /pago.
  • Si el cierre es rechazado con PENDING_PAYMENT_DOCUMENTS, el aviso pasa a mostrar fijo el detalle exacto que devolvió el backend: "No se pudo cerrar la caja: hay pagos de esta sesión con documentación pendiente (MTCN: documentos…). Subí lo que falta y volvé a cerrar." El toast que ya existía desaparece solo, y el operador necesita ver qué papeleta falta mientras va a subirla. El detalle se limpia al elegir otra caja y al cerrar con éxito.

2. Estado de la tarjeta. El badge pasa a Caja vencida (ámbar) y la línea "Abierta el dd/mm/YYYY HH:mm" muestra el día de apertura. En el selector, la tarjeta suma "Abierta desde el dd/mm/YYYY" (4.2.2).

3. Movimiento manual deshabilitado, con el motivo escrito. El toggle Fondeo/Ajuste, el monto, el motivo y el botón de enviar quedan deshabilitados, y arriba del formulario una tarjeta ámbar dice "No se puede fondear ni ajustar. Esta caja quedó abierta desde el…". El motivo está en texto visible y enlazado con aria-describedby al botón: un title no se ve en una tablet ni lo lee quien no pasa el mouse.

4. Totales por PDV (Supervisor, Tesorería y Admin). Cada PDV que tiene cajas abiertas de un día anterior suma una línea ámbar en su tarjeta: "N cajas abiertas desde un día anterior" (stale_cash_boxes). Es la forma de ver qué PDV tiene una caja trabada sin abrir cada una.

Si la caja cruza la medianoche con la pantalla abierta. La pantalla no lo sabe todavía: el primer fondeo o ajuste recibe CASH_SESSION_FROM_PREVIOUS_DAY, la pantalla se refresca y aparece el aviso con el botón de cierre; el mensaje inline del formulario se descarta porque el aviso ya dice lo mismo.

EstadoQué se ve
Caja abierta hoySin aviso. Todo como en 4.2.3
Caja vencida propiaAviso con Cerrar caja, badge ámbar, movimiento manual deshabilitado, con el texto de siempre ("Cerrala y abrila de nuevo para operar hoy")
Caja vencida que abrió otro, y quien mira es Supervisor o Admin del PDVAviso con Cerrar caja, que no le habla como a su dueño: dice "La abrió" y el correo, y que al cerrarla el saldo se mantiene y esa persona la abre de nuevo. El diálogo de confirmación advierte que su dueño no va a poder pagar hasta volver a abrirla
Caja vencida que abrió otro, y quien mira no puede cerrarla (Cajero; Tesorería, que mira sin operar)Aviso sin botón: dice quién la abrió y que se lo pida a un Supervisor o a un Admin
Caja vencida propia, sin permiso de apertura y cierre (se lo sacaron)Aviso sin botón, con la línea "Tu usuario no puede cerrar cajas: pedile a un Supervisor o un Admin que la cierre."
Caja vencida con pagos pendientesEl aviso suma la línea de los pagos pendientes y el link a Pago, si el usuario tiene ese módulo
Cierre rechazado por documentosEl aviso muestra fijo qué MTCN y qué documentos faltan

4.3 Pago: ruta /pago (lo que toca Caja) ​

Ruta: /pago, meta.module = 'pago' (router/index.ts:32-36). Es la pantalla operativa del perfil Cajero (el Backoffice de antes): buscar una transacción y pagarla. Cancelarla, desde B6, solo lo puede el Admin.

Acá solo interesa su relación con Caja, y la relación es asimétrica: cuando el país tiene modulo_caja activo, cada pago descuenta la caja que el operador abrió a su propio nombre (TransactionController::applyCashBoxDiscount, backend/app/Http/Controllers/TransactionController.php:319-402) — pero la pantalla no muestra nada de eso.

4.3.1 Lo que hoy muestra la pantalla sobre Caja ​

Casi nada. No muestra saldo de caja, no muestra qué caja tiene abierta el operador, y no indica que un pago va a mover efectivo físico. La única mención de dinero es el monto de la transacción, formateado en USD fijo (PagoView.vue:170-172). La existencia de la caja se revela solo cuando el pago falla, con una excepción desde B3: si la caja que el propio operador abrió quedó de un día anterior, la pantalla lo avisa antes de que intente pagar.

PagoView.vue consulta GET /caja/disponibles —al entrar y de nuevo en cada búsqueda— y se queda con la sesión abierta por el usuario logueado (opened_by_user_id), que es la que pay() descuenta. No hay endpoint nuevo. Si esa sesión trae from_previous_day, la pantalla muestra:

  • Un aviso fijo arriba de todo, antes del aviso de documentos pendientes: "Esta caja quedó abierta desde el dd/mm/YYYY. Cerrala y abrila de nuevo para operar hoy.", con la línea "Hasta que la cierres no se puede pagar, fondear ni ajustar. Al abrirla de nuevo el saldo se mantiene." y un link Ir a Caja (si el usuario tiene ese módulo). Es el mismo componente que el de Caja (4.2.7), así que dice lo mismo en las dos pantallas. Con pagos pendientes de documentación suma "Además tenés N pagos con documentación pendiente… Están listados abajo", que son los que hay que subir antes de poder cerrar la caja.
  • El botón "Iniciar pago" deshabilitado, con el motivo como primer renglón de la tarjeta ámbar de "Qué falta para poder pagar" (manual de Pago). Es el primero porque subir documentos o guardar datos no lo destraba y se resuelve en otra pantalla.
  • Solo bloquea las transacciones del país de esa caja: pay() mira la sesión únicamente en países con módulo Caja, y deshabilitar el pago de otro país sería bloquear algo que el backend deja hacer.

A quien le cierran la caja. Un Supervisor o un Admin puede cerrar la caja que abrió otro (desde G6, solo ellos: ADR-021). Si ese otro estaba en Pago con la pantalla cargada, el siguiente pago responde NO_CASH_BOX_OPEN_FOR_USER (ver 4.3.2): la pantalla no se entera antes, porque la sesión que tenía en memoria ya no existe. Es el motivo por el que la confirmación del cierre ajeno le avisa a quien cierra que "esa persona no va a poder pagar hasta volver a abrirla".

Si el front no se enteró (pantalla abierta que cruzó la medianoche, o un usuario sin caja:read), el backend manda: pay() responde CASH_SESSION_FROM_PREVIOUS_DAY, la pantalla cierra el modal de confirmación, muestra el toast "Esta caja quedó abierta de un día anterior" con el mensaje del backend, y queda con el aviso y el motivo a la vista.

Tampoco muestra nada sobre documentos obligatorios de ADR-008 fuera del propio bloque DocumentacionPrePago (que sí tiene tratamiento dedicado, PagoView.vue:283-292) — eso no cambió.

4.3.2 Errores de saldo, sesión y documentos ​

CódigoHTTPCuándoTratamiento en la UI
INVALID_STATUS_TRANSITION409Otro usuario resolvió la transacción primero✅ Tratamiento dedicado: notificación de warning + re-búsqueda automática (PagoView.vue:141-148)
INSUFFICIENT_PREFUNDING422El Prefondeo País no cubre amount (solo en países sin módulo Caja)✅ Tratamiento dedicado: título propio y saldo disponible, sin exponer la comisión (PagoView.vue:149-156)
MISSING_REQUIRED_DOCUMENTS422Faltan carta/identificación (ADR-008) — cubre la carrera de dos operadores confirmando casi a la vez✅ Tratamiento dedicado: título propio (PagoView.vue:157-166)
CASH_SESSION_FROM_PREVIOUS_DAY422La sesión OPEN del usuario se abrió un día anterior (B3, ADR-013)✅ Tratamiento dedicado: aviso fijo con link a Caja, "Iniciar pago" deshabilitado con el motivo, y toast propio si el backend lo rechaza igual (PagoView.vue)
NO_CASH_BOX_OPEN_FOR_USER422El usuario no tiene ninguna sesión OPEN a su nombre❌ Sin tratamiento propio: cae en el else genérico "No se pudo procesar el pago" con el mensaje del backend (PagoView.vue:167-173)
CASH_BOX_COUNTRY_MISMATCH422La caja abierta es de otro país que la transacción❌ Mismo else genérico
INSUFFICIENT_CASH_BALANCE422El saldo de la caja no cubre el monto convertido❌ Mismo else genérico
NO_EXCHANGE_RATE422El país paga en moneda local y no hay TC vigente❌ Mismo else genérico

El mensaje del backend para NO_CASH_BOX_OPEN_FOR_USER sí es bueno y accionable — "No tenés ninguna caja abierta a tu nombre — abrí una desde Saldos antes de pagar." (TransactionController.php:335) — pero llega como cuerpo de una notificación genérica, sin link a /caja. Con C5 implementado (el pago con módulo Caja activo ya no valida prefondeo), los tres errores de saldo/sesión de caja son hoy el único bloqueo posible de un pago en un país con Caja, y ninguno tiene tratamiento propio — se invirtió exactamente la prioridad de lo que sí está resuelto (INSUFFICIENT_PREFUNDING, que en Guatemala ya no puede ocurrir). Desde B3 el cuarto bloqueo posible, CASH_SESSION_FROM_PREVIOUS_DAY, sí lo tiene.

Propuesta de UX, sin implementar — mostrar en /pago un indicador permanente de la caja abierta ("Cobrando desde: Central · Caja 2 — saldo 12.500,00 GTQ") y dar a NO_CASH_BOX_OPEN_FOR_USER/CASH_BOX_COUNTRY_MISMATCH/INSUFFICIENT_CASH_BALANCE un tratamiento de primera clase, con CTA a /caja (el aviso de caja vencida de B3 ya lo tiene, y es el modelo a seguir). El fundamento está en 5.1; sigue sin estar en ningún alcance escrito.


4.4 Prefondeo: dos rutas, dos pantallas, cuatro extractos ​

Desde el 2026-08-06 el prefondeo son dos pantallas separadas —dos ítems de sidebar independientes, hoy en el grupo Tesorería: "Prefondeo Soterex", antes "Prefondeo Holding", con ícono Wallet, y "Fondeo PDVs", antes "Prefondeo País", con ícono Landmark; los nombres y la agrupación cambiaron en B6, las rutas y los módulos de permiso, no—. La propuesta de este documento de usar un TabbedSectionLayout con redirect dinámico (ver la versión anterior de este análisis) no se adoptó: la solución real es más simple, dos rutas de primer nivel.

Desde B7 (ADR-015, 2026-10-02) cada pantalla suma pestañas, y cada pestaña es un extracto: el mismo dinero como estado de cuenta, con el saldo que quedó después de cada movimiento. Las pestañas son un componente propio dentro de cada pantalla (PestanasSeccion.vue), no rutas hijas: la URL no cambia al pasar de una a otra.

RutaPantallaPestañasPermiso de cada una
/prefondeoPrefondeo SoterexSoterex ↔ CIS Holding (E1) y CIS Holding (E2)prefondeo:read las dos
/prefondeo-paisFondeo PDVsPaís (E3) y PDV (E4)prefondeo_pais:read y fondeo_caja:read

La forma de cada extracto, y qué movimiento va a cuál, está en el modelo de saldos, 1.10.

4.4.1 Prefondeo Soterex: ruta /prefondeo ​

Ruta: /prefondeo, meta.module = 'prefondeo' (router/index.ts:49-54).

PrefondeoView.vue tiene tres bloques, de arriba hacia abajo:

  1. Saldo con Soterex (:102-116; hasta G12 se llamaba «Saldo global de la Holding»): todos los países juntos, en USD (PrefundingService::globalBalance(), backend/app/Services/PrefundingService.php). Es lo que queda del prefondeo de Soterex, o sea el saldo corrido de la pestaña Soterex ↔ CIS Holding. La leyenda de la tarjeta lo dice, y avisa que el Monto actual de la pestaña CIS Holding es otro número (ahí la comisión suma): con esa pestaña abierta, los dos números a la vista parecían contradecirse (verificación manual de B7). Con un alcance parcial (el usuario no lee todos los países, G12/D3-19 b) la tarjeta suma solo los suyos, se llama «Saldo de la Holding — de sus países», deja de decir «De todos los países juntos» y muestra el aviso que manda el backend (scope.message). Sin scope en la respuesta —multipaís sin país elegido— se lee como siempre. Los números de línea de este apartado son de antes de G12.
  2. Nuevo asiento (:118-155, solo con prefondeo:write): monto y una referencia opcional (:136-145), texto libre de hasta 255 caracteres. Es una sola caja para las dos referencias que lleva el Financial Report de Ecuador (REF BAN, la del banco, y REF INT, la interna): por ahora se escriben juntas. Si el cliente las quiere separadas es la pregunta 1 de ADR-015.
  3. Los dos extractos, en pestañas (:158-180), con el recorrido guiado anclado a todo el bloque (data-tour="prefondeo-asientos").
EstadoQué se veCita
Saldo cargando"..." en lugar del númeroPrefondeoView.vue:110
Error al cargar el saldo"No se pudo cargar el saldo de la Holding. Probá de nuevo."PrefondeoView.vue:54,115
Selector de país del altaSolo si el usuario puede escribir en más de un paísPrefondeoView.vue:121
Filtro de país de los extractos«Todos los países» por defecto; solo aparece con más de un país legible. Elegir uno pide el desglose de ese país (el extracto sale parcial)PrefondeoView.vue:164-177
Sin permiso de escrituraEl bloque «Nuevo asiento» no se renderizaPrefondeoView.vue:118

Validación de alta en el cliente: monto ≤ 0 → "Ingresá un monto mayor a 0.". Éxito → "Asiento cargado.", y se recargan el saldo y el extracto que se está mirando (el asiento es un crédito más). No hay confirmación antes de cargar un asiento: un dígito de más se corrige con otro asiento y no tiene consecuencia operativa inmediata, a diferencia del asiento del país (ver 4.4.2).

Dos números distintos en la misma pantalla. La tarjeta de arriba es el saldo con Soterex (lo que queda del prefondeo de Soterex, con los pagos restando principal más comisión). La pestaña CIS Holding tiene su propio Monto actual: recibido − enviado a países + comisiones, que cuenta la comisión al revés porque responde otra pregunta. No son el mismo número ni deben coincidir: está explicado en ADR-015 §4.

4.4.2 Fondeo PDVs: ruta /prefondeo-pais ​

Ruta: /prefondeo-pais, meta.module = 'prefondeo_pais' y, desde B7, meta.modules = ['prefondeo_pais', 'fondeo_caja'] (router/index.ts:68): se entra con cualquiera de los dos permisos. El guard y firstAllowedRoute() siguen esa lista (puedeLeerRuta(), router/index.ts:346); el ítem del menú aplica la misma regla en su isVisible() (AppLayout.vue:189), y un spec de AppLayout afirma que ningún enlace visible lleva a una ruta que el guard rechace. module queda como el principal: el «?» elige el primer módulo de la lista que el usuario puede leer (composables/useActiveTour.ts:19), así que el Supervisor va a la sección #fondeo_caja del manual y no a una que su perfil no tiene.

Pestañas (PrefondeoPaisView.vue:32-36): País aparece con prefondeo_pais:read y PDV con fondeo_caja:read. Con una sola la barra no se dibuja (:164): el Supervisor entra y ve directamente la de sus PDVs. Esa pantalla no le pide nada a /prefondeo-pais (:66): el backend se lo respondería con 403. Sin ninguna de las dos, "No tenés acceso a ningún extracto de esta pantalla." (:156), que en la práctica no se ve porque la ruta ya lo bloqueó.

Pestaña País ​

Muestra el saldo del país (solo principales, puede ser negativo) y, debajo, su desglose en dos números derivados:

SALDO DEL PAÍS
12.500,00 USD

├─ Distribuido en cajas          5.500,00 USD
└─ Disponible para distribuir    7.000,00 USD

Repartir plata a una caja no baja el saldo del país — recién
baja cuando se paga una transacción.
BloqueFuente
Saldo del paísCountryPrefundingService::balance() (backend/app/Services/CountryPrefundingService.php) — puede ser negativo, se muestra en rojo con una nota (PrefondeoPaisView.vue:185-205)
Distribuido en cajasCountryPrefundingService::distributedInCashBoxes() — suma los saldos de todas las cajas del país, filtrando por la moneda de pago vigente
Disponible para distribuirLa resta de los dos anteriores — puede ser negativo si las cajas ya tienen más plata que el país; en ese caso se marca en rojo (:59-61,224-226)

El desglose completo (CountryPrefundingController::index() → breakdown) viaja en un solo request; PrefondeoPaisView.vue lo oculta cuando el país no tiene módulo Caja activo (showDistribution, :57) — en ese caso la tarjeta muestra solo el saldo, sin las dos filas derivadas.

El extracto de la pestaña (E3) tiene como saldo corrido el disponible para distribuir, no el saldo de la tarjeta: en el extracto, fondear una caja baja el saldo corrido, y la tarjeta de arriba no se mueve. Es lo que la planilla del cliente llama «CIS Guatemala» y lo que el cliente espera ver (1.10). Los pagos no son una línea de este extracto: no mueven el disponible.

Comparado con el diseño original de este paquete (5.7.2), lo implementado es más simple: sin badges nombrados (Sobregiro, Sobredistribuido), sin el link [Ver] hacia Reportes → Cajas, sin íconos Wallet/Banknote — solo color rojo sobre el número y un párrafo explicativo cuando corresponde. El bloque "Circuito de fondos" que proponía 5.7.4 no se implementó: ninguna pantalla conecta visualmente las tres capas de una sola pasada. Los extractos de B7 muestran cada capa como estado de cuenta, y el circuito completo vive en el análisis (1.10).

El alta de asiento es monto (>0) + referencia opcional en texto libre —no el catálogo cerrado de Caja, que es de otro dominio (PrefondeoPaisView.vue:230-255)— y tampoco pide confirmación antes de guardar, a diferencia de lo que proponía 5.7.3. Al guardar se recargan el saldo, el desglose y el extracto.

EstadoQué se veCita
Saldo cargando"..."PrefondeoPaisView.vue:195
Error"No se pudo cargar el prefondeo del país. Probá de nuevo."PrefondeoPaisView.vue:75,204
Selector de paísSolo con más de un país legiblePrefondeoPaisView.vue:174-182

Pestaña PDV ​

El extracto (E4) de un PDV: lo que tiene en sus cajas. Los movimientos son los de las cajas del PDV (fondeos, ajustes, pagos con su MTCN) y el saldo corrido cierra con la suma de los saldos de sus cajas. Suma la columna Caja.

  • Selector de PDV. Sale de las asignaciones del usuario que tienen fondeo_caja:read: los PDVs de la lista si la asignación está acotada, o todos los del país si no lo está (PrefondeoPaisView.vue:122-132). Con varios países se agrupa por país (:278-282); con un solo PDV no hay selector, se ve el nombre (pdv-unico, :288); con ninguno, "No hay PDVs a tu alcance." (:291).
  • El backend manda. Es la misma regla que aplica TreasuryStatementController::resolveStationScope(): si igual se pide un PDV fuera del alcance —o uno que no existe, que responde igual—, el extracto muestra el 403 con su mensaje.
  • Supervisor. Ve únicamente los PDVs de su asignación: dos PDVs, dos opciones; un tercero, 403 por API.

4.4.3 El extracto: el componente que usan las dos pantallas ​

ExtractoTesoreria.vue dibuja los cuatro extractos; cada pantalla le pasa el tipo (soterex-holding, holding, pais, pdv) y el alcance. Lo que hace es lo mismo para todos:

CIS Guatemala                                                   [Exportar Excel] [Exportar PDF]
Desde [01/10/2026]   Hasta [02/10/2026]   Orden [Más antiguos primero]

Monto actual         Saldo anterior       Débitos del período    Créditos del período
USD 7,000.00         USD 0.00             USD 23,000.00          USD 30,000.00
Disponible para distribuir del país

Fecha               Concepto                           Referencia       Débito          Crédito         Saldo
1 oct 2026          Saldo anterior                                                                      USD 0.00
2 oct 2026, 10:05   Prefondeo recibido de la Holding                                    USD 30,000.00   USD 30,000.00
2 oct 2026, 10:10   Fondeo de caja — Blindado          PDV1 · Caja 1    USD 5,000.00                    USD 25,000.00
2 oct 2026, 10:12   Fondeo de caja — Blindado          PDV2 · Caja 1    USD 18,000.00                   USD 7,000.00

(Ilustrativo: el formato de los montos y de las fechas es el de la app, USD 1,234.56 y Intl es-GT. Los números son los de la planilla del cliente; los pagos no aparecen porque el disponible del país no se mueve.)

  • Columnas: Fecha · Concepto · Referencia · Débito · Crédito · Saldo. El de PDV suma Caja; los de la Holding suman País, pero solo cuando el alcance tiene más de un país (con uno repetiría lo mismo en cada fila). Un crédito suma al saldo corrido y un débito resta.
  • Encabezado: Monto actual (el que da el servicio de saldos hoy), Saldo anterior (justo antes del «Desde»), Débitos y Créditos del período. El Saldo al cierre del período aparece solo si el rango no llega hasta hoy (si llega, es el Monto actual) (ExtractoTesoreria.vue:211). Rótulos que el cliente compara con su hoja (G12.4): el extracto de País se encabeza CIS y el país («CIS Guatemala», la columna de su hoja) y su PDF se titula Extracto — Fondeo PDVs · País (disponible para distribuir) (el Excel no lleva título); el Monto actual de Soterex ↔ CIS Holding dice Saldo con Soterex; el de CIS Holding aclara que incluye las comisiones y no lo ya enviado a los países; y bajo los Créditos del período de CIS Holding sale «de los cuales comisiones: N» (G12.3), la suma de las líneas de comisión del rango que viene calculada del backend (commissions_total), no de las filas de la página. Con los números de la planilla, 208.
  • Saldo anterior como fila: abre la primera página con orden ascendente y cierra la última con orden descendente; con un rango sin movimientos sale igual (:184-188).
  • Rangos y orden: sin fecha, los últimos 30 días. Por defecto, de lo más antiguo a lo más nuevo, que es como se lee un estado de cuenta. La paginación la hace el backend; el saldo corrido se calcula sobre todo el rango antes de cortar, así que no se rompe entre páginas.
  • Rojos: un saldo negativo va en el rojo del sistema de diseño (alert-danger). Es un dato contable válido, no un error (§1.5 del modelo de saldos).
  • Nada se recalcula en la pantalla y nada del beneficiario se dibuja: de un pago solo hay MTCN, monto y comisión.
  • En el celular cada fila es una tarjeta; desde md, una tabla con el saldo fijo a la derecha.

La secuencia de un pedido, desde que se abre la pestaña hasta que se exporta:

EstadoQué se veCita
Falta elegir"Elegí un PDV para ver su extracto." / "Elegí un país para ver su extracto."ExtractoTesoreria.vue:89,275
Cargando"Cargando..."; si ya había datos se atenúan en lugar de desaparecer:280
ErrorEl mensaje del backend para un 403 o un 422; uno genérico para un 5xx; botón Reintentar:101-107,284-288
Rango sin movimientos"Sin movimientos en este rango." y, con saldo corrido, la fila Saldo anterior igual:403
Extracto parcialAviso azul con el mensaje del backend: se muestran solo los movimientos de algunos países:296
País que paga en moneda localAviso ámbar con el motivo; sin tarjetas de saldo y sin columna Saldo:307
ExportLos botones muestran "Exportando..."; si falla, el error en rojo bajo los filtros:154-166

Una respuesta vieja no pisa a la nueva (:100,118-130): si se cambia de PDV mientras la anterior viajaba, se descarta.


4.5 Reportes - tab Cajas: ruta /reportes/cajas ​

Ruta: /reportes/cajas, tercera tab de la sección Reportes, meta.module = 'reportes' (router/index.ts:102-110). Comparte permiso con Estado de Situación y Volumen: no hay un permiso separado para el reporte de Cajas (ver Hallazgos).

La pantalla tiene dos bloques, cada uno con su propio par de botones de export (frontend/src/views/reportes/CajasView.vue):

Filtros comunes (CajasView.vue:125-157): país (solo si el usuario tiene más de uno), PDV (opcional, default "Todos los PDVs"), y rango desde/hasta con hora. Cambiar cualquier filtro resetea el detalle a la página 1 y recarga los dos bloques (CajasView.vue:67-74).

Resumen — una fila por caja: PDV, Caja N, Saldo actual, Estado (badge Abierta/Cerrada, o Inactiva para una caja que un Admin dio de baja: manda sobre las otras dos y también sale así en el Excel y el PDF), y totales del período: Fondeo, Ajuste, Pagos (cantidad · total) (CajasView.vue:188-227, CajaReportesController::buildResumenRows(), :186-218). Los totales se calculan por movimiento, no por sesión. Las cajas de baja figuran, a diferencia de Saldos: este reporte lee el ledger y su historia no desaparece (GET /reportes/cajas suma active a cada fila). Cierres por día (4.5.1) y los extractos de Tesorería tampoco las filtran.

Detalle — log completo de movimientos de todas las cajas que matchean: Fecha, PDV, Caja, Tipo (con MTCN inline en los pagos), Monto, Usuario. Paginado real con n-pagination (CajasView.vue:250-291) — a diferencia del listado de /caja.

EstadoQué se veCita
Cargando"Cargando..." (reemplaza ambos bloques)CajasView.vue:161
Error"No se pudo cargar el reporte de cajas. Probá de nuevo."CajasView.vue:61,162
Sin país elegidoCaja punteada: "Elegí un país para ver su reporte de cajas."CajasView.vue:163-165
Resumen vacío"Sin cajas en este alcance."CajasView.vue:202-204
Detalle vacío"Sin movimientos en este rango."CajasView.vue:263-265
Error de exportLínea roja arriba de todo, compartida por los cuatro botonesCajasView.vue:159

El detalle no muestra ni filtra por motivo de los movimientos manuales — ni columna en pantalla ni parámetro de filtro en CajaReportesController::resolveScope() (:260-307), aunque el export PDF/Excel de detalle sí incluye una columna "Motivo" (CajaReportesController::detalleExport(), :153,162). Sigue siendo un pendiente real: el catálogo cerrado de motivos (2.3/2.4) habilitó el filtro, pero nadie lo conectó acá — ver Hallazgos.

4.5.1 Pestaña Cierres por día: ruta /reportes/cierres-por-dia ​

Ruta: /reportes/cierres-por-dia, cuarta tab de Reportes, meta.module = 'reportes' — el mismo permiso y el mismo alcance por país y PDV que Cajas (B3.5, ADR-013 §7). Es la vista de lo que el cliente pidió: "control de saldos finales por día". El path es hermano de cajas y no cajas/cierres a propósito: la tab Cajas se marca activa por prefijo y se verían dos tabs seleccionadas.

Filtros (frontend/src/views/reportes/CierresPorDiaView.vue): país (solo si el usuario tiene más de uno), PDV (opcional, "Todos los PDVs") y Desde / Hasta como días, no fecha y hora como en Cajas: el backend cuenta el día de apertura en hora de Guatemala, con los dos extremos inclusivos. Por defecto, la última semana con hoy incluido (el "hoy" es el de Guatemala, no el del navegador). Un "Hasta" anterior a "Desde" se explica en pantalla antes de llegar al 422, y no deja a la vista la tabla del rango anterior ni los botones de exportar; con una de las dos fechas vacía pasa lo mismo y el aviso pide elegir las dos.

Una fila por sesión de caja —cada apertura, en su día de apertura—, ordenada por día, PDV, caja y hora de apertura. Si una caja se abrió más de una vez el mismo día (cambio de turno, R17) salen dos filas, y el saldo final del día de esa caja es el de la última:

ColumnaContenido
FechaDía de apertura (dd/mm/YYYY)
PDV · CajaNombre del PDV y "Caja N"
AperturaHora y quién abrió
Saldo inicialEl heredado del cierre anterior
Fondeos / AjustesSuma con signo de los movimientos de esa sesión
PagosCantidad · total (con signo: resta)
CierreHora y quién cerró; con la fecha si cerró otro día
Saldo finalEl closing_balance; destacado, es la cifra del reporte

Una sesión abierta el lunes y cerrada el miércoles aparece el lunes, con el cierre del miércoles a la vista: el saldo final le corresponde al día que se abrió. Una sesión que todavía no se cerró no tiene saldo final: la columna Cierre dice Sin cerrar · Vencida (ámbar, abierta un día anterior) o Sin cerrar · En curso (azul, abierta hoy) y el Saldo final dice "—". No se inventa un saldo "al momento": el resumen de Cajas ya muestra el actual.

Invariante verificable: el saldo final de un día coincide con el saldo inicial de la sesión siguiente de esa caja, porque la apertura lo hereda (ADR-007 §5). Si no coincidiera, habría un movimiento escrito entre medio —lo que la regla de 2.10 impide—.

Exportar. Exportar Excel y Exportar PDF con los mismos filtros y sin paginar. Las columnas son Fecha, PDV, Caja, Apertura, Saldo inicial, Fondeos, Ajustes, Pagos (cant.), Pagos (total), Cierre y Saldo final; el PDF sale apaisado. Una sesión sin cerrar dice en Cierre Sin cerrar · Vencida o Sin cerrar · En curso, igual que la pantalla, y Sin cerrar en Saldo final. La exportación se audita como REPORT_EXPORTED, igual que las demás de Reportes.

En el celular, cada fila se apila como una tarjeta de pares rótulo/valor, sin scroll horizontal de página: un reporte de nueve columnas obligaba a deslizar para llegar al saldo final. La tabla entra entera desde unos 1280 px. Con cuatro pestañas en Reportes, la fila de pestañas scrollea sola debajo de sm y trae la activa a la vista.

EstadoQué se ve
Cargando"Cargando..."
Error"No se pudo cargar el reporte de cierres. Probá de nuevo."
Sin país disponible"No hay un país disponible para este reporte."
Sin cierres en el rango"No hay cierres de caja en este rango."
Rango inválido"La fecha "Hasta" tiene que ser igual o posterior a "Desde"."
Fecha vacía"Elegí las dos fechas: "Desde" y "Hasta"."
Error de exportLínea roja arriba de la tabla

4.6 Administración - Parámetros - Estaciones / PDV: ruta /admin/ubicaciones/estaciones ​

Ruta: /admin/ubicaciones/estaciones, meta.module = 'abm_estaciones' (router/index.ts). Segunda tab de la sección Parámetros (antes Ubicaciones).

Es el único lugar donde se administran las cajas físicas: se dan de alta, se desactivan y se reactivan (ADR-022). No hay un módulo de permiso propio (P3-15): lo gobierna abm_estaciones, o sea solo Admin; quien solo puede leer ve el mismo panel sin botones de cambio.

La columna «Cajas» de cada fila (EstacionesView.vue):

  • Aparece solo para sucursales cuyo país tiene modulo_caja activo; el resto muestra —.
  • Dice cuántas cajas activas tiene y, aparte, cuántas están de baja: «2 cajas · 1 inactiva», o … mientras carga. El conteo se pide con una request por sucursal elegible (GET /admin/estaciones/{id}/cajas), en paralelo, después del listado principal.
  • Trae el botón Administrar (Ver, sin abm_estaciones:write), que abre el panel, y, con permiso de escritura, el «+ agregar caja» de siempre, que pasa a «Agregando...» mientras corre. Crea la caja con el número siguiente, sin pedir nombre.

El panel «Administrar» (components/AdministrarCajas.vue) es un diálogo con todas las cajas de la sucursal, también las de baja —es el único lugar desde donde se reactivan—, y se pide a la API cada vez que se abre: «quién la tiene abierta» no puede ser el dato de cuando cargó la pantalla.

┌─ Cajas de Mixco Plaza ───────────────────────────────────────────┐
│ Caja 1   ● Activa     Abierta ahora por ana@cislatam.test         │
│                       Para desactivarla, primero hay que cerrarla.│
│ Caja 2   ● Activa                               [ Desactivar ]    │
│ Caja 3   ○ Inactiva                             [ Activar ]       │
│                                                                    │
│ [ + agregar caja ]                                    [ Cerrar ]   │
└──────────────────────────────────────────────────────────────────┘
  • Una caja abierta no ofrece «Desactivar»: dice quién la tiene (opened_by, que trae el listado) y que primero hay que cerrarla. Es lo único que el panel anticipa; todo lo demás lo contesta el backend.
  • Activar y desactivar piden confirmación en la misma fila, no en un segundo diálogo encima: el rechazo que sigue tiene que quedar al lado de la caja de la que habla.
  • Con plata adentro, el 409 CASH_BOX_HAS_BALANCE se muestra con el texto del backend más los cuatro pasos para dejarla en cero (abrirla desde Saldos —la abre un Cajero, un Supervisor o un Admin—, ajuste negativo por todo el saldo con el motivo Retiro por baja de caja, cerrarla, volver acá y desactivarla), y una nota para el caso que esos pasos no resuelven: efectivo en una moneda anterior del país (el ajuste se registra en la moneda vigente), donde hay que pedir soporte. No dice cuánto hay: ese dato no es de quien administra estaciones.
  • El 409 CASH_BOX_HAS_OPEN_SESSION (alguien la abrió con el panel ya abierto) vuelve a pedir la lista, que quedó vieja.
  • Un 422 de validación de Laravel (sin code) no filtra su texto en inglés: dice un mensaje genérico en español.
  • Una sucursal inactiva avisa y deshabilita «+ agregar caja» (el backend daría 422 STATION_INACTIVE).
  • Para teclado y lector de pantalla: el panel se anuncia como diálogo y le pide el foco a «Cerrar»; el resultado («Caja 2 desactivada.») se anuncia en una región role="status", el rechazo es un role="alert" en la fila, y al cerrarse la confirmación el foco vuelve al botón de esa caja; si un 409 refrescó la lista y la fila ya no ofrece el botón, va al aviso de esa fila (o a «Cerrar»).
EstadoComportamiento
Conteo no disponibleFalla en silencio, la celda queda en … para siempre
Alta fallidaEl rechazo sale en el panel (CASH_MODULE_DISABLED, STATION_INACTIVE) o, desde la celda, en el aviso de arriba de la tabla, sin reemplazar el listado: antes un error de una fila hacía desaparecer todas las estaciones
Desactivar una sucursal con una caja abierta o con plata en sus cajas409 STATION_HAS_OPEN_CASH_BOX o STATION_HAS_CASH_BALANCE: el motivo se muestra arriba de la tabla (sin ningún monto). Cambiarle el país con una caja abierta o con plata da los mismos 409, en el aviso del formulario
Activar una caja de una sucursal inactivaLa confirmación dice que queda activa pero no aparece en Saldos ni se puede abrir mientras la sucursal esté inactiva
Sin permiso de escrituraLa celda dice Ver y el panel no trae botones de cambio
Rechazo 403«No tenés permiso para administrar las cajas de este PDV.»

Qué hace cada acción (el detalle del contrato, en 2.7): desactivar y activar llaman a PATCH /admin/estaciones/{id}/cajas/{cajaId} con {active} y dejan CASH_BOX_DEACTIVATED o CASH_BOX_ACTIVATED en Auditoría con el número de la caja y ningún monto; agregar deja CASH_BOX_ADDED. Una caja desactivada deja de verse en Saldos y de poder abrirse, y sigue en Reportes → Cajas marcada Inactiva (4.5).

Activar modulo_caja en el país crea automáticamente la Caja 1 de cada sucursal (CashBoxService::ensureCashBoxesForCountry), y mover una sucursal a un país con módulo Caja también le crea la suya (si no tiene ninguna caja), así que el panel se usa para la segunda caja en adelante, y para dar de baja.


4.7 Administración - Parámetros - Países: ruta /admin/ubicaciones/paises ​

Ruta: /admin/ubicaciones/paises, meta.module = 'abm_paises' (router/index.ts:195-200). Es la pantalla que enciende o apaga el módulo Caja entero para un país, y desde el 2026-08-06 también su moneda de pago.

El formulario lateral expone tres campos relevantes, todos solo en modo edición — un país recién creado nace con modulo_caja apagado (PaisesView.vue:198-227):

CampoControlRegla
modulo_cajaCheckbox "Módulo Caja activo", con texto de ayuda: "Para países sin EPOS (ej. Guatemala) — habilita saldo de caja por sucursal en moneda local, apertura/cierre diario y tipo de cambio. Apagado = comportamiento actual sin cambios."PaisesView.vue:198-207
local_currencyInput de 3 letras (ISO 4217), visible solo si modulo_caja está tildadoPaisesView.vue:208-216
pago_en_moneda_localCheckbox "Pagar en moneda local", visible solo si modulo_caja está tildado. Default apagado (paga en USD)PaisesView.vue:217-227

Validación en el cliente: con el módulo activo, la moneda local es obligatoria y tiene que ser exactamente 3 letras (PaisesView.vue:60-71). Al guardar, local_currency se manda null y pago_en_moneda_local se fuerza a false si el módulo está apagado (:76-82).

Desactivar un país usa ConfirmDialog con aviso de alcance (PaisesView.vue:252-263). Apagar modulo_caja o encender pago_en_moneda_local, en cambio, no piden ninguna confirmación pese a que el segundo cambia la unidad en la que se mueve plata real en todas las sucursales del país — ver Hallazgos. Desde G7 (ADR-022 §5) apagar modulo_caja sí tiene un control, aunque no es una confirmación: el backend lo rechaza (409 COUNTRY_HAS_OPEN_CASH_BOX o COUNTRY_HAS_CASH_BALANCE, con el texto en el formulario) mientras alguna caja de una sucursal activa del país esté abierta o tenga plata adentro, porque esas cajas dejan de verse en Saldos y de poder abrirse.

El texto de ayuda de pago_en_moneda_local implementado es más corto que el propuesto en la versión anterior de este análisis, pero cubre lo mismo: "Apagado, las transacciones se pagan en dólares y no hace falta tipo de cambio. Encendelo solo cuando el país tenga autorización para hacer cambio de divisa — a partir de ahí cada pago se convierte al TC vigente." (PaisesView.vue:222-226).


4.8 Tesorería - Tipo de cambio: ruta /tipo-cambio ​

Ruta: /tipo-cambio (B6; hasta entonces /admin/ubicaciones/tipo-cambio, que ahora redirige), meta.module = 'tipo_cambio'. Módulo de permiso propio, distinto de abm_paises: lo edita Tesorería sin ser Admin (decisión #16 de E4.3 para el Supervisor, que desde B6 solo lo lee y desde G8, 2026-10-07, ya ni lo ve: la ruta y los dos endpoints dan 403 al Cajero y al Supervisor). Vive en el grupo Tesorería del menú, ya no dentro de Ubicaciones («Parámetros»).

  • Selector de país, alimentado por GET /tipo-cambio/paises, que devuelve solo países con modulo_caja activo (TipoCambioView.vue:28-38).
  • "Vigente" arriba a la derecha, e historial completo debajo: Valor / Vigente desde / Cargado por (TipoCambioView.vue:114-141).
  • Con tipo_cambio:write, panel de alta con la leyenda que explica la inmutabilidad (:144-149).
EstadoQué se veCita
Ningún país con Caja"Ningún país tiene el módulo Caja activo todavía — activalo desde la pestaña Países para gestionar su tipo de cambio."TipoCambioView.vue:100-103
Sin TC cargado"Todavía no se cargó un tipo de cambio para este país."TipoCambioView.vue:122-124
Error de carga"No se pudo cargar el tipo de cambio. Probá de nuevo."TipoCambioView.vue:121
Sin permiso de escrituraEl panel de alta no se renderizaTipoCambioView.vue:144
Error de carga de países❌ Sin manejo: loadCountries() no tiene catch, una falla deja la pantalla en el estado "ningún país con Caja activo", que es un mensaje falsoTipoCambioView.vue:28-38

Con pago_en_moneda_local implementado, esta pantalla dejó de ser un prerrequisito para operar en un país que paga en dólares: NO_EXCHANGE_RATE ya no puede dispararse si el país no tiene la bandera encendida (2.8). El texto de la pantalla no lo aclara — sigue siendo la misma redacción de antes de E4b, así que un Admin que la mire hoy no tiene forma de saber si está en uso o es configuración latente para cuando Guatemala consiga la autorización.


Hallazgos para preguntas abiertas ​

Cosas encontradas escribiendo este documento que no resolví acá y conviene llevar a 06-preguntas-abiertas-caja:

  1. El estado vacío de /caja cubre tres causas distintas con un solo mensaje. "No se pudo determinar una caja con módulo Caja activo para tu usuario" (CajaView.vue:363-365) se muestra igual si el país no tiene modulo_caja, si la sucursal no tiene cajas dadas de alta, o si el usuario no tiene sucursales asignadas.
  2. Un error al cargar los movimientos es indistinguible de "no hay movimientos". El catch deja el array vacío sin marcar el error (CajaView.vue:130-138) — el mismo problema que PagoView.vue ya corrigió explícitamente para "Mis transacciones" (PagoView.vue:96-115). Falta aplicar ahí el criterio ya adoptado.
  3. CASH_NOT_OPEN sigue diciendo "esta sucursal" donde el objeto es "esta caja" (CashBoxController.php:236), mientras que CASH_ALREADY_OPEN ya se corrigió a "esta caja" (:140,206). Es la única inconsistencia entre los dos mensajes hoy.
  4. El modal de apertura no muestra la procedencia del saldo heredado (fecha y usuario del cierre anterior) — el texto es genérico, a diferencia de lo que diseñaba 5.6.2. Tampoco distingue la primera apertura de una caja de una apertura normal.
  5. Agregar una caja de más es irreversible desde la UI. — ✅ Resuelto el 2026-10-06 (G7, ADR-022). No había baja ni desactivación de cajas y el botón «+ agregar caja» no pide confirmación (que sigue sin pedirla: agregar no es destructivo, ahora se puede deshacer). Una caja de más se desactiva desde el panel Administrar (4.6) y queda en el historial como Inactiva; lo que no se puede es borrarla ni reutilizar su número, a propósito.
  6. El reporte de Cajas no tiene permiso propio. Comparte reportes con Estado de Situación y Volumen (router/index.ts:107-109), así que cualquiera que vea reportes ve saldos de caja de todas las sucursales de su alcance.
  7. Apagar modulo_caja o encender pago_en_moneda_local no piden confirmación (PaisesView.vue:198-227), a diferencia de desactivar el país entero, que sí (:252-263) — y el efecto del segundo sobre la operatoria diaria (cambia la moneda en la que se mueve plata real) es comparable o mayor.
  8. El motivo en Reportes → Cajas sigue sin filtrarse ni mostrarse en pantalla, pese a que el catálogo cerrado de motivos (2.3/2.4) ya habilita ese filtro en el backend de /caja. El export de detalle sí incluye la columna, la pantalla y el filtro no. Ver 4.5.
  9. "Distribuido en cajas" y "Disponible para distribuir" ya tienen endpoint — CountryPrefundingService::breakdown() — pero el bloque "Circuito de fondos" que conectaría visualmente las tres capas (5.7.4) no se implementó. Los extractos de B7 muestran cada capa como estado de cuenta, pero sigue sin existir ninguna pantalla que muestre Holding → País → Caja de una sola pasada: el circuito completo está dibujado en el análisis (1.10), no en la app.
  10. /pago solo tiene tratamiento de UI para uno de los errores de Caja, la caja vencida (B3). Los otros tres —sin caja abierta, caja de otro país, saldo insuficiente— son hoy el único bloqueo posible de un pago en un país con módulo Caja activo y siguen cayendo en el mensaje genérico (PagoView.vue:167-173). Ver 4.3.2.

← Anterior · Índice · Siguiente: UX de múltiples cajas y fondeo →

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