base_amount — beneficio sobre un monto base acumulado

Visión general del concepto, de punta a punta · DINI/DINO · Tipre · 12/10/2026 · BORRADOR

1. La idea en una frase

Hoy el beneficio se calcula como un % del total del ticket. La idea es calcularlo sobre un monto base (base_amount) que define el negocio vía promociones, no sobre el total. El cliente paga lo mismo menos el descuento; cambia sobre qué se calcula ese descuento.

Ejemplo. Ticket de $1.000. El negocio quiere que el 10% de beneficio aplique solo sobre ciertos productos que suman $300. Entonces el descuento es 10% de $300 = $30 (no 10% de $1.000). El cliente paga $970.

2. Por qué

Promos dirigidas: permite premiar categorías/productos puntuales sin descontar todo el ticket.
El negocio decide el alcance desde la configuración de promociones del POS, sin tocar código.
Retrocompatible por defecto: sin base_amount, el beneficio se calcula sobre el total — el comportamiento actual no cambia.

Opciones de comportamiento que proponemos (detalle en §5):

Sin base_amount (ausente) → beneficio sobre el total del ticket. Es el comportamiento de hoy.
Con base_amount (> 0) → beneficio sobre esa base (los ítems de la promo).
base_amount = 0 → sin beneficio. propuesta a confirmar por el cliente para el caso "la promo base está configurada pero no acumuló ítems". El server ya lo soporta; requiere un cambio del POS (ver §5). No aprobado aún.

3. Cómo funciona, de punta a punta

Cinco actores, cada uno con un rol claro:

Actor	Rol en base_amount
POS	Calcula el monto base acumulando las promociones que correspondan y lo envía. Nunca aplica el descuento él mismo.
RouterQR	Relaya el dato (transparente).
GatewayQR	Lleva `base_amount` al resolvedor y se lo informa al autorizador.
BeneficiosCenter	Calcula el beneficio: % sobre el monto base (con tope y mínimo), sin cambiar el total.
TECSO (autorizador)	Aplica el descuento y lo confirma; el POS lo imputa y reparte el IVA.

Secuencia del pago QR con beneficio sobre monto base (ida y vuelta).

4. El dato nuevo: `base_amount`

Qué es: el monto (en pesos) sobre el que se calcula el beneficio. Lo produce el POS.
De dónde sale: de promociones que el POS computa pero nunca cobra — suman un acumulado que viaja como base_amount. (El detalle de configuración está en el doc técnico.)
Cómo viaja: POS → RouterQR → GatewayQR → BeneficiosCenter; y al autorizador dentro del descuento.
Si no viene (ausente): el beneficio se calcula sobre el total, como hoy.
Si viniera en 0: no aplica ningún beneficio (BASE_CERO). El server lo soporta; cuándo el POS envía 0 es un punto abierto — ver §5.

5. Reglas que importan

Regla	Qué significa
Cálculo	`descuento = mín( base × % , tope )`.
Tope por el monto QR	El monto base nunca supera lo que se paga por QR → el descuento nunca deja el pago en negativo.
Monto mínimo	El mínimo del beneficio se evalúa contra el monto base (no contra el total).
Default (ausente)	Sin `base_amount` → se usa el total (comportamiento actual). Pensado para promos clásicas sobre todo el ticket.
base = 0 (si se enviara)	Si el POS enviara `base_amount = 0` → no se ofrece ningún beneficio (motivo `BASE_CERO`). El server ya lo soporta; ver el punto abierto abajo sobre cuándo el POS lo envía.
Un beneficio por medio de pago	Nunca se suman beneficios; se elige uno (sin cambios respecto de hoy).
El total no cambia	El descuento se resta de lo que se cobra; el ticket sigue valiendo lo mismo.

Ausente ≠ 0 — la distinción clave (lado server)
El resolver distingue dos señales:

base_amount ausente → el beneficio se calcula sobre el total del ticket.
base_amount = 0 → no aplica ningún beneficio (BASE_CERO). Implementado y verificado.

Punto abierto — comportamiento del POS cuando una promo base acumula 0
Hoy el POS omite base_amount en dos casos: (a) no hay promo base aplicable, y (b) hay una promo base configurada pero no acumuló ítems (requiere iAcuPromos>0; verificado en pos_tic2.cpp). Como "ausente" cae al total, hoy el caso (b) termina en beneficio sobre el total — lo contrario a la intención de negocio de "si no acumula, no aplica".

Para que (b) no dé beneficio, el POS tendría que enviar base_amount = 0 cuando existe una promo base configurada aunque no haya acumulado. Eso es un cambio en el POS (pos_tic2.cpp + rebuild + regresión), no del server (el server ya lo soporta). Es una idea propuesta, pendiente de confirmación del cliente que solicita el desarrollo — no está aprobada ni implementada. El comportamiento vigente es el descripto arriba (hoy (b) → beneficio sobre el total).

6. La vuelta: descuento e IVA

El autorizador confirma el descuento aplicado. El POS lo recibe e imputa el descuento repartiéndolo sobre todo el ticket (de forma proporcional por alícuota de IVA), de modo que lo informado al fisco cierra contra lo cobrado. El cálculo del beneficio usa el monto base; el reparte fiscal es sobre el ticket completo — son dos cosas distintas y así queda validado.

7. Estado y alcance

Concepto / contratoDefinido y coordinado entre las sesiones POS y server.

POSBuild de prueba ya emite base_amount; falta el E2E real y el build de prod.

Server (GW + BeneficiosCenter)Implementado y verificado con tests + E2E de server (rama aislada, sin tocar producción).

Todo este cambio se desarrolla aparte del release en QA; no afecta lo que ya está en producción. El formato del campo quedó confirmado entre POS y server. Falta la prueba de punta a punta con el POS real (build de prod).

Para profundizar: el circuito técnico completo (configuración del POS, tablas, wire, cálculo del server y reparto de IVA) está en docs/base-amount-circuito-completo.html. El contrato con el autorizador, en docs/Beneficios-contrato-autorizador.html.

base_amount · visión general · 12/10/2026 · Tipre. Documento de concepto; sujeto a confirmación de la prueba de punta a punta.