Skip to content

Diagramas de Actividad (procesos multi-componente) ​

Análisis Funcional: Integración Soterex — parte 5 de 8. ← User Flows · Índice · Siguiente: Secuencias de Pantalla →

⚠️ ACTUALIZADO (2026-08-07) ​

  • 4.1 (ingesta): sin cambios de fondo. Sigue siendo un cron cada 30 minutos y sigue sin implementarse contra Soterex real (M5, en modo mock). Se agregan dos precisiones sobre el MTCN.
  • 4.2 (pago): reescrito. El diagrama viejo mostraba un único saldo de prefondeo que bloqueaba el pago; hoy son tres ledgers y el que bloquea es la caja (ADR-007).
  • 4.3 (cancelación): sin cambios. La pregunta #2b sigue abierta.
  • 4.4: nuevo — el circuito completo del dinero entre las tres capas, que es lo que ningún diagrama de esta página mostraba.

⛔ CORREGIDO (2026-09-30, ADR-012) ​

Los dos ítems de arriba sobre 4.1 y 4.3 quedaron falsos, no desactualizados — no eran cambios de forma menores, era la dirección de la integración entera al revés:

  • 4.1 no es un cron ni un pull. Es Soterex quien llama a POST /api/c2p/v1/SendRequest (con OAuth 2.0 Client Credentials) cuando ellos tienen una transacción para registrar — CIS la recibe y responde en el momento, no hay ingesta programada. Diagrama reescrito abajo.
  • 4.3 no tenía una pregunta #2b sin resolver — tenía la llamada al revés. Se disuelve: ver la nota al principio de 4.3, más abajo.
  • Las dos precisiones sobre el MTCN (comisión no calculada por CIS, MTCN = PIN de pago) siguen vigentes tal cual, no dependían de la dirección de la llamada.

4.1 Ingesta de transacción — Soterex → CIS, bajo demanda (SendRequest) ​

CORREGIDO (2026-09-30, ADR-012): no hay cron. Es Soterex quien llama a POST /api/c2p/v1/SendRequest (autenticado con OAuth 2.0 Client Credentials contra POST /api/oauth/token) cada vez que necesita registrar una transacción nueva — CIS responde en el mismo request, con el MTCN ya generado.

Corrección 2026-07-25: el PDV nunca se asigna en este paso — Soterex no lo informa y a esta altura es imposible saberlo. La transacción queda disponible en la bolsa compartida del país. Ver 2.4.

PRECISADO (2026-08-07), dos cosas sobre este paso que no eran evidentes:

  1. La comisión llega acá y no se calcula. El fee viene en el request de SendRequest(CORREGIDO 2026-09-30: viene en el request que manda Soterex, no en la respuesta — el spec v1.4 lo tenía solo en la respuesta porque se escribió para el modelo pull, invertido), granular por transacción. CIS no lo configura ni lo puede alterar, solo lo guarda y lo devuelve tal cual (ADR-005).
  2. El MTCN que se genera acá es también el PIN de pago del beneficiario. CIS se lo informa a Soterex por Notifications, y Soterex lo imprime en la carta como "PIN de Pago". No son dos números: es el mismo — ver 4.2, acá abajo. ✅

Estado real (actualizado 2026-09-30): implementación en curso en feature/api-c2p-entrante (ver ADR-012) — deja de ser mock cuando Soterex tenga las credenciales de staging y confirme la URL/auth de Notifications (se documenta en doc/integracion/2026-09-30-soterex-staging.md, entrega C5, todavía no escrita).

4.2 Pago de transacción — Cajero → WebApp → Soterex ​

⚠️ REESCRITO (2026-08-07). El diagrama anterior (con la corrección del 2026-07-25) mostraba un único chequeo —"verifica saldo de prefondeo del país (pool único)"— que bloqueaba el pago. Eso dejó de ser cierto en dos frentes a la vez:

  • El prefondeo pasó a tener tres capas, con reglas de descuento distintas cada una.
  • La caja es la única que bloquea en países con módulo Caja; el prefondeo dejó de cortar (ADR-007 §2). En países sin módulo Caja se mantiene una validación, ahora contra el Prefondeo País.

Lo que sí sobrevive intacto del diagrama viejo: el lock pesimista con re-chequeo de estado y el 409 ante la carrera perdida. Esa parte era correcta y sigue siéndolo.

Actualizado 2026-10-02 (B6): el actor es el Cajero (el Backoffice de antes); el Supervisor y el Admin pagan igual. Pagar exige pago·E y se valida en la ruta y en el controller; Tesorería no puede pagar.

Actualizado 2026-10-05 (G3): el medio de pago es siempre efectivo. Cualquier otro (la transferencia que existía hasta G3) se rechaza con un 422 antes de bloquear la fila, así que no hay ningún camino que descuente la caja por un pago que no es efectivo.

  • Atomicidad: todo lo de arriba corre dentro de una sola transacción de base de datos. Si cualquier pata falla, no queda ni movimiento de caja ni transacción pagada.
  • Por qué el Prefondeo País puede quedar negativo: si la caja paga y el país estaba en cero, el saldo del país queda en rojo reflejando la deuda real con la Holding. Es información contable válida, no un estado de error — se muestra, no se bloquea.
  • La Holding también puede quedar negativa, y nada lo impide ni lo avisa: al sacar la validación de prefondeo del pago, ninguna capa chequea su saldo. Está aceptado a propósito (ADR-007 §1) — es una capa contable, no operativa.

4.3 Cancelación — Admin → WebApp, y Soterex → WebApp (API) ​

CORREGIDO (2026-09-30, ADR-012): el diagrama original tenía WebApp->>Soterex: POST Cancel API en el flujo humano — no existe, es al revés: Soterex es quien llama a POST /api/c2p/v1/Cancel de CIS, nunca CIS al de ellos. Cuando cancela un humano, no hay ninguna llamada saliente en el momento de cancelar — solo el Notification posterior, por outbox. La nota final ("mecanismo aún no definido", pregunta #2b) se disuelve: la cancelación iniciada por Soterex es una llamada más a Cancel, documentada como segundo alt abajo.

Actualizado 2026-10-02 (B6, P5 y P6): cancelar exige transacciones·B, que hoy tiene solo el Admin. El Cajero y el Supervisor no ven el botón y, si arman el pedido a mano, el backend responde 403. Lo que sigue es el flujo del Admin; la rama de Soterex no cambia (autenticación de máquina, no pasa por estos permisos).

4.4 Circuito completo del dinero (NUEVO) ​

Ningún diagrama de esta página mostraba de dónde sale la plata que el cajero le entrega al beneficiario. Con tres capas, esa omisión pasó de menor a confusa.

El ejemplo canónico que validó el cliente (Diego Sánchez, reunión 2026-08-05): con Holding en 200 USD, país Guatemala en 100 y dos cajas de 20 cada una, un pago de 5 USD de principal + 2 USD de comisión desde la caja 1 deja caja 1 en 15, país en 95 y Holding en 193. Fondear las cajas no había movido el 100 del país. La explicación completa está en Modelo de saldos.

Hallazgos ​

  1. El material de CIS-EC del 2026-08-07 modela la distribución al revés que 4.4. Las planillas de Maggie muestran el saldo del país bajando al fondear un PDV (25.000 → 20.000 tras fondear 5.000). Carlos decidió el mismo día mantener lo implementado (el país solo baja al pagar), porque es lo que Diego definió en la reunión del 05/08. Son dos modelos coherentes pero incompatibles, y los dos vienen del cliente: falta que Teresa y Diego confirmen cuál rige. Mientras tanto, el saldo del país significa algo distinto en la app y en las planillas del cliente, y alguien va a comparar los dos números.
  2. El material también describe un nivel más de caja —país → PDV → cajas individuales— y transferencias entre cajas, que hoy no existen (solo hay fondeo y ajuste). No está en ningún plan.
  3. Alertas de reposición al 30%, parametrizables y en todos los niveles, aparecen en el material del cliente y no existen en ninguna capa.

← User Flows · Índice · Siguiente: Secuencias de Pantalla →

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