Secuencias de Pantalla
Análisis Funcional: Integración Soterex — parte 6 de 8. ← Diagramas de Actividad · Índice · Siguiente: Preguntas Abiertas →
⚠️ ACTUALIZADO (2026-08-07)
La lista original (2026-07-24) era de rutas propuestas. Varias nunca existieron con ese path y otras cambiaron de contenido. Lo que sigue son las rutas reales (
frontend/src/router/index.ts), con el permiso que las gatea y qué se hace en cada una. Al final está el mapeo ruta vieja → ruta real, para poder rastrear enlaces de documentos anteriores.Las rutas que nunca existieron tal como se propusieron:
/transacciones/nuevo,/prefondeo/nuevo(el alta es un modal en la misma pantalla),/admin/roles-permisos(desapareció con E3),/admin/asignacion-roles(se mudó a la ficha del usuario),/reportes/dashboard(es/reportes/volumen).Actualizado 2026-10-02 (B2): el Estado de Situación (
/reportes/situacion) ganó la columna Balance final. Se actualizó su fila en la tabla 5.2 y se agregó la secuencia del cálculo en 5.6.Actualizado 2026-10-02 (B4): el reporte de Cumplimiento (módulo
reporte_cumplimiento, solo Admin) exporta un Excel de 36 columnas, desde la pestaña nueva/reportes/cumplimiento(fila de la tabla 5.2). Cómo se arma y qué lo protege está en 5.7.Actualizado 2026-10-06 (ajustes v3, G4.3 a G4.5): el Reporte individual (
/transacciones) ganó la columna Procesada por (la novena, también en el Excel y en la ficha) y la columna PDV deja de mostrar un guion: dice por qué la transacción no tiene PDV. El Excel pasó a llamarsereporte-individual-…. Qué dice cada texto y cómo se arma está en 5.9.
Actualizado 2026-10-02 (B6, ADR-014): cuatro perfiles (Cajero, Supervisor, Tesorería y Admin; el Cajero es el Backoffice de antes) y un menú nuevo. Las tablas 5.2 y 5.3 se reordenaron por grupo del menú (Caja, Tesorería, Reportes, Administración) y los nombres de pantalla son los de ahora: Reporte individual (Transacciones), Saldos (Caja), Prefondeo Soterex (Prefondeo Holding), Fondeo PDVs (Prefondeo País) y Parámetros (Ubicaciones). Tipo de cambio pasó a Tesorería, con ruta propia (
/tipo-cambio), y Auditoría pasó a Administración y es solo del Admin. Pagar y cancelar dejaron de ser el mismo permiso: ver 5.8. Las rutas no cambiaron, salvo la de Tipo de cambio.
Actualizado 2026-10-07 (G8, ADR-014): el tipo de cambio es solo de Tesorería y Admin (el Cajero y el Supervisor reciben 403 y no ven el ítem); 5.1.1 explica qué decide cada capa cuando una persona tiene más de una asignación (se mezclan las opciones, no hay selector de perfil); y 5.6.6 dice quién ve el nombre del beneficiario en el Estado de Situación y de dónde sale el selector de país de Reportes.
5.1 Acceso
| Ruta | Permiso | Qué pasa |
|---|---|---|
/login | pública | Usuario/password (usuario = mail). SSO Google/Microsoft es Fase 2 |
/sin-acceso | pública | Destino de un usuario autenticado que no puede Leer ningún módulo |
| — | — | Tras el login, el guard manda a la primera ruta legible en orden de sitemap: el Cajero cae en /pago; el Supervisor, Tesorería y el Admin en / |
5.1.1 Una persona con más de una asignación: qué decide cada capa
Una persona puede tener varias asignaciones (país + rol + PDVs). Sus permisos son la suma de todas, país por país, y no hay selector de perfil (decisión D3-T2; el porqué está en ADR-014 §6 y la tabla de quién decidió qué, en Roles y Permisos, 2.3.1). El diagrama sigue a alguien con Cajero en Guatemala y Tesorería en El Salvador:
Dos consecuencias que conviene tener a mano. El menú puede ofrecer una pantalla que en un país da 403: el menú es la unión, el permiso es por país, y por eso cada pantalla con selector de país ofrece solo los países donde su permiso rige (H3-02). Y sumar asignaciones no convierte a nadie en Supervisor: Cajero más Tesorería no cierra la caja de otro ni ve las transacciones de todos; Cajero de un PDV más Supervisor de otro lo es solo en el segundo para los saldos y el cierre, aunque el Reporte individual une los alcances de PDV de las dos.
5.2 Caja, Tesorería y Reportes
Los grupos del menú que no son de Administración. Entre paréntesis, cómo se llamaba la pantalla antes de B6.
| Ruta | Permiso | Qué pasa |
|---|---|---|
/ | dashboard:read | General. Dashboard con KPIs, variación vs. ayer, serie diaria de 30 días, volumen por semana de las últimas 8 y ranking de PDVs. El Cajero no lo tiene. La comisión generada la ve quien tiene prefondeo:read (Tesorería y Admin), no el Supervisor |
/pago | pago:read | Caja → Pago. Entrada del Cajero. Buscador solo por MTCN (desde B1; hasta 15 resultados — ver User Flows §3.8); ficha del resultado con datos del pago, soportes documentales y la acción Pagar (pago:write: Cajero, Supervisor y Admin). Cancelar aparece solo para quien tiene transacciones:delete, hoy el Admin; panel «Mis transacciones» con lo que resolvió el propio usuario en los últimos 30 días. 📋 Pendiente: mostrar acá el saldo de la caja y el estado de la sesión cuando el país tiene módulo Caja — se diseñó y no se implementó, así que hoy el operador tiene que ir a /caja para saber con cuánto cuenta |
/transacciones | transacciones:read | Caja → Reporte individual (antes Transacciones). Listado. ACCEPTED: bolsa compartida por país, sin filtro de PDV (todavía no lo tienen). PAID/CANCELLED: filtrables por PDV, país y fecha. El Cajero ve solo lo que resolvió él (A5.1) y Tesorería no la tiene. Nueve columnas: la última, Procesada por, dice quién la resolvió, y la columna PDV dice por qué falta cuando falta (en vez de un guion); el Excel (reporte-individual-AAAAMMDD-HHMM.xlsx) trae las mismas nueve — ver 5.9 |
/transacciones/:id | transacciones:read | Detalle: datos, monto, MTCN, estado, historial. Nunca la comisión. Pagar (pago:write) y Cancelar (transacciones:delete, solo Admin) con re-chequeo de estado justo antes de confirmar; si otro usuario ya la resolvió, 409 + refresco. Al confirmar se graba PDV + usuario. Suma la sección «Documentación del pago» con los soportes y la papeleta ✅. En «Datos de la transacción», el renglón Procesada por (salvo en una ACCEPTED) y el PDV con el mismo rótulo que el listado |
/caja | caja:read | Caja → Saldos (antes Caja). Selector de caja si hay más de una; apertura y cierre (apertura_cierre_caja:write); fondeo y ajuste (fondeo_caja:write: Tesorería y Admin); movimientos con MTCN y TC, exportables. El Supervisor y Tesorería ven los saldos de todas las cajas de su alcance (fondeo_caja:read); el Cajero, solo el de la que él abrió. Una caja abierta de un día anterior queda vencida y solo se puede cerrar. Detalle completo en Secuencias de Pantalla de Caja |
/prefondeo | prefondeo:read / write | Tesorería → Prefondeo Soterex (antes Prefondeo Holding): tarjeta Saldo con Soterex en USD (descuenta principal + comisión; suma todos los países, o solo los del usuario si no los lee todos y entonces lo dice: «Saldo de la Holding — de sus países», G12), alta de asiento con referencia opcional (solo con write) y dos pestañas de extracto con saldo corrido, rango de fechas, orden y export a Excel y PDF: Soterex ↔ CIS Holding y CIS Holding. Solo Tesorería y Admin. Ver Caja, 4.4 |
/prefondeo-pais | prefondeo_pais:read / write o fondeo_caja:read | Tesorería → Fondeo PDVs (antes Prefondeo País). Pestaña País (prefondeo_pais): saldo por país en USD, con el desglose distribuido en cajas / disponible para distribuir cuando el país tiene módulo Caja, el alta de asiento y el extracto del país, cuyo saldo corrido es el disponible. Descuenta solo principales y puede quedar negativo. Pestaña PDV (fondeo_caja): el extracto de un PDV, dentro del alcance de la asignación. Se entra con cualquiera de los dos permisos y cada pestaña aparece con el suyo: el Supervisor ve solo la de PDV. Ver Caja, 4.4 |
/tipo-cambio | tipo_cambio | Tesorería → Tipo de cambio (antes una pestaña de Ubicaciones, en /admin/ubicaciones/tipo-cambio, que ahora redirige). TC vigente por país + historial inmutable. GET /tipo-cambio/{país} y /tipo-cambio/paises), no ven el ítem y no entran por la URL. Solo lista países con módulo Caja activo |
/reportes/situacion | reportes:read | Reportes. Estado de situación contable: todos los tipos de movimiento + resumen por request. Exportable a Excel y PDF con membrete, filtrable por PDV. Cada fila trae el Balance final (saldo de prefondeo del país después de esa operación) y el listado cierra con la fila Saldo anterior; con un PDV elegido o con acceso acotado a PDVs la columna no se muestra y la pantalla dice por qué — ver 5.6. Lo ven Supervisor, Tesorería y Admin, no el Cajero. El selector de país ofrece solo los países donde la persona tiene reportes:read, y el nombre del beneficiario sale según 5.6.6 |
/reportes/volumen | reportes:read | Volumen y comparativas: pagados por rango de fecha, por PDV y por país; país vs. país; PDV vs. varios PDVs; ranking de PDVs; totalizadores |
/reportes/cajas | reportes:read | Reporte de Cajas: resumen por caja + detalle de movimientos, ambos exportables |
/reportes/cierres-por-dia | reportes:read | Cierres por día: una fila por apertura de caja, en su día de apertura, con el saldo final (las sesiones sin cerrar salen como tales). Exportable a Excel y PDF. Ver Caja, 4.5.1 |
/reportes/cumplimiento | reporte_cumplimiento:read | Cumplimiento (B4): no es reportes:read. Formulario de filtros —país, fechas, estado— y un botón que baja el Excel de 36 columnas con los datos de los beneficiarios. Sin vista previa: la pantalla no muestra ningún dato. Solo Admin por defecto. Ver 5.7 |
5.3 Administración
Todo el grupo es del Admin (B6): ningún otro perfil tiene los ABMs ni Auditoría.
| Ruta | Permiso | Qué pasa |
|---|---|---|
/admin/usuarios-accesos/usuarios | abm_usuarios | ABM Usuarios (incluye mail de notificación, con más de un mail por usuario/estación). Desde acá se editan inline los permisos L/E/B de sus roles (gate abm_roles_permisos) y sus asignaciones país + rol + PDVs, con el PDV activo. La ficha lista los 19 módulos de la matriz —la lista viene del backend, GET /admin/roles-permisos—, y los cuatro roles son asignables |
/admin/usuarios-accesos/asignacion-roles | abm_asignacion_roles | Solapa «Roles»: propiedades del rol, hoy el timeout de sesión. Ya no es donde se asignan roles a usuarios, pese al nombre de la ruta |
/admin/ubicaciones/paises | abm_paises | Parámetros → Países (Parámetros se llamaba Ubicaciones). Incluye el flag del módulo Caja, la moneda local, la moneda de pago y el formato de recibo. Ya no incluye % comisión — el campo se eliminó |
/admin/ubicaciones/estaciones | abm_estaciones | Parámetros → Estaciones / PDV. Identificador: código interno de sucursal, más nombre, país, dirección, provincia y ciudad (combos dependientes sobre los catálogos del país del PDV, opcionales; las usa el reporte de Cumplimiento y el recibo en hoja A4), responsable y mail(es) de notificación. Muestra la cantidad de cajas activas de cada PDV («N cajas · M inactivas») y abre un panel «Administrar» para agregar, desactivar y reactivar cajas (G7, ADR-022) |
/admin/ubicaciones/catalogos | abm_catalogos | Parámetros → Catálogos. Las listas de los combos del pago (tipo de identificación, provincias, ciudades, países) |
/admin/configuracion | abm_configuracion | Timeout de sesión global + configuración de la integración Soterex (modo mock o real, credenciales, test de conexión) |
/admin/auditoria | auditoria:read | Auditoría (antes en «Operación»). Logs de movimientos y logins, con multi-select de acciones y export PDF. Solo el Admin (el Cajero y el Supervisor la perdieron en B6); no tiene ninguna ruta de escritura. Registra también los cambios de perfiles que hizo la migración de B6 (ROLE_RENAMED_BY_MIGRATION, ROLE_CREATED_BY_MIGRATION, ROLE_PERMISSION_CHANGED_BY_MIGRATION, ROLE_PERMISSION_GRANTED_BY_MIGRATION), sin usuario porque los hizo el deploy |
Nota sobre el redirect de
/admin/ubicaciones: es dinámico, no fijo: lleva a la primera pestaña que el usuario puede leer (Países, Estaciones o Catálogos), y lo resuelve incluso si la URL se carga directo (F5), cuando los permisos todavía no cargaron. Antes tenía que tener en cuenta que el Supervisor llegaba a Tipo de cambio por ahí; con B6 el tipo de cambio salió de esa sección y ya no es motivo.
5.4 Documentación
Sin módulo de permiso: visible para cualquier usuario autenticado.
| Ruta | Qué pasa |
|---|---|
| Funcional | Enlace externo al sitio VitePress de doc/ — este mismo documento |
/documentacion/manual-usuario | Manual del usuario embebido en la app |
| Referencia de API | Portal Scalar, abierto vía SSO para no pedir credenciales de nuevo |
5.5 Mapeo ruta original → ruta real
| Ruta propuesta el 2026-07-24 | Hoy | Por qué |
|---|---|---|
/dashboard | / | Es la raíz de la SPA |
/transacciones, /transacciones/:id | igual | Sin cambios de path. El menú las llama Reporte individual (B6); el Cajero ve solo lo que resolvió |
| — | /pago | Nueva (E2): entrada del Backoffice, hoy Cajero |
/prefondeo, /prefondeo/nuevo | /prefondeo + /prefondeo-pais | Se partió en dos capas (ADR-007); el alta nunca fue una ruta aparte, es un modal |
| — | /caja | Nueva (E4): módulo Caja |
/reportes/situacion | igual | Ganó export Excel/PDF, filtro por PDV y la columna Balance final con la fila Saldo anterior (B2, 5.6) |
/reportes/dashboard | /reportes/volumen | Cambió de nombre; se le sumó /reportes/cajas |
| — | /reportes/cumplimiento | Nueva (B4): reporte de Cumplimiento, con permiso propio |
/admin/usuarios | /admin/usuarios-accesos/usuarios | Se agrupó en una sección con solapas; absorbió permisos y asignaciones |
/admin/paises | /admin/ubicaciones/paises | Ídem, bajo «Ubicaciones» (hoy «Parámetros» en el menú; el path no cambió) |
/admin/estaciones | /admin/ubicaciones/estaciones | Ídem |
| — | /admin/ubicaciones/tipo-cambio → /tipo-cambio | Nueva (E4.1) como pestaña de Ubicaciones. Movida en B6 a una ruta propia del grupo Tesorería; la URL vieja redirige |
/admin/configuracion | igual | Absorbió la configuración de la integración Soterex |
/admin/auditoria | igual | Sin cambios de path. En el menú pasó de «Operación» a Administración y es solo del Admin (B6) |
/admin/roles-permisos | eliminada | Los permisos se editan inline en la ficha del usuario (E3) |
/admin/asignacion-roles | reutilizada con otro contenido | El path sobrevive como solapa "Roles" (propiedades del rol); las asignaciones se mudaron a la ficha del usuario |
5.6 Estado de situación: cómo se arma el Balance final
Ajuste v2 del cliente (Guatemala), entrega B2, decisión C10: "Cada línea debe traer el saldo final luego de dicha operación (balance final), como columna final del reporte". Plan en Ajustes v2 del cliente GT.
/reportes/situacion listaba movimientos (transacciones y asientos de prefondeo) sin ningún saldo. Ahora cada fila lleva balance_after: el saldo de prefondeo del país que quedó después de esa operación. El saldo se deriva del ledger cada vez que se consulta y nunca se guarda (ADR-005, ADR-007).
5.6.1 Qué saldo es y cuánto mueve cada fila
Es el saldo de la capa Holding atribuible al país: el mismo de la tarjeta Saldo actual de la pantalla. No es el de Prefondeo País (que descuenta solo el principal) ni el de una caja: los tres siguen siendo números distintos, como fija el ADR-007.
| Fila | Efecto sobre el Balance final |
|---|---|
| Asiento de prefondeo | Suma el monto |
Transacción PAID | Resta monto + comisión |
Transacción ACCEPTED | Cero: repite el saldo de la fila anterior en el tiempo |
Transacción CANCELLED | Cero: ídem |
La fecha de cada fila es la que ya mostraba la pantalla: created_at para un asiento y last_updated_at para una transacción (para una PAID, el momento del pago; no existe paid_at).
5.6.2 Orden determinístico
El corrido se calcula en orden cronológico, de lo más viejo a lo más nuevo, con desempate total: fecha, después el asiento antes que la transacción, y por último el id. Antes la lista solo ordenaba por fecha, y como la base guarda segundos, dos movimientos del mismo segundo quedaban en un orden indefinido; con un saldo corrido eso cambia los números de la fila. El asiento va primero para que un crédito del mismo instante nunca deje un saldo transitorio negativo.
La pantalla y los exports muestran el inverso exacto de ese orden (lo más nuevo arriba), no un segundo ordenamiento que pudiera desempatar distinto.
5.6.3 Saldo anterior y paginación
El corrido arranca del saldo anterior: el saldo del país justo antes de Desde (00:00 de ese día), calculado con los mismos criterios de fecha que la lista y con el borde excluyente (<) contra el >= del rango, así que ningún movimiento queda contado dos veces ni sin contar en el límite. Se muestra en la tarjeta del resumen y como última fila de la última página (lo cronológicamente primero cierra una lista que tiene lo más nuevo arriba), también cuando el período no tiene movimientos.
El Balance final se calcula sobre todo el rango y recién después se corta la página: calcularlo sobre la página daría saldos que parecen bien y están mal. Por eso una fila muestra el mismo saldo en la página 1 y en la 9. Cierre del rango: el Balance final de la fila más nueva es el saldo a Hasta; coincide con la tarjeta Saldo actual cuando Hasta es hoy.
5.6.4 Cuándo no hay columna
El corrido solo reconcilia si están todos los movimientos que mueven el saldo del país. La API lo dice en running_balance (available, reason, message) y la pantalla muestra el message tal cual, como texto visible y no como tooltip (en una tablet no se ve).
| Quién consulta | available | reason | Columna y fila Saldo anterior | Tarjeta Saldo anterior |
|---|---|---|---|---|
| Acceso a todos los PDVs del país, sin PDV elegido | true | — | Sí | Sí |
| Acceso a todos los PDVs, con un PDV elegido | false | STATION_FILTER | No: aviso | Sí (es un hecho del país, como Saldo actual) |
| Acceso limitado a algunos PDVs | false | STATION_SCOPE | No: aviso | No |
Con un PDV elegido, el filtro deja afuera los asientos (no tienen PDV) y los pagos de los demás PDVs. Con acceso limitado, el usuario ve solo los pagos de sus PDVs, así que su corrido tampoco cierra. A ese usuario no se le informa el saldo anterior: sin la columna no tiene un punto de partida que mostrar, y es un dato del país entero que no hace falta darle a quien ve una parte. Esto no es un aislamiento: summary.balance (Saldo actual) y summary.prefunding_total (Prefondeo cargado) ya eran del país completo antes de B2 y siguen yendo a ese usuario, de modo que con ellos puede estimar cuánto se pagó en total. Si el cliente quiere ocultarle esos totales de país, es una decisión de producto aparte. Un usuario acotado que además elige un PDV recibe STATION_FILTER. En todos los casos sin corrido, balance_after viaja null en cada fila.
5.6.5 Un solo cálculo para pantalla, Excel y PDF
El listado y los exports comparten el mismo armado de datos, así que la columna y la disponibilidad son idénticas en los tres. En el Excel y el PDF el Balance final es una columna más (el Excel lo escribe como texto con el formato USD 1,234.56, igual que el resto) y la fila Saldo anterior va al final, porque lo más nuevo está arriba y ese es el dato más viejo. Sin corrido, el export no trae ni la columna ni la fila.
El cálculo vive en un servicio de saldo corrido (RunningBalance: filas ordenadas + saldo de apertura + efecto con signo de cada fila → las mismas filas con balance_after). No ordena, no pagina y no decide si el saldo corresponde mostrarse: eso lo resuelve quien lo llama. Está pensado para que los cuatro extractos de tesorería (B7) lo reusen con sus propias reglas de efecto. Suma en centavos enteros para no arrastrar la deriva de punto flotante de una fila a la siguiente.
5.6.6 Quién ve el nombre del beneficiario, y qué países ofrece Reportes
Dos reglas del Estado de Situación que salen de la mezcla de perfiles (D3-T2, G8):
- El nombre del beneficiario (
beneficiary) viaja solo a quien es Supervisor o Admin del PDV del pago:PermissionService::stationIdsWhereAssignmentHolds($user, $countryId, SUPERVISOR_DE_TRANSACCIONES), la misma capacidad que usa el listado (fondeo_caja·L más acceso a transacciones) evaluada dentro de una misma asignación y por PDV:nulles todos los PDVs,[]ninguno, y la bolsa compartida (ACCEPTED, sin PDV) cuenta para quien supervisa alguno. Lo reciben el Supervisor y el Admin; a Tesorería le lleganullen la pantalla y en el Excel y el PDF, y también a quien suma Cajero y Tesorería en el país, y a un Supervisor de un PDV que además es Tesorería le llega solo en los pagos de su PDV (revisión de G8: Reportes le abre todo el país, el nombre no).Antes se decidía con, y esa combinación recibía el nombre de todos los pagos solo por sumar los permisos de dos asignaciones (H3-01). La comisión y el saldo de prefondeo no se acotan acá: Reportes es donde esos datos deben verse.allows(transacciones:read)sobre la unión de las asignaciones - El selector de país de Estado de Situación, Volumen y Cajas (y el del Reporte individual) ofrece solo los países donde rige el permiso de esa pantalla:
countriesWithAccess('reportes')ycountriesWithAccess('transacciones'). Antes ofrecían los países de cualquier asignación, y con Cajero en Guatemala y Tesorería en El Salvador la primera carga pedía Guatemala y daba 403 (H3-02).
Los dos son tests de caracterización (PerfilesAccesoApiTest::test_cajero_mas_tesoreria_no_lee_el_nombre_del_beneficiario_en_el_estado_de_situacion y test_supervisor_de_un_pdv_mas_tesoreria_lee_el_nombre_solo_de_los_pagos_de_su_pdv; SituacionView.spec.ts, CajasView.spec.ts, VolumenView.spec.ts y TransaccionesView.spec.ts para el selector).
5.7 Reporte de Cumplimiento: cómo se arma el Excel y qué lo protege
Ajuste v2 del cliente (Guatemala), entrega B4, decisiones C11 y P7. Plan en Ajustes v2 del cliente GT.
El cliente hoy arma a mano una planilla (Request Pilot List) para su regulador. El reporte la genera: 36 columnas con los nombres y el orden de esa planilla. Es un solo endpoint de descarga, GET /reportes/cumplimiento/export, y no existe una vista previa: el reporte vuelca nombre, fecha de nacimiento, nacionalidad, documento, teléfono, mail y dirección de todos los beneficiarios de un país, así que en bloque solo salen por este archivo, que tiene permiso propio y queda auditado. Ningún endpoint del reporte devuelve esos datos en JSON, y el listado de Transacciones es una lista blanca sin datos personales (TransactionListResource). La ficha de una transacción sí trae la fila completa a quien tiene lectura de Transacciones sobre ese país y PDV —como ya pasaba con el documento—: bajar los datos de muchas personas exige este archivo o abrir las fichas de a una.
Filtros. País (obligatorio, y tiene que ser uno donde el usuario tenga el permiso), rango por fecha de creación de la transacción (inclusivo de los dos días enteros, ambos extremos opcionales) y estado (ACCEPTED pendiente, PAID pagada, CANCELLED cancelada; sin estado, todos). Solo Excel.
La pantalla. Es un formulario y un botón; el aviso fijo de arriba dice que el archivo contiene datos personales de los beneficiarios y que cada descarga queda auditada.
| Tema | Regla |
|---|---|
| Quién la ve | La pestaña se dibuja solo con reporte_cumplimiento:read y la ruta la bloquea el guard por el mismo módulo. El ítem "Reportes" del menú y de la barra del celular aparece con ese permiso o con reportes; para quien tiene solo el primero, /reportes lo lleva directo a Cumplimiento |
| País | Obligatorio y siempre visible, aun con uno solo (acota datos personales). Solo se ofrecen los países donde el usuario tiene este permiso, no cualquiera donde tenga una asignación |
| Fechas | Arrancan en el mes en curso (día 1 a hoy, hora de la app), para que por defecto no salgan más datos de los necesarios. "Quitar fechas" deja el rango abierto; cada extremo es opcional. Un "Hasta" anterior a "Desde" lo avisa la pantalla y deshabilita el botón, antes de llegar al 422 del backend |
| Resumen | Dice país, fechas y estados en palabras antes de descargar ("sin límite de fechas" si el rango está abierto) |
| Descarga | Un botón; "Descargando…" mientras tanto y sin doble clic. Al terminar confirma; cambiar cualquier filtro saca la confirmación o el error anteriores |
| Errores | 422 del tope, con el mensaje del backend tal cual (ya viene redactado: dice el tope y qué acotar). 429, que hay que esperar un minuto. 403, el mensaje del backend. Cualquier otro fallo, un aviso genérico. Nunca el texto en inglés de Laravel |
| Nombre del archivo | reporte-cumplimiento-<ISO>-AAAAMMDD-HHMM.xlsx. Si el navegador no puede leer el nombre que manda el backend (la API en otro origen), la pantalla arma el mismo |
Lo que decide cada celda y no está en la tabla del plan:
| Tema | Regla |
|---|---|
| Celda sin dato | Vacía, nunca "—": el reporte lo lee un regulador y una raya no es un dato |
| Montos (14, 15, 26, 27) | Número, con formato de monto. Todo lo demás es texto, incluidos el MTCN y el documento (conservan los ceros a la izquierda) |
| Fechas (3, 19, 28, 31) y horas (20, 32) | Texto d/m/Y y H:i:s, en la zona horaria de la app. Texto y no fecha de Excel a propósito: la fecha de nacimiento no tiene edad máxima validada y un año tipeado de más (1085) se vería como #### |
| Etiquetas (7, 8, 10, 11, 34, 35) | La etiqueta del catálogo del país de la transacción, también si el ítem está desactivado. Un valor viejo en texto libre que no coincide con ningún código sale tal cual |
| Teléfono y mail (5, 13) | El dato adicional primero y, si no hay (o está en blanco), el original |
| Tipo de entrega (16) | Cash o Bank transfer; vacío mientras la transacción no tiene el dato cargado |
| Total con comisión (15) | Principal más comisión. Revela la comisión de cada pago, que es información restringida (la ve quien tiene prefondeo:read): quien reciba reporte_cumplimiento la ve en este reporte aunque no tenga ese permiso. Hoy solo Admin tiene los dos; darle el permiso a otro perfil es una celda de la matriz, y esta consecuencia viene con ella |
| Moneda, tipo de cambio y monto destino (25–27) | Si hay movimiento de caja del pago: su moneda, su tipo de cambio congelado (1 si se pagó en dólares, sin conversión) y su monto en positivo (el ledger lo guarda como salida). Sin movimiento y país que paga en USD: USD, 1 y el principal. Sin movimiento y país que paga en moneda local: la moneda, y tipo de cambio y monto vacíos (el principal está en dólares y ponerlo bajo otra moneda sería un dato falso) |
| Pendiente o cancelada (25–27) | No tienen movimiento: rige la misma regla del país |
| MTCN y PIN (21 y 22) | El MTCN lleva el prefijo C- (cumplimiento.mtcn_prefix, variable CUMPLIMIENTO_MTCN_PREFIX; vacía lo apaga y sale el número crudo); el PIN va sin él, como en la carta de Soterex. Es solo la celda del reporte: no cambia el almacenamiento, la API, los recibos ni los extractos (G9.3, D3-18) |
| Notas adicionales (30) | Siempre vacía (G9.2: el cliente la pidió en blanco). Se mantiene el encabezado. El servicio ya no lee audit_logs para este reporte, y el motivo de una cancelación queda solo en Auditoría (solo Admin, evento Cambio de estado de transacción, campo motivo): la ficha de la transacción no lo muestra |
| Fecha y hora de pago (31, 32) | La de la última actualización, solo si está pagada |
| Agencia (33 a 36) | Solo las pagadas. Son "Paid at Branch", dónde se pagó: una pendiente puede tener PDV (lo toma con el primer documento que sube el cajero, ADR-008) y una cancelada por un usuario también (el de quien cancela), y ninguna se pagó ahí. Una pagada vieja sin PDV sale con las cuatro vacías, y un PDV sin provincia ni ciudad (B4.1) con esas dos vacías. Lectura del product owner: ver la pregunta 13 de preguntas abiertas del pago con documentos |
| 23, 24, 29 y 30 | Eran la lectura del product owner de cómo el cliente llena hoy esas cuatro a mano. El cliente contestó el 2026-10-02: la entidad pagadora (24) es por país, un mapa por ISO en config/cumplimiento.php (payer_names, hoy GT = «CIS Guatemala»; un país sin entrada sale vacío y no se inventa), y las notas (30) van siempre en blanco. No se tocan hasta que conteste QC-19 y QC-20: Transaction Status (23) sigue siendo Sent (su mail dice «Send») y Transaction Status - Update (29) sigue en inglés (ellos lo escribieron en español). Ver la pregunta 13 de preguntas abiertas del pago con documentos |
Qué protege el archivo:
- Permiso propio (
reporte_cumplimiento, solo lectura, solo Admin). Tener el permiso general de Reportes no alcanza. - El alcance está en la consulta, no solo en el parámetro: un usuario acotado a PDVs recibe solo las transacciones de esos PDVs, y una pendiente sin PDV (que no se puede atribuir a ninguno) no le llega. Distinto del listado de Transacciones, donde la pendiente es una bolsa compartida del país.
- Tope de filas: el menor entre el general de exports y uno propio de este reporte (hoy 1000), porque 36 columnas pesan mucho más en memoria que las 8 de los otros exports. Se pasa del tope: 422
EXPORT_TOO_LARGEcon la indicación de acotar el rango o el estado, nunca un archivo truncado. - Límite de descargas: 10 por minuto por usuario (middleware
throttle.user). No es elthrottlede Laravel por IP: la app no usa el guard de Laravel, así que ese firma por IP, y detrás del balanceador todos los usuarios compartirían un único cupo (un Admin dejaría sin descarga a otro). Pasado el límite: 429. - Sin caché: la respuesta lleva
Cache-Control: no-store. El nombre del archivo es el país y el momento (reporte-cumplimiento-GT-20261002-1530.xlsx), nada del contenido. - Celdas que parecen fórmulas (
=,+,-,@) salen siempre como texto. - Auditoría (
REPORT_EXPORTED, tiporeporte_cumplimiento): quién, país, rango, estado y cantidad de filas. Nunca el contenido —ni un nombre, ni un documento, ni un MTCN— y no queda atada a una transacción puntual. Se registra antes de generar el archivo, así que un fallo al armarlo no deja un archivo con datos personales sin rastro. - El intento fuera de alcance también queda: pedir un país que no es del usuario (la pantalla no lo ofrece, así que es un pedido armado a mano) responde 403 y registra
REPORT_EXPORT_DENIEDcon quién y el id pedido, nada más. La respuesta es la misma para un país ajeno que para uno inexistente.
5.8 Pagar y cancelar: qué comprueba cada capa
Ajuste v2 del cliente (Guatemala), entrega B6, decisiones P5 y P6, y ADR-014. Hasta B6 pagar y cancelar eran el mismo permiso (
transacciones:write). Ahora son dos, y la regla se valida en tres lugares: el botón es una comodidad, el backend manda.
| Acción | Ruta del API | Permiso | Quién lo tiene hoy |
|---|---|---|---|
| Buscar en Pago | GET /pago/buscar | pago:read | Cajero, Supervisor, Admin |
| Cargar los datos del pago, subir y ver soportes | PATCH .../datos-pago, POST/GET .../documentos | transacciones:write | Cajero, Supervisor, Admin. Con la tx resuelta, subir lo que falta lo hace además solo quien la pagó, el Supervisor del PDV o el Admin (G5) |
| Reemplazar un soporte ya cargado | POST .../documentos (ya hay uno de ese tipo) | transacciones:write y, con la tx resuelta, ser Supervisor del PDV en una misma asignación | Con la ACCEPTED, el Cajero; con la pagada o cancelada, solo el Supervisor del PDV y el Admin (G5) |
| Pagar | PATCH /transacciones/{id}/pay | pago:write | Cajero, Supervisor, Admin |
| Cancelar | PATCH /transacciones/{id}/cancel | transacciones:delete | Admin |
| Cancelación que pide Soterex | POST /api/c2p/v1/Cancel | autenticación de máquina (OAuth) | No pasa por estos permisos (ADR-012) |
Quién ve los soportes y la papeleta de lo que se pagó. Pagar se acota por país; los soportes, la papeleta y los datos del pago de una transacción ya resuelta, además, se acotan por PDV. Desde G2.1 (2026-10-06) hay una sola excepción: quien la pagó o la canceló entra a esa transacción aunque su PDV sea otro, siempre después del permiso por país (PermissionService::isResolverOf()). Cualquier otra persona de otro PDV recibe 404 y la pantalla le dice que se pagó en otro punto de venta, sin ofrecerle la papeleta. Ver Pago con documentos, §1.6.
Tesorería no tiene ninguno de los dos módulos: ni abre una transacción, ni busca en Pago, ni sube soportes. Las restricciones se prueban por API con un usuario real de cada perfil (PerfilesAccesoApiTest), no solo mirando que el botón no esté.
Una comprobación más, que no es de permisos (G3, 2026-10-05). El medio de pago es solo efectivo: pay() y datos-pago responden 422 con errors.delivery_type («El medio de pago solo puede ser efectivo.») si mandan TRANSFERENCIA u otro valor, y lo hacen antes de bloquear la fila y de tocar la caja. Corre después de los permisos y del alcance por país, y se prueba también por API: la pantalla ya no ofrece la opción, pero eso es una comodidad. Ver Preguntas Abiertas del pago, #3.
Subir un soporte y reemplazarlo: qué comprueba cada capa (G5, 2026-10-06)
Ajuste v2 del cliente (Guatemala), ítems 2, 3, 6 y 8 de la hoja, y la actualización G5 del ADR-011. El backend distingue subir un tipo que falta de reemplazar uno ya cargado: la pantalla ofrece Subir o Reemplazar según
puede_subirypuede_reemplazar, pero el que manda es el backend, con un código distinto para cada rechazo.
- Puede subir (
canManageTransactionDocuments): con laACCEPTED, cualquiera contransacciones:writeen el país; con la pagada o cancelada, quien la resolvió, el Supervisor con alcance sobre el PDV y el Admin. - Puede reemplazar (
canReplaceTransactionDocuments): con laACCEPTED, igual que subir; con la pagada o cancelada, solo el Supervisor con alcance sobre el PDV y el Admin. Quien la pagó queda afuera: sube la papeleta firmada que falta (y cierra la caja), pero no pisa lo ya cargado. - «Supervisor con alcance» es
fondeo_caja:readmástransacciones:writeen una misma asignación que cubra el PDV de la tx (PermissionService::assignmentHolds). Juntar capacidades de asignaciones distintas no alcanza. - El rechazo de quien no ve la transacción es 404 y el de quien la ve pero no puede es 403: así el 404 no confirma que exista.
- La subida es atómica (G1, ADR-019): escribir el archivo, crear su fila, fijar el PDV con el primer documento y dejar la constancia de Auditoría van en una sola transacción de base de datos. Si el almacenamiento falla, el pedido responde 503
DOCUMENT_STORAGE_UNAVAILABLE(sin el detalle del SDK, que trae el bucket) y no queda nada: ni fila, ni PDV asignado, ni constancia. Lo que no escribe nada se resuelve antes: el 404, los dos 403, el 422 de archivo inválido y el 422ACTIVE_STATION_REQUIRED. - Lo prueban
DocumentosReemplazoApiTestyPermissionServiceTransactionScopeTest, por API con un usuario real de cada perfil, no solo mirando que el botón no esté.
5.9 Reporte individual: quién procesó cada transacción y por qué no tiene PDV
Ajustes v3 del cliente (Guatemala), entrega G4 (G4.3 a G4.5), pedidos RV3-15, RV3-16 y RV3-17 del plan. El cliente pidió dos cosas sobre el listado y su Excel: una columna con el usuario que procesó la transacción, y que ninguna fila muestre el PDV como un guion pelado.
5.9.1 Qué dice «Procesada por»
Un solo texto por fila, siempre un string, que sale igual en el listado, en la ficha y en el Excel:
| La transacción está… | «Procesada por» dice | Por qué |
|---|---|---|
PAID | El correo de quien la pagó | Es el único dato de la persona que guarda el sistema (users no tiene nombre y apellido) |
CANCELLED por una persona de CIS | El correo de quien la canceló | Hoy solo el Admin cancela (5.8); antes de B6 también lo hacía el Cajero |
CANCELLED por el Cancel de Soterex | Soterex (API) | La cancelación llegó por la API de entrada (ADR-012); no hay persona de CIS |
CANCELLED por el vencimiento del MTCN | Sistema | La canceló el proceso c2p:expire; tampoco hay persona, pero no fue Soterex |
ACCEPTED | (vacío) | Todavía no la resolvió nadie |
PAID sin operador grabado (dato de demo o anterior a que se grabara) | (vacío) | La API solo puede cancelar: atribuirle un pago a Soterex sería falso |
El plan de ajustes v3 daba la API de Soterex como único camino sin persona hacia CANCELLED. No lo es: el vencimiento del MTCN (plan de alineación al contrato C2P, D7) también cancela sin usuario. Llamarlo «Soterex (API)» diría algo falso, así que tiene su propio texto, «Sistema», el mismo que ya usa el historial de la ficha.
Decisión de la entrega, sin confirmar. Los textos «Sistema» (esta columna) y «Cancelada por vencimiento del MTCN» (la columna PDV, 5.9.2) no están en el plan: salen de que el vencimiento existe y no es Soterex. El cliente los va a ver en su Excel, así que se confirman junto con QC-10 (la columna «Procesada por»). Si Carlos prefiere la regla literal del plan (toda
CANCELLEDsin persona dice «Soterex (API)»), el cambio es una línea enProcesadaPor::etiqueta()y el test del vencimiento.
Cómo se distingue la API del sistema. La fila de la transacción no lo dice (resolved_by_user_id es null en los dos casos). Lo dice el asiento de Auditoría de la cancelación: sin usuario ni cliente de la API y con origin: system es el vencimiento; cualquier otro es el Cancel de Soterex. Es el mismo criterio que usa el historial de la ficha, y se calcula con una consulta por cada mil transacciones del listado (ninguna si no hay canceladas sin persona), no una por fila. Esa consulta busca en audit_logs por transaction_id, que tiene índice desde esta entrega (en PostgreSQL una clave foránea no lo trae sola).
«Soterex (API)» es lo que queda por descarte. Una CANCELLED sin persona cuyo asiento no dice origin: system se atribuye a Soterex, sin pedir una marca positiva de la API: es la regla que fijó el plan (G4.3), y en la aplicación el único camino que cancela sin persona y sin ese asiento es el Cancel de Soterex. El límite: una CANCELLED anterior a que se grabara quién la cancelaba, de demo, o a la que se le borró a mano la fila del usuario que la canceló (la aplicación no tiene baja de usuarios; resolved_by_user_id queda en null), también dice «Soterex (API)». Una PAID en ese caso queda vacía, porque la API solo puede cancelar. Pedir la marca positiva exigiría un tercer estado («cancelada, no se sabe por quién») con un texto nuevo para el cliente, y eso no se decidió.
5.9.2 Qué dice la columna PDV cuando no hay PDV
Con PDV, la columna dice su nombre, sea cual sea el estado. Sin PDV dice por qué, con los mismos textos en la pantalla (listado y ficha) y en el Excel:
| La transacción está… | La columna PDV dice |
|---|---|
ACCEPTED | Sin asignar (bolsa del país): todavía no tiene PDV, se lo da quien la resuelve |
CANCELLED por el Cancel de Soterex | Cancelada por Soterex: nadie de CIS la canceló, así que no hay PDV que atribuir |
CANCELLED por el vencimiento del MTCN | Cancelada por vencimiento del MTCN |
PAID, o CANCELLED por una persona de CIS | Sin PDV asignado: el hueco de datos de RV3-17 (alcance ambiguo del que resolvió, datos viejos o de demo) |
Los textos de «cancelada por…» salen de comparar «Procesada por» con «Soterex (API)» o «Sistema»: la API no expone ninguna otra marca. Los textos los arman dos módulos, uno por lado (utils/pdvDeLaTransaccion.ts en el frontend y App\Support\PdvDeLaTransaccion en el backend, para el Excel), con un test de cada uno que fija el texto: si cambia uno, cambia el otro.
Qué no resuelve esto. Esta entrega (G4b) solo muestra mejor el hueco. Que el PDV de un pago sea el de la caja que pagó es el otro pedido de RV3-17 y lo resuelve G4a (ADR-020): una
PAIDnueva en un país con módulo Caja ya trae el PDV de la caja de la que salió la plata, y las históricas se completan desde su movimiento de cajaPAGOcon una migración de datos del deploy. «Sin PDV asignado» queda para lo que eso no alcanza: un pago de un país sin módulo Caja hecho con un alcance sin acotar (Admin), y los datos viejos o de demo sin movimiento de caja.
5.9.3 El Excel
GET /transacciones/export (path y nombre de ruta sin cambios) descarga reporte-individual-AAAAMMDD-HHMM.xlsx; antes se llamaba transacciones-…. Trae nueve columnas: MTCN, Beneficiario, Estado, País, PDV, Monto, Creada, Última actualización y, al final, Procesada por. Se agregó al final a propósito: el cliente ya usa las otras ocho por su posición.
Se arma con las mismas reglas que el listado: los mismos filtros, el mismo orden (con un desempate por id para que las filas empatadas no cambien de lugar entre la pantalla y el archivo) y el mismo alcance. Ordenar por «Procesada por» ordena por el correo; las filas sin persona quedan juntas. El tope de filas y la etiqueta de Auditoría («Exportación de transacciones») no cambiaron.
5.9.4 Quién ve el correo del operador
El correo de quien procesó es dato del operador, no del beneficiario: la regla de ADR-016 (los datos personales en bloque salen solo por Cumplimiento) no lo alcanza. Pero el listado es una lista blanca y el campo se agregó a propósito (ADR-016, Actualización G4.3): sale solo procesada_por, el texto, nunca la relación con el usuario.
- Alcance: no cambia. Quien ve una transacción ve quién la procesó. El Cajero ve solo lo que resolvió él, así que en su listado la columna trae siempre su propio correo; el Supervisor y el Admin ven el de cada operador de su alcance. Tesorería no tiene la pantalla.
- Auditoría: el correo no se copia a la metadata del evento de la exportación (que guarda los filtros y la cantidad de filas).
- Ficha, pagar y cancelar: el mismo texto, sin la relación
resolved_by.
Decisión por defecto, sin respuesta del cliente todavía (QC-10 del plan): alcanza con el correo. Si el cliente quiere el nombre y apellido de la persona, hay que agregarlos al usuario (hoy
userssolo tiene el mail), y es un cambio de datos, no de pantalla.
← Diagramas de Actividad · Índice · Siguiente: Preguntas Abiertas →

