ADR-018: La comisión C2P la calcula CIS con un tarifario por país
Date: 2026-10-05 Status: Accepted — decisión de Carlos del 2026-10-05 (D2 y D2b del plan doc/plans/2026-10-05-alineacion-contrato-c2p-soterex.md). Implementación en el plan: hechas K1a (el tarifario, el cálculo y el sembrado provisional) y K1b (SendRequest los usa: la comisión sale del tarifario, se guarda al crear, el fee del request se ignora y sin tramo se rechaza con 2026) y K8 completo: la API del ABM (alta, edición, desactivación, sin solapamientos y auditado; ver §6) y su pantalla (la pestaña «Comisiones» de Parámetros). Falta, en cualquier caso, el tarifario real, que lo define Tesorería y todavía no está cargado (ver Consecuencias). Supersedes in part: ADR-005 (la comisión no la fijaba CIS) y la decisión D13 de ADR-012 (fee obligatorio en el request de SendRequest). Ver también: ADR-007 (la comisión descuenta solo la Holding, sin cambios).
Actualización 2026-10-05 (decisión de Carlos), más abajo: el tarifario provisional de Guatemala ya no es el 1 % ni existe solo fuera de producción. Son 50.00 USD fijos por transacción, para cualquier monto, sembrados en todos los ambientes, producción incluida, y editables por país desde Parámetros → Comisiones. Reemplaza a D2b (§5 y las consecuencias que lo repiten, marcadas abajo). Ver Actualización 2026-10-05.
Context
Hasta hoy, dos decisiones decían que la comisión no es de CIS:
- ADR-005 (2026-07-31) leyó la especificación v1.4 de Soterex —escrita para el modelo pull, que después resultó invertido (ADR-012)— y concluyó que
feelo calcula y lo devuelve Soterex, que CIS no lo fija ni lo edita. En consecuencia eliminócountries.commission_pcty dejó atransactions.feecomo la única fuente de verdad. - ADR-012 §5, D13 (2026-09-30), ya con la dirección de la integración corregida (Soterex llama a CIS), mantuvo el criterio por decisión de Carlos: "la comisión la manda Soterex". El
feepasó a ser obligatorio en el body de SendRequest, con los errores 2016 (obligatorio) y 2017 (valor inválido).
Dos cosas cambiaron:
- La especificación de Soterex, aceptada como contrato definitivo el 2026-08-14, dice lo contrario. En la Operación 2 (
SendRequest) el request no tienefee: llevaamount("Principal, excluding fee") y el que responde devuelvefee("We store principal plus fee as the transaction total"). Quien responde es CIS. Con elfeeobligatorio, todo create armado según la especificación rebota con 2016: es la diferencia #8 del plan, marcada como bloqueante. - CIS-EC ya había pedido el motor. El requerimiento #2 del 2026-08-07 (hoja Requerimientos de
Soterex - GT Detalle requerimientos.xlsx, analizado endoc/plans/2026-08-07-analisis-definiciones-cis-ec.md§2.2) pide una tabla de comisiones por país: tramos de monto y valor fijo por tramo, con excepciones por porcentaje. Los números de su planilla de tesorería lo confirman: 2.500 y 2.600 pagan la misma comisión, así que no es un porcentaje puro. En su momento esa lectura chocaba con ADR-005 y quedó anotada como contradicción pendiente; con el contrato de Soterex ya no hay contradicción.
Restricciones que mandan:
- La comisión es plata y no admite error de redondeo. Se calcula con aritmética exacta, nunca con
float. - Ningún saldo se materializa (ADR-005, ADR-007): este ADR no toca ledgers ni saldos. La comisión sigue siendo un dato de la transacción, que descuenta solo la Holding.
- La comisión sigue siendo información restringida (ADR-005): no aparece en las pantallas operativas. Cambia quién la calcula, no quién la ve.
- No hay tarifario real todavía. Lo define Tesorería (Teresa) y no vino en ningún adjunto.
Decision
1. CIS calcula la comisión con un tarifario por país de destino
fee = fixed_fee + amount × percent / 100, del tramo activo del país que contiene al monto, redondeado a 2 decimales half-up.
- Tramo:
min_amount <= amount <= max_amount, los dos extremos incluidos;max_amountnulo es "sin tope". - Fijo, porcentaje o ambos: un tramo puede cobrar un monto fijo, un porcentaje, o fijo más porcentaje (los tres casos que pide el requerimiento #2).
- Half-up: 0,005 → 0,01 y 10,005 → 10,01. El redondeo se hace una sola vez, al final de la cuenta.
- Aritmética exacta con
brick/math(viene con Laravel y ahora está declarada encomposer.json; la imagen no trae bcmath). El monto entra como texto decimal o entero, nunca comofloat. - Si ningún tramo activo contiene al monto, no hay comisión y el alta se rechaza con el código
2026("fee: No fee schedule covers this amount for the destination country"). Lo mismo si la comisión resultante no entra entransactions.fee(decimal(12,2)): se trata como sin tarifario y queda un aviso en el log, porque indica un tramo mal cargado. - Tramos solapados: el ABM (K8) los impide en toda escritura (§6), pero la base no lo garantiza, así que el cálculo es determinístico igual: gana el de menor
min_amount, después el más viejo y después el de menor id.
La cuenta vive en App\Services\FeeCalculator, que devuelve la comisión como texto de 2 decimales ("5.00") más el tramo usado, por si quien llama lo quiere auditar.
2. El tarifario es una tabla: country_fee_tiers
Una fila por tramo: país (clave foránea a countries), min_amount, max_amount (nulo = sin tope), fixed_fee, percent, active, description y provisional. Los montos son decimal(12,2), el mismo ancho que transactions.amount y transactions.fee; el porcentaje es decimal(7,4).
- La base garantiza los rangos: ningún monto ni porcentaje negativo,
max_amount >= min_amounty un porcentaje de 0 a 100. Un porcentaje negativo produciría comisiones negativas en la contabilidad sin ningún error. - La base no garantiza que no se solapen. Una restricción de exclusión sobre rangos exige la extensión
btree_gisten Postgres, y crear una extensión es un privilegio que el usuario de las migraciones no tiene por qué tener en Aurora. Lo valida el ABM de K8. - Un tramo no se borra, se desactiva (
active = false), como los ítems de catálogo. Un país con tarifario no se borra por accidente.
3. El fee deja de ser parte del request
SendRequest ya no recibe fee. Si Soterex lo manda, se ignora, y si difiere de la comisión calculada queda registrado en la auditoría (qué difiere, sin PII). Los códigos 2016 y 2017 quedan fuera de uso y se listan como retirados en el sign-off. El alta guarda la comisión calculada en transactions.fee y la devuelve como texto en la respuesta.
4. La comisión se congela al crear la transacción
La comisión se guarda en transactions.fee en el momento del alta, y de ahí en adelante es un dato de la transacción. Cambiar el tarifario no toca ninguna transacción existente: ni las pendientes ni las pagadas ni las canceladas. Es lo mismo que ya pasaba con el fee que mandaba Soterex, y por eso el cambio no necesita ninguna migración sobre transacciones.
5. Tarifario provisional de Guatemala, solo fuera de producción (D2b) — reemplazado el 2026-10-05
Reemplazado. Lo que sigue es lo que se decidió el 2026-10-05 por la mañana y se implementó primero; ya no rige el valor (1 %) ni el alcance (solo fuera de producción). Lo vigente está en la Actualización 2026-10-05. Se deja el texto original como registro de qué se había decidido y por qué.
Mientras Tesorería no entregue el tarifario real, fuera de producción se carga para Guatemala un tramo único del 1 % del principal (min_amount 0,01, sin tope, fixed_fee 0, percent 1), marcado provisional = true y rotulado "PROVISIONAL — reemplazar por la tabla de Tesorería". Es el mismo ejemplo de la especificación de Soterex (500,00 → 5,00) y sirve para que Soterex pruebe el sandbox.
- En producción no se siembra nada, por ninguno de los dos caminos. Sin tarifario el alta se rechaza (2026), que es lo correcto antes de tener la tabla real: es mejor rechazar que cobrar una comisión inventada.
- Dos caminos, idempotentes, que convergen al mismo resultado: una migración de datos (las bases que ya existen, como staging) y
CountrySeeder(una base nueva, donde la migración corre antes de que exista Guatemala). Los dos llaman a la misma clase,EnsureProvisionalFeeSchedule, que decide todo: el ambiente, y que solo siembra si Guatemala no tiene ningún tramo (activo o no). Un tarifario real que ya se cargó, o un provisional que un Admin desactivó, no se pisa ni se resucita en el próximo deploy. provisionales lo que usa K8 para mostrar el aviso visible en Parámetros → Comisiones.
6. El ABM del tarifario (K8)
El tarifario se administra desde Parámetros → Comisiones, con el permiso abm_paises (lectura para listar, escritura para crear y editar; hoy solo lo tiene el Admin). La API es GET y POST /admin/paises/{country}/comisiones y PUT /admin/comisiones/{tier}, y las reglas viven en App\Services\FeeTierService:
- Sin baja: no hay DELETE. Un tramo se desactiva (y se puede reactivar), así queda la historia de qué tarifario rigió y quién lo cambió. La desactivación se audita distinto de una edición.
- Los tramos activos de un país no se solapan, con los extremos incluidos (igual que el cálculo del §1):
[0.01, 100.00]y[100.00, 200.00]chocan (el monto 100.00 sería ambiguo);[0.01, 100.00]y[100.01, 200.00]no. Se valida en el alta, en la edición y en la reactivación; un tramo inactivo no cuenta. La 422 (FEE_TIER_OVERLAP) dice con qué tramo choca. Como la base no lo garantiza (§2), cada escritura toma un lock de fila sobre el país antes de leer los tramos (FOR UPDATEdentro de una transacción, el mismo con el que se serializa el sembrado provisional): dos altas simultáneas que se pisan entre sí no pueden pasar las dos. - Los huecos avisan, no bloquean: las respuestas traen
meta.gaps, los montos que hoy no tienen comisión (SendRequest respondería2026), calculados al centavo con aritmética exacta. Un país sin tramos activos tiene un único hueco, de 0.01 al infinito. provisional: un tramo creado por esta API naceprovisional = false. Editar un valor de un tramo provisional (monto mínimo o máximo, comisión fija, porcentaje o descripción) lo pasa afalse: un Admin lo revisó y ya es suyo. Desactivarlo, reactivarlo o unPUTque no cambia ningún valor no tocan el flag. El aviso «PROVISIONAL — reemplazar por la tabla de Tesorería» esmeta.provisional: hay al menos un tramo activo provisional. Cuando una edición apaga el flag, si la descripción guardada empieza conPROVISIONALy el pedido no mandadescription, el servidor la pone ennull(no puede quedar «PROVISIONAL — reemplazar…» en un tramo conprovisional: false) y lo registra en elbefore/afterde la auditoría; si el pedido manda una descripción, se respeta.- Un tramo gratis es legítimo: comisión fija 0 y porcentaje 0 no se bloquea (puede ser una política);
meta.zero_fee_countcuenta los tramos activos sin comisión para que la pantalla lo muestre y no pase inadvertido. - Auditoría de cada cambio (
FEE_TIER_CREATED,FEE_TIER_UPDATED,FEE_TIER_DEACTIVATED,FEE_TIER_ACTIVATED, entidadcountry_fee_tier), con el usuario, el país y los valores; en la edición, elbeforey elaftersolo de lo que cambió. Son datos de configuración, no personales. - Cambiar el tarifario sigue sin tocar ninguna transacción existente (§4).
La pantalla. La pestaña «Comisiones» de Parámetros (/admin/ubicaciones/comisiones) se abre con el mismo permiso que Países (abm_paises: con lectura se ve el tarifario y los avisos; con escritura se crean, editan y activan o desactivan tramos), así que no cambia qué perfiles ven el ítem «Parámetros» del menú. Tiene un selector de país (arranca en el primer país activo) y la tabla de sus tramos —activos e inactivos, con «sin tope», la marca de provisional y el estado—; el alta y la edición van en un modal y desactivar o reactivar piden confirmación (que avisa si el tramo es el único activo).
- Avisos arriba de la tabla, que salen del
metade cada respuesta y se actualizan con cada alta, edición o cambio de estado sin volver a pedir la lista: sin ningún tramo activo y montos sin comisión (rojos: SendRequest se rechaza con 2026), tarifario provisional (ámbar: hay que reemplazarlo por la tabla de Tesorería cuando la defina; mientras tanto es el que se cobra, también en producción — texto actualizado el 2026-10-05; antes decía «antes de producción» y que el sandbox no cobraba lo real) y tramos que no cobran comisión (suave). - El backend manda. El formulario frena lo evidente antes de pegarle a la API (montos de hasta 2 decimales, porcentaje de hasta 4, nada negativo,
hasta >= desde), pero muestra por campo los errores del 422 y, anteFEE_TIER_OVERLAP, el mensaje con los tramos con los que choca, que además se marcan en la tabla (con texto, no solo con color). Los montos y el porcentaje se tratan como texto decimal exacto, nunca comofloat. Una edición manda solo lo que cambió y la pantalla siempre muestra lo que devuelve la respuesta (por ejemplo, que el tramo dejó de ser provisional). - Auditoría. Las cuatro acciones tienen etiqueta y un detalle legible en Auditoría («GT · de 100.01 a 500.00 · fijo 2.00 · 0.5 %»; en una edición, cada campo con su antes y su después).
Alternatives Considered
- Que Soterex mande el
fee(la D13 de ADR-012, como estaba). Pros: no hay motor, ya estaba construido. Contras: la especificación no lo manda, así que todo create según el contrato rebota; obliga a Soterex a conocer la comisión de CIS; y no cubre el requerimiento #2 de CIS-EC. Descartada: era la causa de una diferencia bloqueante. - Una tarifa única global (un porcentaje en la configuración de Soterex). Pros: es lo más chico. Contras: los números de Tesorería no son un porcentaje puro (2.500 y 2.600 pagan lo mismo) y el requerimiento pide una tabla por país. Descartada.
- Volver a poner
countries.commission_pct(un porcentaje por país). Pros: es una columna. Contras: es el campo que ADR-005 eliminó por no reflejar la realidad, y sigue sin cubrir ni el monto fijo ni los tramos. Descartada. - Derivar la comisión del tipo de cambio o de otra tabla existente. El tipo de cambio (
exchange_rates) convierte la moneda del pago, no tiene relación con lo que cobra CIS sobre el principal en USD. Descartada. - Una fórmula libre editable ("un monto fijo, un % o una fórmula", dice el requerimiento). Pros: máxima flexibilidad. Contras: guardar y evaluar expresiones de un usuario en una cuenta de plata es una superficie de riesgo, y los números del cliente se cubren con tramos de fijo más porcentaje. Descartada (YAGNI); si aparece una regla que los tramos no expresan, se reabre con el caso concreto.
- Tarifario con vigencia (
valid_from/valid_to) y versiones. Pros: permite programar un cambio de tarifas. Contras: complejidad sin un pedido. Como la comisión se congela en la transacción al crearla, el historial de lo cobrado no se pierde por desactivar un tramo y cargar otro. Descartada por ahora. - El tarifario en un archivo de configuración o en variables de entorno. Contra: cambiarlo exigiría un deploy y el Admin no podría cargar el de Tesorería. Descartada: es un dato de negocio que se edita desde la app (K8).
Consecuencias
- Positivo: SendRequest queda alineado con la especificación de Soterex (el request no lleva
fee; la respuesta lo devuelve) y se cierra una diferencia bloqueante del plan. - Positivo: se cubre el requerimiento #2 de CIS-EC (tabla por país, fijo, porcentaje o ambos) que estaba anotado como contradicción con ADR-005.
- Positivo: el cálculo es exacto y determinístico, y cambiar el tarifario no puede alterar el historial.
- Negativo: el tarifario real lo tiene que definir Tesorería (Teresa).
Hasta entonces, en producción todo SendRequest se rechaza con 2026.(Reemplazado el 2026-10-05: producción arranca con el provisional de 50 USD fijos y ya no rechaza por falta de tarifario, ver la actualización.) Cuando Tesorería lo defina, se carga desde Parámetros → Comisiones (K8): la pantalla y su API ya están (§6), y mientras el tarifario sea el provisional la propia pantalla lo avisa. - Negativo:
las comisiones del sandbox (1 %) no son las que se van a cobrar.(Reemplazado el 2026-10-05: el provisional son 50 USD fijos y rige también en producción.) El sign-off con Soterex dice que son provisionales y no definitivas. - Negativo: reintroduce un motor de comisiones y un módulo más que mantener, que ADR-005 había descartado.
- Neutral:
feesigue siendo información restringida, no aparece en las pantallas operativas, y sigue descontando solo de la Holding (ADR-007). No cambia ningún saldo ni ningún ledger. - Neutral: el contrato con Soterex cambia:
feesale del request (si llega, se ignora), 2016 y 2017 se retiran y aparece el rechazo 2026. K7 lo documenta en el sign-off, el OpenAPI y la collection. - Pendiente, fuera de este ADR: la segunda tabla que mencionó Tesorería —la comisión de CIS EC a CIS GT— sigue sin definirse (
doc/plans/2026-08-07-analisis-definiciones-cis-ec.md§2.2); este tarifario es el que aplica Soterex.
Actualización 2026-10-05: el provisional son 50 USD fijos, también en producción
Quién y cuándo. Carlos, el 2026-10-05, en el chat de trabajo de la ejecución del plan. Primero: «dejalo por ahora en 50 USD y que sea editable en la configuración por país», y al preguntarle si eso valía también para producción: «50 USD fijos, también sembrado en producción».
Qué cambia. El tarifario provisional de Guatemala pasa de «1 % del principal, solo fuera de producción» (D2b del plan, §5 de este ADR) a:
| Antes (D2b) | Ahora | |
|---|---|---|
| Tramo | min_amount 0,01, sin tope, fixed_fee 0, percent 1 | min_amount 0,01, sin tope, fixed_fee 50.00, percent 0 |
| Qué cobra | 1 % del monto (500.00 → 5.00) | 50.00 USD por transacción, para cualquier monto (0,01 → 50.00; 500.00 → 50.00; 9999999999.99 → 50.00) |
| Dónde se siembra | Solo fuera de producción | En todos los ambientes, producción incluida |
provisional y descripción | true, «PROVISIONAL — reemplazar por la tabla de Tesorería» | Igual: la pantalla de Comisiones muestra el aviso «PROVISIONAL» hasta que alguien edite el tramo |
| Editable | Por país, desde Parámetros → Comisiones (K8) | Igual |
| Producción sin tarifario | El alta se rechaza con 2026 | Solo si un Admin desactiva todos los tramos o deja un monto sin cubrir |
Cómo se implementa (sin cambiar los dos caminos ni su idempotencia): EnsureProvisionalFeeSchedule ya no mira el ambiente. Sigue sembrando solo si Guatemala no tiene ningún tramo (activo o inactivo), con el lock de fila FOR UPDATE; un tarifario real, un provisional editado o uno desactivado no se pisan ni se resucitan. Lo llaman la migración de datos 2026_10_05_100100_k1_tarifario_provisional_de_guatemala (las bases que ya existen) y CountrySeeder (una base nueva, y en producción el disparo manual que crea el país), y los dos convergen al mismo tramo. La lista blanca local/testing/staging de DeploymentEnvironment sigue valiendo para el endpoint del sandbox y el modo mock, pero ya no para esto: ningún valor de APP_ENV cambia qué se cobra.
Por qué. La integración con Soterex tiene que poder dar de alta una transacción desde el primer día, y Carlos prefiere un valor conocido y editable a rechazar todo hasta que Tesorería entregue la tabla. D2b prefería rechazar antes que cobrar «una comisión inventada»; esta decisión acepta cobrar una comisión provisional, explícita y visible, a cambio de no frenar la integración. El costo de esa elección es lo que sigue.
Efectos que hay que tener presentes.
- Una comisión mayor que el principal para montos menores a 50 USD. Un
SendRequestde 20.00 queda confee: "50.00". No se rechaza: niFeeCalculator(solo exige que la comisión entre endecimal(12,2)) nitransactions.fee(sinCHECKcontra el monto) la comparan con el principal, y no se agregó ninguna validaciónfee <= amount. Lo fija de punta a puntaComisionMayorQuePrincipalTest(alta, pago con y sin módulo Caja), que falla si alguien agrega esa validación sin decidirlo. Qué pasa con la plata al pagar esa transacción de 20.00: la Holding descuenta el principal más la comisión (70.00); el Prefondeo País y la caja descuentan solo el principal (ADR-005, ADR-007: la comisión nunca toca la caja); y sin módulo Caja la validaciónINSUFFICIENT_PREFUNDINGcompara solo el principal. Los reportes y el de Cumplimiento muestran «Total Amount w/fee» = 70.00 y los extractos de Tesorería,-(principal + comisión). No rompe nada: solo es raro de cara al negocio, y lo corrige Tesorería cargando tramos reales (por ejemplo, un fijo bajo para los montos chicos). - Ya no es cierto que, sin tarifario cargado, en producción todo
SendRequestda2026. Producción arranca con el provisional. El2026sigue existiendo en dos casos: un Admin desactiva todos los tramos del país (la pantalla lo avisa en rojo) o un monto queda sin cubrir (un hueco entre tramos, o un tope que el monto supera). Es lo que dicen el sign-off y el OpenAPI. - El ejemplo de la especificación de Soterex (500.00 → 5.00) ya no sale del tarifario sembrado: 500.00 da 50.00. El sign-off, el OpenAPI, la collection de Postman y sus ejemplos se reescribieron con
fee: "50.00". El payload de las notificacionesPAIDyCANCELLEDtrae la comisión guardada en la transacción ("50.00"). - Soterex tiene que saber que producción arranca con 50 USD fijos y que no es el tarifario definitivo. El sign-off lo dice así (secciones 1.1, 3.3 y 5). No promete avisarle antes de cambiarlo: es una decisión que no se tomó (ver
doc/integracion/2026-10-06-antes-de-mandar-el-sign-off.md). - Un tarifario provisional puede quedar cobrándose mucho tiempo. El aviso ámbar de Parámetros → Comisiones es la única señal: desaparece cuando se edita el tramo (cualquier valor) o se cargan los definitivos. El texto de ese aviso ya se actualizó (2026-10-05): dice que es el que se cobra, también en producción.
Alternativas que esta actualización descarta. Mantener D2b (producción rechaza hasta tener la tabla real): Carlos la descartó expresamente. Sembrar el 1 % también en producción: no era lo que pidió, y con montos chicos la comisión del 1 % es centavos. Un tope fee <= amount: nadie lo pidió y cambiaría el contrato que Soterex ve (un 2026 o un fee distinto según el monto); si hace falta, es una decisión nueva.
Lo que no cambia. Todo lo demás del ADR: el cálculo (§1), la tabla (§2), el fee fuera del request (§3), la comisión congelada al crear (§4) y el ABM (§6).

