Skip to content

User Flows ​

Análisis Funcional: Integración Soterex — parte 4 de 8. ← Roles y Permisos · Índice · Siguiente: Diagramas de Actividad →

⚠️ ACTUALIZADO (2026-08-07) ​

Los flujos de esta página son del 2026-07-24, con una corrección del 2026-07-25. Entre medio se entregaron E2 (pantalla Pago), E3 (permisos inline), E4/E4-multi/E4b (módulo Caja y prefondeo en tres capas) y E5a/E5b (datos y documentos del pago). Lo que cambió:

FlujoQué pasó
3.2 PagoReescrito. El Backoffice ya no arranca en el listado de Transacciones, y el saldo que valida el pago dejó de ser el prefondeo
3.3 CancelaciónVigente. Se aclara desde dónde la dispara cada rol y que no toca la caja
3.4 PrefondeoCorregido. Son dos pantallas y tres capas, no un pool por país
3.6 Roles y PermisosCorregido. Dejó de ser una pantalla propia: se edita inline en la ficha del usuario
3.7 Asignación de rolesCorregido. Se mudó a la ficha del usuario
3.8 Búsqueda en PagoNuevo, y afloja a propósito una medida anti-enumeración de E2.1

Los flujos del módulo Caja —apertura, cierre, fondeo, ajuste, alta de cajas, tipo de cambio— no se duplican acá: viven en Flujos de Caja. El detalle del wizard documental vive en Pago con documentos.

⚠️ ACTUALIZADO (2026-10-02, B6 — ADR-014) ​

Hay cuatro perfiles: Cajero, Supervisor, Tesorería y Admin. El Backoffice se llama ahora Cajero (mismo rol, renombrado). Lo que cambia en los flujos de esta página:

FlujoQué pasó
3.1 LoginCae en Pago el Cajero; el Supervisor, Tesorería y el Admin caen en el Dashboard
3.2 PagoLo hace el Cajero, el Supervisor y el Admin (pago·E). Tesorería no tiene la pantalla
3.3 CancelaciónPagar y cancelar dejaron de ser el mismo permiso. Cancela solo el Admin (transacciones·B); el Cajero y el Supervisor pagan pero no cancelan
3.4 PrefondeoYa hay un perfil para esto: Tesorería (y el Admin). El Supervisor no carga prefondeos ni fondea cajas
3.7 AsignaciónEl selector de PDVs no depende del rol: vacío = todos los del país
3.9Nuevo: un flujo por perfil, para ver de un vistazo qué hace cada uno en un día

Los diagramas de las secciones fechadas antes de esta actualización se corrigieron cuando contradecían a B6; el resto conserva los nombres de su época.

Actualizado 2026-10-07 (G8): el tipo de cambio es solo de Tesorería y Admin: el Cajero y el Supervisor ya no lo ven (3.9.1 y 3.9.2), y 3.9.5 resume qué pasa cuando una persona tiene más de un perfil.

3.1 Login (MVP1: solo usuario/password — SSO Google/Microsoft queda para Fase 2) ​

El usuario del sistema es el mail. El login con SSO Google y SSO Microsoft/O365 (el cliente ya usa Microsoft 365 con dominio propio) queda confirmado como Fase 2, fuera del MVP1.

PRECISADO (2026-07-28, decisión #1 del plan v2): el destino después del login no se decide por nombre de rol. El guard recorre el sitemap en orden de prioridad y manda al usuario a la primera ruta cuyo módulo puede Leer (firstAllowedRoute(), frontend/src/router/index.ts). Que el Cajero (el Backoffice de antes) caiga en Pago es consecuencia de que tiene dashboard:read = false y de que pago va antes que transacciones en esa lista, no de un caso especial escrito para ese rol. Si no puede leer nada, cae en /sin-acceso.

3.2 Flujo core — el Cajero paga una transacción ​

⚠️ REESCRITO (2026-08-07). La versión anterior arrancaba en "Backoffice entra a Listado de Transacciones" y validaba el pago contra el saldo de prefondeo del país. Las dos cosas dejaron de ser ciertas:

  1. El Backoffice (hoy Cajero) no tiene el listado de Transacciones. Entra por la pantalla Pago y encuentra la transacción buscándola (3.8), no eligiéndola de una bolsa que ve entera. La bolsa compartida por país sigue existiendo conceptualmente —cualquier operador del país puede resolver cualquier ACCEPTED— pero se accede de a una, por búsqueda. Decisión #1 del plan v2.
  2. El prefondeo dejó de bloquear el pago en países con módulo Caja: la única validación de saldo es la caja del operador (ADR-007 §2).

Lo que no cambió y sigue vigente de la corrección del 2026-07-25: el PDV no viene con la transacción, se asigna recién al resolverla, y hay re-chequeo de estado con lock justo antes de confirmar (ver §2.4).

Lo que hay que retener de este flujo, porque es donde más se equivoca la intuición:

  • La comisión no aparece en ninguna parte de la pantalla. Ni en la ficha, ni en el modal de confirmación, ni en el error de saldo — el error de prefondeo omite a propósito el monto requerido, porque restándolo del monto visible se deduciría la comisión (§2.5).
  • De qué caja sale la plata lo decide quién paga, no el PDV. Cada pago descuenta la caja que ese mismo operador abrió a su nombre. Detalle en Flujos de Caja §2.5.
  • Todo pasa en una sola transacción de base de datos. Si la caja no alcanza, no queda ni movimiento ni transacción pagada.
  • El medio de pago es siempre efectivo (G3, 2026-10-05). Antes de esta entrega la pantalla ofrecía también Transferencia bancaria y el pago descontaba la caja igual, como si fuera efectivo (RV3-13): el diagrama no mostraba el medio porque, en los hechos, no cambiaba ningún camino de plata. Hoy el backend rechaza cualquier otro medio con un 422 antes de bloquear la fila y de tocar la caja, y por eso todo PAGO de caja es efectivo. Detalle en Preguntas Abiertas del pago, #3.
  • Quién puede pagar (B6): el que tiene pago·E —Cajero, Supervisor y Admin—. Tesorería no tiene la pantalla. El Admin paga como cualquiera: necesita una caja abierta a su nombre en un país con módulo Caja. Antes lo decidía transacciones·E, el mismo permiso que cancelar.
  • Ningún saldo se guarda: los tres se derivan de su ledger. Por eso el diagrama dice "se recalculan solos" y no "se descuentan".

3.3 Flujo — Cancelación bidireccional ​

Actualizado 2026-07-25: re-chequeo de estado + PDV asignado recién acá.

PRECISADO (2026-08-07): el flujo en sí no cambió, pero sí desde dónde se dispara y qué no toca. El Backoffice cancela desde la ficha de la pantalla Pago, no desde un detalle de transacción que ya no ve; Supervisor y Admin siguen cancelando desde /transacciones/:id. Los dos pegan al mismo endpoint, gateado por transacciones:write.

CORREGIDO (2026-10-02, B6, P5 y P6): cancelar dejó de ser transacciones·E y exige transacciones·B, que hoy tiene solo el Admin. El botón «Cancelar transacción» aparece, en la ficha de Pago y en el Detalle, solo para quien tiene ese permiso; el Cajero y el Supervisor pagan pero no cancelan (403 por API, aunque armen el pedido a mano). Un Cajero que se equivocó de transacción tiene que pedírselo a un Admin. Pagar, en cambio, sigue en pago·E.

Una aclaración que vale porque se pregunta seguido:

  • Cancelar no toca ninguna caja ni ningún prefondeo. Los saldos se derivan de las transacciones PAID; una CANCELLED nunca entró en la cuenta, así que no hay nada que devolver.

CORREGIDO (2026-09-30, ADR-012): el diagrama original tenía un paso "WebApp llama al Cancel API de Soterex" que no existe — es al revés: Soterex es quien llama a nuestro Cancel, nunca CIS al de ellos. Cuando cancela un humano (hoy, solo un Admin), CIS cancela localmente y listo — no hay ninguna llamada de red saliente en ese momento, solo el Notification posterior. La rama "Soterex quiere cancelar" (antes "mecanismo a definir", pregunta #2b) ya no es un caso aparte: es la misma transacción pasando por el mismo endpoint Cancel, solo que quien llama es Soterex en vez de un humano desde la UI — con la validación extra de que el transaction_id/token sean del mismo ApiClient que hizo el SendRequest original.

3.4 Flujo — Se carga prefondeo ​

⚠️ ACTUALIZADO (2026-10-02, B6): el flujo no cambia, pero sí quién lo hace. Hay un perfil Tesorería (y el Admin): el Supervisor ya no carga prefondeos ni fondea cajas, solo ve las de su PDV. Los diagramas y las notas de abajo ya dicen Tesorería; las menciones al «rol Supervisor» que siguen tachadas son las de la versión de agosto.

⚠️ CORREGIDO (2026-08-05, ADR-007). El flujo original era uno solo: "Supervisor entra a Prefondeo, completa país, monto y fecha, y el sistema suma al saldo pool del país". Hoy hay dos pantallas y tres capas, y una de las tres —la caja— no se carga por acá sino con un fondeo.

Además, el campo "fecha" nunca existió: el asiento se graba con la fecha del momento de la carga y no es editable. Contradicción documentación↔código que ya venía anotada en el paquete del módulo Caja y que sigue sin resolverse.

  • Quién carga qué: ni la Holding ni el País tienen un rol propio. Los carga tesorería (Teresa y Diego, de CIS-EC) operando con rol Supervisor o Admin — se decidió explícitamente no crear un rol "Tesorería" (Carlos, 2026-08-06). CORREGIDO (2026-10-02): desde B6 existe el perfil Tesorería (ADR-014): carga la Holding y el País y fondea las cajas (prefondeo·E, prefondeo_pais·E, fondeo_caja·E), igual que el Admin. El pedido del cliente del 2026-10-01 fue explícito: el Supervisor ve las cajas de su PDV pero no las fondea. Quien hoy hace tesorería con rol Supervisor pierde esos accesos al desplegar B6 hasta que se le asigne Tesorería.
  • CIS EC administra la caja de CIS GT (confirmado 2026-08-07): quien carga el prefondeo de Guatemala es un usuario de Ecuador con alcance sobre ese país.
  • El ejemplo numérico completo de cómo se mueve la plata entre las tres capas está en Modelo de saldos.

3.5 Flujo — Admin gestiona un ABM (patrón genérico: Países / Usuarios / Estaciones / Configuración) ​

PRECISADO (2026-08-07): el patrón sigue siendo este, pero dos ABMs ganaron efectos laterales que no son "guardar un registro" y conviene tener presentes:

  • ABM Países: activar el módulo Caja exige tener moneda local configurada (si no, error) y crea automáticamente la Caja 1 de cada sucursal del país que todavía no tenga ninguna. El campo % comisión ya no existe; en su lugar están el flag de módulo Caja, la moneda local y la bandera de moneda de pago.
  • ABM Estaciones/PDV: dar de alta una sucursal en un país con módulo Caja crea su Caja 1. Desde la ficha del PDV se agregan cajas adicionales, numeradas solas. Desde G7 (2026-10-06) también se desactivan y reactivan, pero no se borran (ADR-022): el panel «Administrar» de la celda «Cajas» las lista todas.

Ver Flujos de Caja §2.7.

3.6 Flujo — Admin edita los permisos de un usuario ​

⚠️ CORREGIDO (2026-07-28, E3.1 del plan v2). El flujo original era "Admin entra a ABM Roles y Permisos y ve una grilla Módulo × Rol × L/E/B". Esa pantalla ya no existe: los permisos se editan inline en la ficha del usuario, sobre los roles que ese usuario ya tiene asignados. El permiso abm_roles_permisos sigue siendo el gate, y la dependencia Borrar→Escribir sigue vigente tal cual se definió.

  • El cambio sigue siendo por rol, no por usuario individual: editar la matriz desde la ficha de Ana afecta a todos los usuarios que compartan ese rol. La ficha es el lugar desde donde se edita, no el alcance de lo editado. Vale decirlo porque la UI invita a leerlo al revés.
  • El guardado es atómico: usuario y permisos, o ninguno de los dos.

3.7 Flujo — Admin asigna roles multipaís / multi-PDV a un usuario ​

ACTUALIZADO (2026-10-02, B6): el selector de PDVs ya no depende del rol. En la ficha el campo se llama «PDVs (vacío = todos)» para cualquier rol, y «PDV activo» sirve para el que paga: el Cajero y el Supervisor lo necesitan si tienen más de un PDV; Tesorería, que no paga ni cancela, no. El Admin y Tesorería se asignan normalmente sin PDVs (todos los del país). Los roles asignables son los cuatro.

⚠️ CORREGIDO (2026-07-28, E3 del plan v2). El flujo es el mismo, pero cambió de lugar: ya no hay una pantalla "ABM Asignación de Roles" donde se busca un usuario por mail. Las asignaciones se editan en la sección "Roles y Asignaciones" de la ficha del usuario, dentro de Usuarios y Accesos. La solapa que hoy se llama "Roles" pasó a contener propiedades del rol (el timeout de sesión), no asignaciones.

El PDV activo (role_assignments.default_station_id) es lo que resuelve qué sucursal se graba cuando el usuario paga o cancela teniendo más de un PDV asignado — ver Pregunta Abierta #14. (Desde G2.2 y G4, 2026-10-06, ADR-020: quien paga con dos o más PDV y sin PDV activo no puede subir el primer documento ni pagar, salvo que, en un país con módulo Caja, tenga una caja abierta —el PDV del pago es entonces el de esa caja—. La ficha de usuario lo anticipa con un aviso ámbar «Sin PDV activo», que no impide guardar.)

3.8 Flujo — Búsqueda en la pantalla Pago (NUEVO) ​

Actualizado (B1, 2026-10-02): hoy la pantalla Pago busca solo por MTCN; el nombre ya no se consulta (avisa «Ingresá un MTCN», y se audita igual). La búsqueda parcial por nombre sigue en el listado de Reporte individual (antes Transacciones), que además de B6 solo ve completo el Supervisor y el Admin. El diagrama y la tabla de abajo conservan el diseño del 2026-08-07, con la rama del nombre, para poder ver qué se aflojó y qué se volvió a ajustar.

Actualizado (G9.5, 2026-10-07, H3-05): el buscador acepta además el MTCN con el prefijo de la carta, C-5436014032, porque es lo que el operador copia y pega. Es una sola C (mayúscula o minúscula) seguida de al menos un guion o espacio, y solo vale si lo que sigue son dígitos (con guiones o espacios entre ellos): se descarta antes de comparar, y lo demás sigue siendo «Ingresá un MTCN» (C, C-, Carlos, C-abc, CC-123, C5436014032). No agrega consultas ni cambia el throttle de 10 por minuto ni la auditoría de cada intento, y el intento inválido sigue sin guardar lo tipeado. El filtro del Reporte individual hace lo mismo, también solo delante de dígitos: un apellido «C-Ruiz» no se toca. La regla vive en App\Support\MtcnBusqueda y se repite a propósito en frontend/src/utils/mtcn.ts; los dos tests repiten la misma tabla de casos.

El Cajero (el Backoffice de antes) no tiene un listado de la bolsa del país: tiene un buscador. Todo lo que hace arranca acá.

⚠️ Esto afloja a propósito una medida de seguridad de E2.1 — dejarlo dicho importa más que la prolijidad del flujo. El diseño original hizo la búsqueda exacta justamente como medida anti-enumeración: había que acertar el MTCN completo con sus ceros a la izquierda, o el nombre y apellido enteros. En uso real resultó impracticable — la carta que tiene el operador delante muestra el MTCN sin ceros y el nombre como lo escribió Soterex, y cualquier diferencia de tilde, segundo nombre o apellido compuesto devolvía cero resultados sin explicar por qué.

Los tres cambios del 2026-08-07 (pedido de Carlos) y lo que cuesta cada uno:

CambioAntesAhoraQué se pierde
NombreExacto, nombre y apellidoParcial, nombre o apellido, mínimo 3 letrasBuscar "rodriguez" devuelve una lista, no un acierto
MTCNExacto, con ceros a la izquierdaComparación numérica — "26" encuentra "0000000026"Se puede barrer el rango de MTCN de a uno
AlcanceACCEPTED del país + solo las PAID/CANCELLED propiasTodo el país, resueltas por quien seaUn operador puede mapear el padrón de beneficiarios de su país

El alcance se amplió porque el material de CIS-EC pide expresamente que, ante una transacción ya pagada, el operador corrobore los soportes del pago para eliminar posibilidades de error — y eso es imposible si solo ve las propias, porque el pago que hay que corroborar casi siempre lo hizo otro.

Qué defensas quedan en pie: el throttle de 10 búsquedas por minuto con bucket propio, la auditoría de todo intento (incluidos los que no devuelven nada, que es la señal que detecta un barrido), el acotamiento por país, el mínimo de 3 caracteres, y que el resultado no expone documento, email, teléfono, fecha de nacimiento ni comisión.

Esto queda explícitamente marcado como el punto más fuerte a revisar en la auditoría de seguridad (E6). Es una decisión de negocio consciente y fechada, no un descuido.

3.9 Flujo — El día de cada perfil (NUEVO, B6) ​

Cuatro perfiles, cuatro recorridos. Resumen de lo que ya está en el resto de este documento y en Roles y Permisos, pensado para leerlo de corrido. Lo que no está en el diagrama de un perfil es porque no puede hacerlo, y el backend lo rechaza aunque alguien arme el pedido a mano.

3.9.1 Cajero (el Backoffice de antes) ​

Opera una ventanilla: busca, completa, paga y cuida su caja. No ve la bolsa entera del país, ni Reportes, ni Auditoría, ni el Tipo de cambio (desde G8: para pagar no lo necesita, el pago toma por su cuenta el vigente). Su menú de trabajo tiene tres ítems —Pago, Reporte individual y Saldos—, más la Documentación.

Dos reglas que lo condicionan: la caja opera solo el día en que se abrió (ADR-013) —si quedó abierta de ayer no paga hasta cerrarla y abrirla de nuevo— y no se puede cerrar mientras falte subir la papeleta firmada de un pago de la sesión (C2).

3.9.2 Supervisor ​

Hace lo mismo que el Cajero sobre su PDV, y además ve lo que pasa en las cajas y en los reportes. No mueve plata.

No ve Prefondeo Soterex, ni la pestaña País de Fondeo PDVs ni los extractos de la Holding (403 por API); de Fondeo PDVs ve solo la pestaña PDV, con los extractos de sus PDVs. No edita el tipo de cambio (lo lee) No ve el tipo de cambio (desde G8, 2026-10-07) y no ve Auditoría ni el reporte de Cumplimiento.

3.9.3 Tesorería (perfil nuevo) ​

Mueve la plata entre la Holding, los países y las cajas. No ve Pago ni el Reporte individual: no opera transacciones.

Fondear no descuenta el prefondeo del país: es distribución banco a cajón, no gasto (ver 3.4 y Modelo de saldos).

3.9.4 Admin ​

Todo lo de los otros tres perfiles, más lo que solo él puede: cancelar, administrar y auditar.

Un Cajero que se equivocó de transacción llega acá: el Admin la cancela. Y quien hoy hace tesorería con el rol Supervisor llega a Tesorería: hay que asignarle el rol nuevo (ver ADR-014, Consequences).

3.9.5 Una persona con más de un perfil ​

Los cuatro recorridos de arriba son los de una persona con un perfil. Con más de uno se mezclan las opciones: el menú es la suma de los menús de cada asignación, los datos y las acciones se deciden país por país, y no hay selector de perfil (decisión D3-T2, 2026-10-04). Cae en la primera pantalla que alguno de sus perfiles puede leer, así que solo un Cajero sin otro perfil cae en Pago. Dos casos que se preguntan seguido:

  • Cajero y Admin en el mismo país: el menú es el del Admin, sin mezcla visible (el Admin ya incluye todo lo del Cajero).
  • Cajero y Tesorería en el mismo país: paga, y además puede fondear y ajustar la caja con la que paga; no se vuelve Supervisor (ve solo lo que pagó y no cierra la caja de otro). Es la combinación a evitar: la regla y el resto de las combinaciones sensibles están en Roles y Permisos, 2.3.2 y en ADR-014 §6.

Hallazgos ​

Cosas que aparecieron al contrastar estos flujos contra el código, y que no resolví acá porque no las cubre ninguna decisión documentada.

  1. ✅ RESUELTO (B6 lo verificó el 2026-10-02): un usuario que solo tenga prefondeo_pais no puede entrar a ningún lado. firstAllowedRoute() ya lista prefondeo-pais (y todas las rutas con módulo, incluidas las cinco pestañas de Reportes), y admin-roles-permisos salió de la lista. Un test cubre que cada uno de los cuatro perfiles cae en una pantalla que puede ver. El texto original, por el rastro: la lista de prioridad del guard (firstAllowedRoute(), frontend/src/router/index.ts) no incluye prefondeo-pais: un usuario cuyo único módulo legible sea ese cae en /sin-acceso aunque la pantalla exista y él tenga permiso. Con el seed actual no se da (quien tiene prefondeo_pais tiene también Dashboard), pero es una bomba de tiempo para cualquier rol nuevo o recortado. La misma lista sigue nombrando admin-roles-permisos, que es una ruta que ya no existe.
  2. El asiento de prefondeo no acepta fecha, en ninguna de las dos capas, pese a que el flujo 3.4 original la pedía. Ya venía anotado en el paquete del módulo Caja; sigue igual.
  3. El motivo de cancelación es texto libre y no tiene código de Soterex asociado. Los motivos "de fábrica" coinciden con los sub_status que define Soterex (1000/1001/1002), pero un motivo nuevo escrito por el usuario no mapea a ninguno. CORREGIDO (2026-09-30, ADR-012): sigue sin resolver, pero cambia dónde importa — ya no es para llamar a un "Cancel API real" de Soterex (ese endpoint no existe del lado de CIS llamando afuera), sino para el campo sub_status que pide el payload de Notifications al avisarle a Soterex que una transacción quedó CANCELLED. Con el modelo nuevo, cuando cancela Soterex el sub_status lo manda él en el Cancel entrante y CIS solo lo guarda; el hueco real es únicamente para las cancelaciones que inicia un humano de CIS.

← Roles y Permisos · Índice · Siguiente: Diagramas de Actividad →

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