Skip to content

Modelo de saldos — cómo se mueve la plata ​

Análisis Funcional: Módulo Caja — parte 2 de 7. ← Resumen del alcance · Índice · Siguiente: Flujos de Caja →

Este es el documento central del paquete. Explica de qué bolsillo sale cada peso cuando se paga una transacción, y por qué los saldos que la app muestra no siempre bajan juntos.

El modelo que rige es el de tres capas —Holding → País → Caja—, definido con el cliente el 2026-08-05 e implementado en E4b (mergeada el 2026-08-06). El modelo anterior, de dos saldos, ya no existe: se menciona una sola vez, más abajo, para quien venga de conocerlo.

Si preferís verlo en una sola imagen, andá directo a 1.10: el diagrama del circuito completo, qué movimiento aparece en cuál de los cuatro extractos de tesorería (B7, 2026-10-02) y el ejemplo de la planilla del cliente número por número. Las secciones 1.1 a 1.9 explican el porqué de cada regla; la 1.10 las junta.

1.1 El principio que no cambia: los saldos no se guardan, se calculan ​

Ni el prefondeo ni la caja tienen una columna "saldo actual" en ningún lado. Cada saldo es la suma de sus movimientos, calculada en el momento en que alguien la pide.

saldo = Σ movimientos que suman − Σ movimientos que restan

Es el patrón que el proyecto ya usaba para el prefondeo desde M2 y que ADR-005 extendió a la caja: un solo lugar de verdad, imposible de desincronizar. La contracara es que no existe "corregir el saldo" — solo existe agregar un movimiento más. Volvemos sobre esto en §1.8, porque cambia cómo se opera.

Las tres funciones que derivan —PrefundingService::balance() / globalBalance(), CountryPrefundingService::balance() y CashBoxService::balance()— suman su ledger en cada lectura; ninguna lee una columna cacheada.

1.2 Qué cambió respecto del modelo de dos saldos ​

Hasta E4b había dos: un único pool en USD rotulado "prefondeo del país", que descontaba amount + fee, y la caja. Si venís de conocer ese modelo, todo lo que cambió es esto: ese pool pasó a llamarse Prefondeo Holding —que es lo que siempre fue, porque descontar la comisión es su comportamiento, no el del país— y apareció una capa nueva entre él y la caja. El porqué está en §1.3.

1.3 Las tres capas ​

Por qué apareció una capa nueva ​

En la revisión del 2026-08-05, Teresa Ortiz explicó algo que ninguno de los ADRs anteriores podía haber previsto: por el contrato nuevo, Soterex ya no le transfiere la plata al país. Le transfiere a una holding, que se queda con la comisión y le baja al país únicamente el principal que hay que pagar.

Mirado contra el código, el modelo de dos saldos quedaba mal repartido:

  • El único pool en USD que existe descuenta amount + fee. Eso es, exactamente, el comportamiento de la Holding — se llamaba "prefondeo del país" pero nunca lo fue.
  • El pool que el país necesita, el que descuenta solo principales y es comparable contra el extracto bancario del país, no existía.

De ahí sale la decisión: no se cambia el pool existente, se lo renombra a lo que siempre fue y se agrega abajo el que faltaba.

Ver ADR-007 §1.

Qué descuenta cada capa ​

CapaAlcanceDescuenta de cada pago¿Puede quedar negativa?¿Ve la comisión?
Prefondeo HoldingGlobal — suma de todos los paísesamount + feeSí, y nada lo impide ni lo avisa ⑴Sí, es la única que la ve
Prefondeo PaísPor paísamountSíNo
Caja operativaPor caja de un PDVamount, en la moneda de pago del paísNoNo

⑴ La Holding puede quedar negativa y nadie se entera. Al sacar la validación de prefondeo del pago, ninguna capa chequea su saldo, y tampoco existe un aviso al repartir a los países de más. Es una asimetría real del sistema —abajo, fondear una caja por encima de lo disponible del país sí avisa— y está documentada en ADR-010 (Proposed), que propone el aviso que falta. Medido el 2026-09-13 sobre la base de desarrollo: los países tenían repartidos 148.100 contra 138.100 que la Holding había recibido, o sea 11.888,90 de más, en silencio.

La comisión se liquida a fin de mes entre la Holding y Soterex. Por eso el país nunca la ve: no la negocia, no la paga y verla en su saldo lo volvería incomparable contra el extracto del banco, que es justamente contra lo que Diego concilia.

1.4 El ejemplo canónico, paso a paso ​

Es el ejemplo que Diego Sánchez planteó en la reunión y que Carlos validó línea por línea. Sirve como test de comprensión: si los tres números finales te cierran, entendiste el modelo.

Punto de partida

Prefondeo Holding ....... 200 USD
  └── Prefondeo Pais Guatemala .... 100 USD

Paso 1 — tesorería le manda plata a las cajas. Llegan 20 en blindado a la Caja 1 y 20 a la Caja 2, y Tesorería (hasta B6, el Supervisor) los carga como FONDEO con motivo Fondeo inicial.

CapaAntesDespuésPor qué
Holding200200No se pagó nada todavía
País100100⚠️ No baja — la plata se movió de lugar, no se gastó
Caja 1020Entró el efectivo
Caja 2020Entró el efectivo

En la pantalla de Prefondeo País, después de este paso, se ven tres números y no uno — porque "saldo del país" solo no alcanza para saber cuánto queda para repartir:

Saldo del pais ................ 100
  Distribuido en cajas ........  40     (20 + 20)
  Disponible para distribuir ...  60     (100 - 40)

Ese tercer número es contra el que avisa el sistema: si un fondeo lo deja en negativo, la caja se fondea igual y aparece el aviso (§1.3 ⑴ explica por qué arriba, entre la Holding y el país, ese aviso todavía no existe).

Este es el punto que más costó cerrar en la reunión, y vale detenerse. Diego preguntó textualmente: "ingresan los 20, ingresan los 20 también en la caja 2. No he pagado nada todavía… ahí la pregunta es, esto se mantiene en 100, ¿verdad?". La respuesta es sí.

El prefondeo del país no es "plata disponible sin repartir": es toda la plata del país. Mandarla a un cajón es moverla del banco al cajón, y en los dos lados sigue siendo del país. Recién deja de ser del país cuando se le entrega a un beneficiario. Dicho al revés: el prefondeo del país solo baja cuando se paga una transacción, nunca por distribuir.

Si el fondeo descontara el país, la plata se contaría dos veces hacia abajo — bajaría al mandarla al PDV y volvería a bajar al pagarla.

Paso 2 — el cajero paga una transacción desde la Caja 1. El principal es 5 USD y la comisión que Soterex informó para esa transacción es 2 USD.

CapaAntesDespuésQué descontó
Caja 12015Solo el principal — 5
Caja 22020Nada: el pago sale de la caja que abrió ese operador
Prefondeo País10095Solo el principal — 5
Prefondeo Holding200193Principal + comisión — 5 + 2

Diego lo cerró así: "mi caja actual va a tener ahora 15 USD… la caja operativa se me redujo los 5 que ya pagué, y en el fondeo de holding van a estar los 5, que serían 195 − 2, 193". Carlos: "esa es exactamente [la lógica], eso pasa".

Nota sobre los 195. El plan de E4b muestra la fila del Holding como "antes 195, después 193". Ese 195 es el paso intermedio del cálculo hablado de Diego — restar primero el principal y después la comisión. El punto de partida del Holding es 200 y el final es 193, como está en ADR-007 §1. Es la misma cuenta, contada en dos tiempos.

Resultado final

Holding ......... 193      -- bajo 7:  principal 5 + comision 2
  Pais Guatemala .. 95     -- bajo 5:  solo el principal
    Caja 1 ......... 15    -- bajo 5:  solo el principal
    Caja 2 ......... 20    -- intacta

Los tres bajan en el mismo pago, pero por importes distintos. No es un descuadre: cada capa mide una cosa distinta. Estos mismos números, leídos como un estado de cuenta línea por línea, están en 1.10.

1.5 Por qué el saldo del país puede quedar negativo ​

Ver ADR-007 §2.

El escenario que planteó tesorería es concreto: la transferencia al país está en trámite, así que el prefondeo del país figura en cero. Pero en el cajón del PDV hay plata física, porque el blindado ya llegó. Llega un beneficiario a cobrar.

Con el modelo viejo ese pago se rechazaba con INSUFFICIENT_PREFUNDING: la app negaba una operación que físicamente se podía hacer, por un problema administrativo que no tenía nada que ver con el efectivo del cajón. Diego lo resolvió en una línea: "que me consulte en la caja operativa y listo". Teresa lo confirmó: "si hay, paga; si no hay, no paga — que no le consulte al prefondeo".

Si el pago se hace igual y el país estaba en cero, el país queda en rojo. Y eso es correcto: el número negativo es exactamente la deuda que el país tiene con la Holding por la plata que ya entregó y todavía no le bajaron. Carlos lo planteó así en la reunión: "para que a mí me cierre toda la contabilidad del sistema, esto tiene que permitir negativo por lo que acabás de pagar".

Un saldo negativo del país es información contable válida, no un estado de error. Se muestra —en rojo, con leyenda— y no bloquea nada.

Ojo con no generalizarlo: la caja operativa no puede quedar negativa. En un cajón físico no existe "menos cero", así que un ajuste que dejaría la caja bajo cero se rechaza (ADJUSTMENT_WOULD_GO_NEGATIVE). El negativo es una propiedad del pool contable del país, no del efectivo.

1.6 Qué valida el pago ​

La regla de fondo: el pago consulta la plata que está en el cajón, no la que está en los pools contables. Los tres saldos bajan con cada pago, pero solo uno puede frenarlo.

En un país con módulo Caja activo (Guatemala) ​

El pago corta si falla cualquiera de estas, en este orden:

  1. Faltan los documentos obligatorios —carta e identificación, anverso y reverso— → MISSING_REQUIRED_DOCUMENTS (ADR-008). Es el bloqueo más frecuente en la operación real, y no tiene nada que ver con saldos.
  2. El operador no tiene ninguna caja abierta a su nombre → NO_CASH_BOX_OPEN_FOR_USER.
  3. La caja que tiene abierta se abrió un día anterior al de hoy → CASH_SESSION_FROM_PREVIOUS_DAY (ADR-013). Corta antes de mirar país, tipo de cambio o saldo: con una caja vencida lo único que se puede hacer es cerrarla.
  4. La caja que tiene abierta es de otro país que el de la transacción → CASH_BOX_COUNTRY_MISMATCH.
  5. El país paga en moneda local y no hay tipo de cambio vigente → NO_EXCHANGE_RATE. Con la bandera apagada —el caso de Guatemala— esta validación no corre (§1.7).
  6. La caja no cubre el monto a entregar → INSUFFICIENT_CASH_BALANCE.

Ninguna de las dos capas de prefondeo bloquea nada. El Prefondeo País baja y puede quedar negativo; el Prefondeo Holding baja y también puede quedar negativo, sin aviso (§1.3 ⑴). La Holding pasó a ser una capa puramente contable y de reporte hacia Soterex.

Todo PAGO de caja es efectivo (G3, 2026-10-05). Este modelo siempre supuso que la plata que sale de la caja es la que el operador cuenta y entrega en el mostrador, pero mientras existió el pago por transferencia eso era falso: applyCashBoxDiscount descontaba la caja sin mirar el medio de pago y la caja reportaba menos efectivo del que tenía (RV3-13). Desde G3 el medio de pago es solo efectivo y el backend rechaza otro con un 422 antes de tocar la caja, así que no hay ninguna rama «transferencia» que el pago tenga que sortear (ADR-011, actualización G3; Preguntas Abiertas del pago, #3). Los PAGO por transferencia que ya estaban en el ledger de Staging no se borran: se compensan con un AJUSTE por caja (ver la fila «Un pago de prueba por transferencia» de la tabla de §1.8).

En un país sin módulo Caja (Ecuador, con su EPOS) ​

Ahí no hay cajón físico que consultar, así que se mantiene una validación de saldo, contra el Prefondeo País y por el principal solamente: INSUFFICIENT_PREFUNDING.

Merece una aclaración honesta: es una decisión conservadora del equipo, no algo que el cliente haya pedido. Toda la conversación del 2026-08-05 fue sobre Guatemala con caja física; sacar la validación también donde no hay caja dejaría a Ecuador —en producción— sin ninguna barrera de saldo, y eso nadie lo discutió. ADR-007 §2 la deja escrita como asunción explícita. Si el cliente confirma que quiere sacarla en todos lados, es borrar una rama. Anotada en Preguntas Abiertas #8.

1.7 La moneda de la caja ​

Cada país tiene una bandera, countries.pago_en_moneda_local, y el default es pagar en dólares.

  • Apagada (Guatemala). Teresa lo explicó en la reunión: "en este momento en Guatemala no podemos hacer cambio porque no tenemos la autorización… la transacción es pagada en dólares". El pago descuenta el monto nominal en USD, no se guarda tipo de cambio (exchange_rate queda en null) y no se exige TC vigente — bajo esta configuración, NO_EXCHANGE_RATE sería un bloqueo falso.
  • Encendida. El pago convierte: amount × TC vigente, y el TC usado queda congelado en el movimiento, así que una reimpresión futura muestra el TC del día del pago y no el de hoy.

El ledger guarda la moneda en cada movimiento (cash_movements.currency), no la infiere del país. Como la bandera es editable, sin eso un país que cambiara de moneda dejaría movimientos viejos y nuevos en el mismo ledger en monedas distintas, y el saldo sumaría peras con manzanas. Los movimientos en la moneda anterior quedan visibles aparte, como saldos residuales.

El módulo de tipo de cambio no se tira: queda listo para cuando llegue la autorización, o para el esquema de casa de cambio tercerizada que Teresa mencionó como segunda instancia.

1.8 Ledger inmutable: qué implica para quien opera ​

Los movimientos de caja no se editan y no se borran. Nunca. Ni por un Admin.

Esto no es una limitación técnica que se pueda levantar más adelante: es lo que hace que el saldo sea confiable. Si un movimiento se pudiera editar, el saldo de ayer dejaría de ser reproducible y la auditoría perdería sentido.

En la práctica, para el usuario:

Si pasó esto……no se hace esto…se hace esto
Cargué un fondeo de 1000 y eran 100Editar el movimientoUn AJUSTE de −900, con motivo
Conté el cajón y falta plataCorregir el saldo inicialUn AJUSTE negativo con motivo Faltante de arqueo, que tesorería revisa
Sobra plata en el cajónRetocar el saldoUn AJUSTE positivo con motivo Sobrante de arqueo
Llegó un blindadoEditar el saldo de aperturaUn FONDEO con motivo Blindado
Un pago de prueba por transferencia (de antes de G3) descontó la cajaBorrar el PAGO o editar su montoUn AJUSTE positivo por el total de esos pagos, motivo Otro con la descripción «Corrección de pago por transferencia de prueba». Procedimiento en Staging
Hay que dar de baja una caja que tiene plataDesactivarla igual, o borrarlaUn AJUSTE negativo por todo el saldo con motivo Retiro por baja de caja, y recién después desactivarla (ver 1.10)

El historial queda con las dos líneas: el error y su corrección. Es más ruidoso de leer que un número prolijo, y es exactamente el punto — el ruido es la trazabilidad. Teresa lo dijo así sobre los faltantes: "debería estar como un ajuste, y ahí el ajuste ya debería estarlo revisando tesorería".

Lo mismo aplica a las tres capas: los asientos de prefondeo (Holding y País) tampoco se editan, y el historial de tipo de cambio se corrige insertando un valor nuevo, nunca sobreescribiendo el anterior.

El corolario del saldo inicial de apertura ​

De acá sale, directamente, la regla R9 del Resumen: el saldo inicial de una apertura se hereda del cierre anterior y no es editable. Si se pudiera tipear, el operador tendría una vía para cambiar el saldo sin dejar rastro de por qué cambió — que es justo lo que el ledger inmutable evita en todos los demás caminos. Las dos razones legítimas para que el número sea distinto quedan tipificadas y auditadas por separado:

  • Falta o sobra plata física → AJUSTE con motivo de arqueo.
  • Entró plata nueva → FONDEO.

1.9 Resumen en una tabla ​

Prefondeo HoldingPrefondeo PaísCaja operativa
AlcanceGlobalPor paísPor caja de PDV
MonedaUSDUSDMoneda de pago del país
Se cargaManual, tesoreríaManual, tesoreríaFONDEO por Tesorería
Baja conPagos: principal + comisiónPagos: solo principalPagos: solo principal
No baja conDistribuir al paísFondear una caja—
Puede ser negativoSí — sin aviso ni validaciónSí — se muestra en rojoNo
Avisa si se reparte de más❌ No existe el aviso (ADR-010, pendiente)✅ Avisa al fondear una caja por encima de lo disponible—
Bloquea el pagoNoSolo en países sin CajaSí, es la única validación de saldo
Ledgerprefunding_entriescountry_prefunding_entriescash_movements
Se lee como extracto enPrefondeo Soterex, pestañas Soterex ↔ CIS Holding y CIS HoldingFondeo PDVs, pestaña PaísFondeo PDVs, pestaña PDV

1.10 El circuito completo y los cuatro extractos ​

Desde la entrega B7 (ADR-015, 2026-10-02) la tesorería lee el dinero como lo lee un banco: un estado de cuenta, con una línea por movimiento —fecha, concepto, referencia, débito o crédito— y el saldo que quedó después de cada una. Son cuatro extractos, uno por tramo del circuito.

No cambian ningún número del modelo. Los extractos son vistas derivadas de los mismos tres ledgers (§1.1: nada se guarda, todo se calcula), y el último saldo de cada uno es exactamente el que ya devolvía el servicio de siempre. Mostrar lo mismo de otra forma tampoco hace que fondear una caja descuente el país: eso sigue siendo distribución y no gasto (§1.4).

Esta sección es también la deuda que ADR-007 dejó anotada: la app tiene tres saldos que un usuario nuevo tiene que entender, y la forma de pagarla era un diagrama del circuito completo y no más prosa. Es el que sigue.

El circuito, de punta a punta ​

Los círculos ①–④ son los cuatro movimientos de plata que existen. E1 a E4 son los cuatro extractos:

ExtractoDónde se veEl saldo corrido es…
E1Soterex ↔ CIS HoldingPrefondeo Soterex › pestaña Soterex ↔ CIS HoldingLo que queda del prefondeo de Soterex: el Saldo con Soterex de la tarjeta de la pantalla (el «saldo final con Soterex» de la hoja del cliente)
E2CIS HoldingPrefondeo Soterex › pestaña CIS HoldingLo que la Holding tiene sin repartir, más lo que ganó en comisiones: recibido − enviado a países + comisiones. El encabezado separa cuánto de los créditos son comisiones: «de los cuales comisiones»
E3PaísFondeo PDVs › pestaña PaísEl disponible para distribuir del país (no el saldo del país: ver más abajo). Se encabeza CIS y el país, como la hoja
E4PDVFondeo PDVs › pestaña PDVLo que tiene el PDV en su bóveda y en sus cajas

Qué movimiento va a qué extracto ​

Cada fila es un movimiento de plata; cada columna, qué hace con ese saldo. Un crédito suma al saldo corrido y un débito resta.

MovimientoE1 · Soterex ↔ HoldingE2 · CIS HoldingE3 · País (disponible)E4 · PDVSaldo del país (contable)
① Soterex le acredita prefondeo a la Holdingcréditocrédito———
② La Holding le envía plata a un país—débitocrédito—sube
③ Tesorería fondea el PDV (a su bóveda) o una caja——débitocréditono cambia
③b Se pasa plata entre la bóveda y las cajas de un PDV, o entre dos cajas (L3)——sin línea ⑶sin línea ⑶no cambia
④ Se paga una transacción de principal P y comisión Fdébito de P + Fcrédito de Fsin línea ⑴débito de Pbaja P
Ajuste de caja (arqueo)——con el signo cambiado ⑵con su signono cambia

⑴ Un pago baja el saldo del país en P, y el movimiento de la caja que lo cubrió baja lo distribuido en P, por el mismo monto: el disponible no se mueve, así que el pago no es una línea del extracto del país. Si un pago no pasó por una caja del país (un país sin módulo Caja, o uno pagado antes de que existiera), sí es una línea y resta su principal.

⑵ Un faltante de arqueo baja la caja, así que sube lo que queda disponible en el país: el extracto del país lo muestra al revés que el del PDV. Los extractos de la Holding no tienen ajustes.

⑶ Un traspaso son dos movimientos del ledger de suma cero dentro del mismo PDV (sale de una caja y entra a otra), así que no cambia lo que tiene el PDV, ni lo distribuido, ni el disponible del país: no es una línea de E3 ni de E4. Sí está en el historial de cada caja y en Reportes → Cajas.

Lo que se lee de esta tabla, y que es lo que más cuesta: el pago es el único movimiento de plata que baja el saldo del país, mientras que fondear una caja (o la bóveda de un PDV) baja el disponible y deja el saldo del país igual.

La bóveda del PDV y los traspasos (L3, ADR-029) ​

El cliente pidió el 14/10 que Tesorería mande la plata al PDV y no a una caja: «recién ahí se decide a qué caja/s se distribuye el dinero», desde «una caja 0 / bóveda / líder», sin obligación de repartir todo, y pudiendo pasar plata entre cajas o de una caja de vuelta a la bóveda (por ejemplo, un operador no pagó y el otro se quedó sin fondos). Es una capa más entre el país y la caja:

QuéRegla
Qué esLa CashBox con number = 0 de cada PDV con módulo Caja. Se crea sola (al dar de alta el PDV, al activar el módulo del país y por migración en los PDV existentes). Arranca en cero
SesiónNo tiene: no se abre ni se cierra, no tiene «día». Sus movimientos (fondeo, ajuste, traspasos) no llevan sesión
PagosNo paga. Un pago sale solo de una caja operativa con sesión abierta hoy
Fondear y ajustarfondeo_caja:write (Tesorería y Admin), siempre, sin esperar a que alguien abra una caja. Ajustarla no la deja en negativo
Traspasartraspaso_caja:write (Supervisor de sus PDV, Tesorería y Admin; el Cajero no). Del mismo PDV, monto ≤ saldo de origen, y cada caja que no es la bóveda tiene que estar abierta hoy
Cómo se vePrimera de cada PDV en Saldos, como «Bóveda del PDV (Caja 0)». El Cajero no la ve ni su saldo
Saldo del paísUn traspaso no lo cambia ni cambia lo distribuido. Fondear la bóveda sí baja el disponible del país, como fondear una caja
ExtractosEl del país y el del PDV no muestran los traspasos (suman cero). El fondeo a la bóveda sí, rotulada «Bóveda»
Baja de un PDVUna bóveda con plata la bloquea: se vacía con un ajuste de «Retiro por baja de caja», sin abrirla

Un ejemplo con números inventados: Tesorería manda 5,000 USD al PDV (quedan en su bóveda y el disponible del país baja 5,000); el Supervisor pasa 2,000 a la Caja 1 y 1,500 a la Caja 2 (la bóveda queda con 1,500); a media tarde la Caja 1 se queda sin fondos y la Caja 2 no pagó nada: pasan 500 de la Caja 2 a la Caja 1. En todo momento el PDV tiene los mismos 5,000 menos lo que se pagó.

El saldo del país y el disponible para distribuir ​

Son dos números distintos y los dos son verdad. El del país se concilia contra el banco; el disponible dice cuánto queda para mandar a una caja. La relación entre ellos es siempre la misma:

saldo del país = distribuido en cajas + disponible para distribuir

El disponible es el saldo corrido del extracto País; lo distribuido es lo que hay en las cajas de sus PDVs.

Por eso en el extracto del país fondear baja el saldo corrido y en el encabezado el saldo del país no baja. Son los dos números de la planilla del cliente:

  • El «CIS Guatemala» de la planilla (30.000 → 25.000 → 7.000) es el disponible para distribuir: en la planilla, fondear un PDV lo baja. Es el saldo corrido del extracto País.
  • El «saldo final» de la planilla (12.500) es el saldo del país: 30.000 enviados menos 17.500 de principales pagados. No baja al fondear (§1.4) y va en el encabezado del extracto País, junto con lo distribuido en cajas y el disponible.

El ejemplo de la planilla del cliente, número por número ​

Es la hoja Módulo tesorería del Excel de Guatemala (filas 19 a 34). Un test automático lo reproduce paso a paso por API y, después de cada paso, afirma los cinco saldos en los cuatro extractos (TreasuryStatementApiTest::test_reproduce_la_planilla_del_cliente_paso_a_paso).

PasoE1 · Soterex ↔ HoldingE2 · CIS HoldingE3 · País (disponible)E4 · PDV1E4 · PDV2
Prefondeo de 50.000 a la Holding50.00050.000000
Envío de 30.000 a Guatemala50.00020.00030.00000
Fondeo de 5.000 a PDV150.00020.00025.0005.0000
Fondeo de 18.000 a PDV250.00020.0007.0005.00018.000
Pago de 1.000, comisión 10, en PDV148.99020.0107.0004.00018.000
Pago de 2.500, comisión 30, en PDV146.46020.0407.0001.50018.000
Pago de 4.500, comisión 54, en PDV241.90620.0947.0001.50013.500
Pago de 5.000, comisión 60, en PDV236.84620.1547.0001.5008.500
Pago de 4.500, comisión 54, en PDV232.29220.2087.0001.5004.000

Las filas de totales de la hoja (55 a 59) también están en la pantalla y en el test: las comisiones suman 208 —el encabezado de CIS Holding dice «de los cuales comisiones: 208»— y los pagos de cada PDV suman 3.500 y 14.000, que son los Débitos del período de sus extractos (1.000 + 2.500 en el PDV1; 4.500 + 5.000 + 4.500 en el PDV2).

Y el saldo contable del país al final, que no es ninguna de las columnas del país de arriba:

Saldo del paísDistribuido en cajasDisponible para distribuir
12.500 = 30.000 − 17.500 de principales pagados5.500 = 1.500 + 4.0007.000 = 12.500 − 5.500

Dos cosas para mirar en la tabla de arriba. El disponible del país queda clavado en 7.000 durante todos los pagos porque un pago no lo mueve (⑴). Y E1 y E2 cuentan la comisión al revés: E1 la resta de lo que le queda a Soterex (1.000 + 10 salen de los 50.000) y E2 la suma a lo que la Holding ganó (20.000 + 10). La planilla las cuenta así; ADR-015 §4 explica por qué no se contradice con el aviso que propone ADR-010.

Quién ve cada extracto ​

Cada uno sigue al permiso de la capa que muestra, y el backend lo exige aunque la pestaña no se dibuje:

ExtractoPermisoQuién
E1 y E2prefondeo (lectura)Tesorería y Admin
E3prefondeo_pais (lectura)Tesorería y Admin
E4fondeo_caja (lectura), con el alcance por PDV de la asignaciónSupervisor —solo sus PDVs—, Tesorería y Admin

El Supervisor entra a Fondeo PDVs y ve únicamente la pestaña PDV de los suyos; pedir el extracto de otro PDV, o cualquiera de los otros tres, responde 403.

Lo que ve cada persona depende de dónde tiene el permiso, no de un rol aparte: la hoja del cliente habla de «Tesorería Regional» y «Tesorería Local», y para el sistema es el mismo perfil con más o menos países asignados (D3-T1).

Con menos de todos los países. E1 y E2 cubren los países que el usuario puede leer: una Tesorería de Guatemala ve la parte de Guatemala, con el aviso de «parcial», y E3 y E4 completos de su país. La tarjeta de saldo de Prefondeo Soterex dice lo mismo que E1: suma los países del usuario (G12, D3-19 b) y trae el mismo indicador, en vez del saldo global que mostraba antes. «Todos los países» no cuenta a uno inactivo y sin movimientos (El Salvador y Honduras se siembran así); uno inactivo con movimientos sí. Quién ve qué, entidad por entidad de la hoja del cliente, está en la tabla de roles.

Los tres extractos de país —E1, E2 y E3— son de país entero: listan cada pago y cada fondeo de todos los PDVs. Una asignación acotada por PDV no alcanza para leerlos (ese país queda fuera de ellos, y pedirlo a mano responde 403); solo el E4 sigue el alcance por PDV. Con los perfiles sembrados no cambia nada: Tesorería y Admin no van acotados. (ADR-015 §5.)

Lo que un extracto no muestra ​

  • Nada del beneficiario. De cada pago salen el MTCN (en la columna Referencia), el monto, la comisión y la fecha. Tesorería no tiene permiso sobre las transacciones, y para conciliar le alcanza con eso.
  • Gastos bancarios. El cliente pidió expresamente no tomarlos en cuenta: el crédito de un prefondeo es lo que se cargó en el asiento. El monto que se carga es el que envió o notificó el nivel de arriba, no el que acreditó el banco: el costo de la acreditación lo asume quien recibe y queda fuera del control (RV3-58).
  • El «Saldo final CIS Holding» de 32.708 de la hoja. Es el Monto actual de CIS Holding (20.208) más el saldo final de CIS Guatemala (12.500), y supera en 208 —la comisión— a los 32.500 que quedan en total. No se sabe si el cliente lo quiere ver o si es un doble conteo, así que la app muestra los tres números de siempre y ese no: es la pregunta #25.
  • Saldo corrido en un país que paga en moneda local. El disponible resta lo repartido en cajas, en la moneda de pago, a un saldo en USD, y con otra moneda esa resta no significa nada. Ese extracto muestra los movimientos sin saldo y lo dice. Hoy ningún país está en ese caso.

Cómo se lee un extracto en la pantalla —el saldo anterior, el orden, los rojos, el export— está en el manual. El detalle de la API y de las decisiones, en el ADR-015.

La baja de una caja y su saldo ​

Desde G7 (ADR-022, 2026-10-06) una caja se puede desactivar, y la pregunta del modelo es qué pasa con la plata que tiene adentro. La respuesta, decidida por Carlos (D3-14 a): una caja con saldo no se desactiva. Se deja en cero primero, con un AJUSTE negativo de motivo Retiro por baja de caja, y recién ahí se da de baja. Eso exige abrirla (el ajuste pide una sesión abierta del día), ajustar, cerrarla y desactivarla.

Lo que esto significa para los saldos:

  • Ningún saldo se guarda ni cambia de fórmula. cash_boxes.active es configuración, no un saldo (§1.1). El saldo de una caja sigue siendo la suma de su ledger y la desactivación no escribe ningún movimiento.
  • Una caja de baja siempre está en cero —cerrada y sin plata en ninguna moneda—, así que sacarla de Saldos no hace que ningún total discrepe del extracto del PDV ni de «Distribuido en cajas». Es justamente lo que la alternativa de permitir desactivar con saldo habría roto: el total del PDV de Saldos tendría que seguir sumando una caja que Saldos no muestra. La misma regla vale para las otras vías por las que una caja deja de ser operable: desactivar su PDV, mudar el PDV de país y apagar el módulo Caja del país se rechazan (409) mientras alguna caja tenga una sesión abierta o plata adentro, y solo cuando esas cajas hoy son operables (PDV activo de un país con módulo Caja). Si no, la plata de la caja desaparecería de Saldos sin que nadie pudiera retirarla.
  • Su historia no desaparece. El ledger de la caja, los extractos de Tesorería, «Distribuido en cajas» y Cierres por día siguen leyendo todas las cajas, también las de baja. Reportes → Cajas la marca Inactiva. Reactivarla la devuelve con su número y su saldo (que es cero).
  • El retiro es un AJUSTE, no un movimiento nuevo de otro tipo. Baja el saldo de la caja y, como cualquier ajuste, no toca el saldo del país; lo que se mueve es la derivada: baja lo distribuido en cajas y, como saldo del país = distribuido + disponible (§1.10), sube el disponible para distribuir. Contablemente la plata vuelve al pool del país, que es lo que corresponde cuando se vacía una caja, y el retiro figura en el extracto País de Fondeo PDVs como un movimiento con su signo (ADR-015 §6). El sistema registra el retiro; la logística del efectivo físico queda afuera (0.3).
  • Por qué un motivo propio y no Faltante de arqueo. El faltante afirma que faltaba plata en el cajón, y acá no falta nada: se retira a propósito. Con el motivo propio el historial y el filtro por motivo separan una cosa de la otra.

La línea de país de Saldos (G6.C) es la contracara de lo mismo: es la plata que hay en las cajas de cada país, en su moneda de pago. Con el alcance completo es exactamente el «Distribuido en cajas» de §1.10, el mismo cálculo y no uno parecido; con el alcance parcial es la suma de las cajas de los PDV que el usuario ve y la pantalla lo rotula «Total de tus PDV». Como cuenta el ledger de TODAS las cajas del país, la línea incluye la plata de un PDV inactivo, que no tiene tarjeta porque sus cajas no son operables: con alcance completo puede ser mayor que la suma de las tarjetas. Hoy solo pasa con un PDV que se desactivó antes de G7 (desde G7 no se desactiva un PDV con plata en sus cajas), y el cliente, que dibujó la línea como la suma de las tarjetas, tiene esa diferencia explicada en Preguntas abiertas #24.


Análisis Funcional: Módulo Caja — parte 2 de 7. ← Resumen del alcance · Índice · Siguiente: Flujos de Caja →

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