Análisis de las definiciones de CIS-EC (mail de Maggie, 2026-08-07)
Fuentes: mail de Magui con tres adjuntos — Soterex - GT Detalle requerimientos.xlsx (hojas Requerimientos, Módulo tesorería, Módulo caja), Soterex - Reporte completo.xlsx (8 hojas, la relevante es Request Pilot List) y la carpeta Docs soporte tx (9 archivos: modelos de papeleta y formulario de enrolamiento, más un ejemplo real de cada documento que hay que guardar).
Qué es esto: el material cierra las 5 definiciones que estaban pendientes del lado de Operaciones (CIS-EC) y que bloqueaban E5. Pero además contradice dos decisiones ya implementadas y mergeadas a main, y agrega alcance que no estaba en ningún plan.
Este documento no resuelve las contradicciones — las expone con la evidencia de cada lado, porque resolverlas es decisión del negocio.
0. Decisiones de Carlos (2026-08-07)
Tomadas sobre este análisis, el mismo día. Dos se apartan del material escrito de CIS-EC — no por desconocerlo, sino habiéndolo leído. Quedan registradas acá con esa salvedad, porque hay que comunicárselas al cliente antes de que aparezcan como sorpresa.
| # | Decisión | ¿Coincide con el material? |
|---|---|---|
| §2.1 Distribución | El saldo del país NO baja al fondear una caja. Se mantiene lo implementado en E4b.3 y el desglose de tres cifras | ❌ No. El material muestra el saldo bajando. Prevalece lo que Diego definió en la reunión del 05/08 |
| §4 Escenario | Escenario 1, con capa Holding, directamente. Es lo que E4b.3 ya implementa | ⚠️ Parcial. Maggie sugería arrancar con el 2 y migrar. Teresa igual debe confirmarlo |
| §2.2 Comisión | La comisión la sigue devolviendo Soterex por transacción. ADR-005 queda vigente, sin motor de comisiones | ❌ No. El requerimiento #2 pide una tabla de tramos editable |
| §7 Siguiente | E5a — datos y documentos del pago | — |
Qué hay que devolverle a CIS-EC
Estas dos divergencias no se resuelven solas y conviene plantearlas antes de seguir construyendo encima:
- El requerimiento #2 queda sin implementar a propósito. Si Soterex ya devuelve el
feepor transacción, la tabla de tramos no tiene consumidor en la app. Hay que confirmarles que elfeede la API es el valor bueno — y si no lo es, la decisión se cae y hay que reabrirla. - El saldo del país significa otra cosa que en sus planillas. En la app es el total contable (incluye lo que está en las cajas); en el Excel es lo que queda en el banco. Los dos números son correctos, pero no son el mismo, y alguien va a compararlos.
1. Lo que queda confirmado (sin cambios para nosotros)
| Tema | Confirmación |
|---|---|
| Cambio de moneda → MVP2 | "Ningún reporte incluye el manejo de la integración (cambio de moneda), ya que se necesita tener una autorización... dejar este desarrollo para un MVP2". Valida E4b.2 §6: la bandera pago_en_moneda_local queda apagada y el módulo de TC sin usar |
| Selfie opcional | Hoja Módulo caja, fila 18: "DESEABLE, no es obligatorio". Coincide con la decisión #17 del plan v2 |
| Papeleta | Se adjunta el modelo real (Word). Confirma formato y contenido de E5.3 |
| Reportes exportables a Excel | "todos los reportes deben ser exportables a Excel". Ya lo hacemos en Reportes, Auditoría y Caja |
| Soportes como foto, escaneo o PDF | Hoja Módulo caja, fila 14. No hay que exigir un formato único |
2. ⚠️ Lo que contradice lo que ya está en main
Las dos son estructurales y las dos ya están implementadas al revés.
2.1 Distribuir plata a una caja sí descuenta el nivel de arriba
Lo que implementamos (ADR-007 §1, E4b.3): mover plata del país a una caja no descuenta el prefondeo del país — es distribución banco→cajón, no gasto. El país solo baja cuando se paga. Para compensar que el saldo entonces no dice cuánto queda para repartir, construimos el desglose "distribuido en cajas / disponible para distribuir".
Sale de la reunión del 2026-08-05, donde Diego lo dijo textual: "el fondo país sigue siendo 100", y Carlos confirmó el ejemplo numérico completo.
Lo que dice el material de Maggie: exactamente lo contrario. Hoja Módulo tesorería, filas 22-23 — CIS GUATEMALA recibe 25.000 y al fondear PDV1 con 5.000 su saldo pasa a 20.000:
| Fila | Operación | Saldo CIS GT |
|---|---|---|
| 20 | Prefondeo a CIS GT | 25.000 |
| 22 | Prefondeo a PDV1 (−5.000) | 20.000 |
| 23 | Prefondeo a PDV2 (−20.000) | 0 |
El mismo patrón se repite en la hoja Módulo caja (filas 30-33) para PDV → cajas individuales.
Por qué importa: con el modelo de Maggie, el saldo de cada nivel es lo que queda para repartir, y el desglose de tres cifras que construimos sobra. Con el nuestro, el saldo es contable y el desglose es indispensable. Son dos modelos coherentes pero incompatibles, y ambos vienen del cliente.
Qué hace falta: que Teresa y Diego confirmen cuál rige. Si es el de Maggie, se simplifica —distributedInCashBoxes() y availableToDistribute() desaparecen— pero hay que cambiar cuándo se debita el país, que es lógica de plata.
2.2 La comisión sí la calcula CIS, con una tabla de tramos
Lo que decidimos (ADR-005): la comisión no es editable por CIS — la calcula y la devuelve Soterex granular por transacción (fee en SendRequest). Se eliminó countries.commission_pct por completo, argumentando que "no reflejaba la realidad".
Lo que pide el material (hoja Requerimientos, #2): "Tabla de comisiones por país: tramos de monto y valor fijo por tramo (y excepciones con porcentaje, si las hay)", y en el requerimiento: "Para el cálculo de la comisión, hacer el campo editable para un monto fijo, un % o una fórmula".
Los números de la hoja Módulo tesorería son consistentes con tramos:
| Principal | Comisión | % |
|---|---|---|
| 1.000 | 15 | 1,50% |
| 2.500 | 30 | 1,20% |
| 2.600 | 30 | 1,15% ← mismo valor que el tramo anterior |
| 3.000 | 36 | 1,20% |
| 4.000 / 4.500 / 5.000 | 48 / 54 / 60 | 1,20% |
Que 2.500 y 2.600 paguen lo mismo descarta un porcentaje puro: es una tabla de tramos.
Por qué importa: ADR-005 no solo eliminó el campo, sino que construyó un argumento entero sobre que la comisión es un dato de Soterex. Si CIS la calcula, hay que reintroducir un motor de comisiones —más rico que el commission_pct que se borró— y revisar qué significa entonces el fee que devuelve Soterex.
Ojo: el mail dice que "el 100% de la comisión que paga Soterex se queda en CIS EC" y que CIS EC liquida a CIS GT por fuera de la API. Eso sí coincide con ADR-007: el país no ve comisiones. Pero queda una segunda tabla pendiente —la comisión de CIS EC a CIS GT— que Teresa todavía no definió.
3. Alcance nuevo que no estaba en ningún plan
3.1 Un nivel de caja más: la caja principal del PDV
Hoy modelamos país → cajas del PDV. El material describe país → PDV → cajas individuales (hoja Módulo caja, filas 30-33): el PDV tiene su propio saldo, y desde ahí se fondean la Caja 1 y la Caja 2.
3.2 Transferencias entre cajas
Hoja Módulo caja, fila 25: "considerar retiro de fondos en la dirección contraria para fondear las cajas individuales (caja 1 a la 2) o la caja principal del PDV (caja 2 al PDV)".
Hoy solo existen fondeo (suma) y ajuste (corrige). No hay transferencia, que es una operación distinta: un solo acto que resta de un lado y suma del otro, y que debe verse como una sola cosa en la auditoría.
3.3 Alerta de reposición al 30%
Aparece en los dos escenarios y en todos los niveles: "Cuando el saldo prefondeado llegue al 30%, debe solicitar un nuevo prefondeo", con el umbral parametrizable. En las hojas se ve como "enviar alerta de pedido de prefondeo adicional" en Soterex, Holding, país, PDV y caja.
No existe nada de esto: no hay umbrales, ni alertas, ni notificaciones.
3.4 Medio de pago: efectivo o transferencia bancaria
Hoja Módulo caja, fila 12, y columna AA del reporte ("Agregar un box para escoger el medio de pago"). Todo el módulo Caja asume efectivo. Con transferencia bancaria:
- Se suman cuatro documentos, por única vez por cliente (enrolamiento, cartola, solicitud, mail de confirmación de acreditación).
- Hay que guardar datos de cuenta bancaria (columna
AB). - Pregunta abierta de Teresa: si la figura existe o se deja solo efectivo.
Si el pago no es en efectivo, además, no debería descontar de la caja física — eso no está dicho en ningún lado y es una pregunta que hay que hacer.
3.5 Transacción "pagada pero incompleta"
Hoja Módulo caja, fila 14: "Podría evaluarse la posibilidad de que la tx se quede pagada pero incompleta, si todos los soportes no se han guardado". Es un estado que hoy no existe.
3.6 El operador completa datos de la transacción
Requerimiento #1: "Si Soterex no envía la columna por la API, favor incluir los campos en la pestaña del pago de la tx (Módulo Cajero)". El wizard de pago no solo sube documentos: captura datos.
De las 36 columnas que se quedan en el reporte, estas las carga CIS al pagar y no existen en nuestro modelo:
Address · City · State · Identification Type · Identification Country · Identification Number · Phone 2 · Email 2 · Payout Currency · Ex. Rate · Beneficiary Destination Amount · Cta Bancaria · Notes · Destination Delivery Type · Paid at Branch City/State
Y estas tampoco, aunque son de origen Soterex o derivadas: Nationality, PIN Number, Transaction Expiration Date (la carta dice 60 días), Payer Name, Transaction Status - Update, Additional Notes.
PIN Numbermerece atención aparte. La carta al beneficiario trae "PIN de Pago" como dato separado del MTCN, y las instrucciones dicen: "En la ventanilla, proporcione el PIN de Pago. Este código es necesario para entregar los fondos". Es un control de seguridad del pago que no tenemos modelado.
3.7 El reporte regulatorio
36 de las 48 columnas se quedan. Es un reporte nuevo, distinto de los que ya existen, exportable a Excel. El mapeo completo columna por columna está en el adjunto y hay que traducirlo a un documento nuestro cuando se implemente.
3.8 Formulario de enrolamiento generado por el sistema
Hoja Módulo caja, fila 21: "Ver la posibilidad de emitirlo desde la misma API porque ya se cuenta con todos los datos". El modelo Word tiene los campos: nombres, tipo y número de identificación, dirección, ciudad, estado/provincia, teléfono, país de residencia, nacionalidad, correo, género, fecha de nacimiento, estado civil y datos de cuenta bancaria.
Género y estado civil no existen en nuestro modelo ni vienen en el reporte.
4. Los dos escenarios de tesorería
| Escenario 1 | Escenario 2 | |
|---|---|---|
| Estructura | Soterex → Holding → País (GT/EC) → PDV | Soterex → País (GT y EC por separado) → PDV |
| Capas internas | 3 (Holding, País, PDV/Caja) | 2 (País, PDV/Caja) |
| Quién ve todo | CIS Holding y CIS EC (administrador) | CIS EC (administrador) |
| CIS GT | Solo su estado de cuenta | Solo su estado de cuenta |
Maggie sugiere arrancar con el 2 y migrar al 1, y Teresa tiene que confirmar.
Esto importa directamente: E4b.3 implementó el escenario 1 (tres capas con Holding). Si arrancan con el 2, la capa Holding queda sin uso real en MVP1 — no rompe nada, pero es una pantalla y un ledger que nadie mira todavía.
Vale notar que el escenario 2 del Excel no tiene capa Holding en absoluto: Soterex prefondea directo a cada país.
5. Cambio organizacional
"CIS EC será el administrador de la caja de CIS GT" — confirmado con Tere.
Guatemala no opera su propia tesorería: la opera Ecuador. Impacta la matriz de permisos, porque significa que hay usuarios de EC con alcance sobre los saldos de GT — y encaja con la decisión del 2026-08-06 de que el Prefondeo País lo cargan Supervisor y Admin, no un rol nuevo.
También explica por qué el mail no incluye al equipo de Guatemala.
6. Lo que sigue sin definirse
| # | Qué falta | Quién | Bloquea |
|---|---|---|---|
| 1 | La tabla de comisiones en sí. El requerimiento la pide y el comentario dice que aplica a todos los países, pero no vino en ningún adjunto — solo los montos de ejemplo | CIS-EC | Motor de comisiones |
| 2 | Escenario de tesorería: 1 o 2 | Teresa | Cuánto de E4b.3 queda en uso |
| 3 | Si existe la figura de pago con transferencia bancaria | Teresa | 4 documentos y el medio de pago |
| 4 | Comisión de CIS EC a CIS GT (si CIS GT se queda con la suya) | Teresa | Segunda tabla de comisiones |
| 5 | Si Soterex notifica el prefondeo por la API o se carga a mano | Soterex | Automatizar la capa superior |
| 6 | Cuál de los dos modelos de distribución rige (§2.1) | Teresa / Diego | Semántica del saldo del país |
| 7 | Si un pago por transferencia bancaria descuenta la caja física | Teresa | Lógica del descuento |
7. Impacto en el plan
E5 se puede arrancar, pero es más grande de lo que decía el plan v2. Deja de ser "wizard de tres uploads + papeleta" y pasa a incluir la captura de ~15 campos nuevos, el medio de pago y la generación del formulario de enrolamiento.
Propuesta de reordenamiento:
- E5a — Datos y documentos del pago. Los campos que el operador completa, el medio de pago y los uploads. Es lo que menos depende de definiciones abiertas.
- E5b — Papeleta y formulario de enrolamiento. Ambos con modelo Word ya provisto.
- E6 (nueva) — Reporte regulatorio de 36 columnas. No estaba en el plan v2.
- E7 (nueva) — Motor de comisiones. Bloqueada por la tabla que falta.
- E8 (nueva) — Alertas de reposición al 30%. Independiente, se puede hacer en cualquier momento.
- Revisión de E4b según se resuelvan §2.1 y §4 — puede implicar deshacer parte de lo hecho.
La auditoría de seguridad y la documentación total, que eran E6 y E7, se corren al final.
Lo que NO haría todavía: tocar E4b.3 antes de que Teresa confirme el escenario y el modelo de distribución. Cambiar lógica de saldos dos veces sobre supuestos distintos es peor que esperar.