Resumen del alcance

Análisis Funcional: Integración Soterex — parte 1 de 8. Índice · Siguiente: Sitemap →

⚠️ ACTUALIZADO (2026-08-07)

Este documento es del 2026-07-24. Entre esa fecha y hoy se entregaron E1, E2, E3, E4, E4-multi y E4b, y quedó implementado (sin mergear todavía) E5a/E5b. Varias afirmaciones del texto original quedaron falsas, no incompletas: la papeleta estaba fuera de alcance y hoy está adentro, la comisión era editable por CIS y hoy no lo es, el prefondeo era un pool por país y hoy son tres capas.

Lo que cambió está marcado abajo con CORREGIDO o NUEVO, con la fecha de la decisión que lo cambió y su fuente. Lo que no está marcado sigue vigente tal cual se escribió el 2026-07-24.

Estado de cada cosa, con el mismo criterio que usa el paquete del módulo Caja:

Marca	Significa
✅	Está en main y funciona así hoy
📋	Decidido, todavía sin implementar

La web app reemplaza el proceso manual de carga vía Excel/Google Sheet que hoy ejecuta CIS LATAM (marca "Zoom" en otros países) para procesar las transacciones que envía el aliado Soterex.

• Reemplaza: carga manual de Excel, macro generadora de MTCN, cálculo manual de comisión y descuento de prefondeo.

• CORREGIDO (2026-07-28, decisiones #9 y #15 del plan v2):No reemplaza el flujo de papeleta/comprobante de pago (queda fuera de alcance). La papeleta sí entra en el alcance: el sistema la genera membretada, en formato térmico de 58 mm, con el monto en USD y en moneda local, adjunta a la ficha de la transacción y reimprimible. Junto con ella entraron los soportes documentales del pago (carta firmada, scan de identificación, foto opcional) y los datos que completa el operador. Todo eso vive en su propio paquete funcional — ver "Paquetes que complementan a este" más abajo. ✅

• No reemplaza el sistema EPOS (mal referenciado como "hipos" en la charla) — no hay integración con EPOS en esta etapa. NUEVO (2026-07-28, decisión #2 del plan v2): para los países que no tienen EPOS (el caso concreto es Guatemala), la app incorporó un módulo Caja propio que controla el efectivo del punto de venta. Es opcional por país: apagado, la app se comporta exactamente como antes de que existiera. ✅

• La integración con Soterex es bidireccional:

  • WebApp → Soterex: la WebApp llama a tokenC2P (auth) y luego a SendRequest mediante un cron cada 30 minutos para tomar las transacciones pendientes registradas por Soterex y generarles el MTCN.
  • WebApp → Soterex: Cancel — cuando Backoffice cancela desde la webapp, esta llama al endpoint Cancel de Soterex.
  • WebApp → Soterex: Notifications (webhook consumido por Soterex) para informar el MTCN generado y los cambios de estado (ACCEPTED, CANCELLED, PAID).
  • ⚠️ Falta definir cómo llega a la WebApp una cancelación iniciada por Soterex (ver Pregunta Abierta #2 revisada), dado que todos los endpoints salientes confirmados son WebApp → Soterex. Sigue abierta al 2026-08-07 — es lo único bloqueante que queda del análisis original.

• Lanzamiento inicial: Guatemala, con diseño preparado para escalar a más países (ABM de Países). ✅

• CORREGIDO (2026-07-31, ADR-005):La comisión CIS es editable por país. La comisión no la fija CIS: la calcula y la devuelve Soterex, granular por transacción (fee en la respuesta de SendRequest). El campo commission_pct de ABM Países se eliminó — nunca estuvo conectado con el fee real. Además es información restringida desde el 2026-07-25: no aparece en ninguna pantalla operativa, solo en Reportes y en el Dashboard del Supervisor (ver §2.5 de Roles y Permisos). ✅

  El material de CIS-EC del 2026-08-07 pide lo contrario —una tabla de tramos editable por país—. Carlos decidió el mismo día mantener ADR-005 y no implementar el motor de comisiones hasta que CIS-EC confirme que el fee de la API es el valor bueno. Es una divergencia consciente con el cliente, no un olvido.

• CORREGIDO (2026-08-05, ADR-007):El saldo de prefondeo es un pool por país (no por PDV individual). El contrato nuevo mete a la Holding entre Soterex y el país, así que el prefondeo pasó a tener tres capas: ✅

  1. Prefondeo Holding — global, en USD. Es el pool que ya existía; descuenta principal + comisión. Es la capa que ve Soterex.
  2. Prefondeo País — por país, en USD. Descuenta solo principales y admite saldo negativo a propósito: es lo que tesorería concilia contra el extracto bancario del país.
  3. Caja operativa — por caja de PDV, en la moneda de pago del país. Solo en países con el módulo Caja activo.

  Mover plata del país a una caja no descuenta el prefondeo del país: es distribución banco→cajón, no gasto. El detalle completo, con el ejemplo numérico que validó el cliente, está en Modelo de saldos.

• NUEVO (2026-08-05, ADR-007 §2): con módulo Caja activo, la única validación de saldo del pago es la caja del operador — la plata del cajón manda. Los países sin módulo Caja (Ecuador, que opera con su EPOS) siguen validando, ahora contra el Prefondeo País. ✅

• NUEVO (2026-08-05, ADR-007 §6): la moneda de pago es configurable por país. Guatemala no tiene autorización para hacer cambio de divisa, así que paga en dólares y no se le exige tipo de cambio vigente. El módulo de TC queda entero, listo para cuando llegue la autorización. El cambio de moneda propiamente dicho quedó diferido a MVP2 por confirmación escrita de CIS-EC (2026-08-07). ✅

• NUEVO (2026-07-28, decisión #1 del plan v2): el rol Backoffice dejó de entrar por el listado de Transacciones. Su punto de entrada es la pantalla "Pago", un buscador acotado del que sale toda su operación. Backoffice tiene transacciones:read = false a propósito (y write = true, porque pagar y cancelar pegan a los mismos endpoints). Tampoco ve el Dashboard. Ver Sitemap y User Flows §3.2. ✅

• NUEVO (2026-08-07, revisado el 2026-08-10): el PIN de pago que imprime la carta del beneficiario es el MTCN. Se implementó una verificación y se sacó al probarla: buscando por número de transacción, pedía retipear lo que el operador acababa de tipear. Ver Pago con documentos §1.2. Cancelar tampoco cerrar la transacción. ✅

• Autenticación MVP1: solo usuario/contraseña (usuario = mail). El cliente ya usa Microsoft 365 con dominio propio, pero el SSO (Google y Microsoft) queda para una fase posterior, no para el MVP1. ✅

• Modelo de roles multipaís: un mismo usuario puede tener roles distintos en distintos países (ej: Admin en Guatemala y Supervisor en otro país), y un Supervisor puede estar a cargo de más de un PDV. Toda esta asignación debe ser editable (ver Matriz de Roles y Permisos). ✅

• NUEVO (2026-08-07, confirmado con Teresa Ortiz): CIS EC administra la caja de CIS GT. Guatemala no opera su propia tesorería. Eso significa que hay usuarios de Ecuador con alcance sobre los saldos de Guatemala, cosa que el modelo multipaís de arriba ya soporta sin cambios.

• Todo el proceso debe quedar con log completo y trazabilidad (transacciones, cambios de estado, movimientos y logins). ✅

Paquetes que complementan a este

Este análisis siguió siendo el tronco, pero dos módulos crecieron lo suficiente como para necesitar su propio paquete funcional. No duplican lo de acá: lo profundizan.

Paquete	Qué cubre	Por qué está aparte
Módulo Caja	Saldo por caja, apertura y cierre, fondeo, ajuste, múltiples cajas por sucursal, tipo de cambio, y las tres capas de prefondeo con su ejemplo numérico	Cuando se escribió este análisis el módulo no existía ni estaba pedido
Pago con documentos	El pago en ventanilla: datos que completa el operador, soportes documentales y papeleta térmica	Es el detalle de E5a/E5b; acá queda solo el flujo de alto nivel

Qué queda fuera del alcance, hoy

Lista corta de cosas que están pedidas o sugeridas por el cliente y deliberadamente no se construyeron — para que no se lean como olvidos:

• Aprobación de pagos por Supervisor. Se decidió explícitamente no implementarla (decisión #7 del plan v2). El flujo de pago no tiene paso de autorización.
• Autorización de Supervisor para abrir o cerrar caja. Existió y se sacó el 2026-08-05 (ADR-007 §4): el ledger inmutable ya da la trazabilidad, y exigir al Supervisor físicamente en el PDV era fricción diaria.
• Motor de comisiones editable por CIS — ver el punto de comisión más arriba.
• Cambio de moneda en el pago — diferido a MVP2 por confirmación de CIS-EC.
• Integración Soterex real (M5) — sigue en modo mock, sin credenciales de sandbox y con la pregunta #2b abierta.

---

Índice · Siguiente: Sitemap →