Base del beneficio (base_amount)¶
Desde v1.6.0 (2026-11-16) el beneficio puede calcularse sobre una parte del ticket y no sobre el total del pago QR. Esta página describe cómo viaja el dato entre los sistemas, las reglas que aplica BeneficiosCenter y cómo se mantiene la compatibilidad con integradores que no lo envían. La decisión de diseño está en ADR-007; las reglas normativas, en el SPEC §5.5 del repositorio del sistema.
Qué problema resuelve¶
Hay promociones de medio de pago que apuntan a un medio que el POS no tiene. El descuento
corresponde solo a lo acumulado de los ítems que cumplen la promoción (una promo base), no al
total del ticket. El POS conoce ese acumulado; BeneficiosCenter no. El POS lo informa como
base_amount y BeneficiosCenter calcula el descuento sobre él. El total a pagar no cambia: el
descuento se resta del monto que se cobra por QR.
Una promo de medio de pago cuyo medio sí existe en la caja no es una promo base. La promo base se configura en el backend de promos, no en el POS.
Cómo viaja¶
sequenceDiagram
participant POS
participant RQ as RouterQR
participant GW as GatewayQR
participant BC as BeneficiosCenter
participant AUT as Autorizador TECSO
POS->>RQ: POST /trxpago + base_amount
RQ->>GW: reenvía el campo tal cual
GW->>BC: transaction.base_amount
BC-->>GW: benefits[].baseAmount y discountAmount
GW->>AUT: benefits_methods_data[].discount.base_amount + amount
AUT-->>GW: benefits_data.base_amount (eco)
Note over GW: audita el eco: WARN si difiere, nunca falla el pago
| Tramo | Dónde va base_amount |
|---|---|
| POS → RouterQR → GatewayQR | /trxpago, nivel superior, junto al importe. Solo si hay una promo base cumplida; si no hay, el campo se omite (no se envía null). El POS envía el mínimo entre lo acumulado y el monto QR. |
| GatewayQR → BeneficiosCenter | transaction.base_amount en el request del resolver, solo si está presente. |
| BeneficiosCenter → GatewayQR | baseAmount en cada beneficio (la base efectiva usada) y discountAmount calculado sobre ella. |
| GatewayQR → TECSO | benefits_methods_data[].discount.base_amount, con discount.amount ya calculado. TECSO no recalcula. |
| TECSO → GatewayQR | Eco en benefits_data.base_amount. El GatewayQR lo audita; una diferencia con la base enviada genera un WARN y nunca falla el pago. |
El RouterQR no tuvo cambios de código: reenvía el campo sin modificarlo.
Reglas en BeneficiosCenter¶
Fuente: BenefitResolver y SPEC §5.5.
- Base efectiva =
min(max(base_amount, 0), amount). Una base negativa no se rechaza: se trata como 0. Una base mayor al total se recorta al total. - Descuento =
min(base efectiva × porcentaje / 100, maxDiscountAmount), redondeado HALF_UP a dos decimales en un solo paso. Nunca supera el total. - Monto mínimo:
montoMinimose compara contra la base efectiva, no contra el total (mayor o igual). BASE_CERO: si el request informóbase_amounty la base efectiva es 0, el beneficio se descarta con ese motivo y no se ofrece (respuesta200conbenefits: []). Con base ausente no aplica: no se descarta aunque el descuento redondee a 0.- El desempate y la regla de que los beneficios nunca se suman no cambian: el ganador único por tipo de cliente se calcula sobre la base.
Dos reglas pendientes de confirmación del cliente
El mínimo evaluado contra la base y el descarte BASE_CERO frente a ofrecer un descuento de
0.00 son la postura vigente de la implementación, no una decisión cerrada por DINO
(ADR-007).
Ejemplo¶
Ticket de 4.500,02 a pagar por QR y una promo base que acumuló 2.750,00. Con un beneficio del
10 % sin tope, el POS envía base_amount = 2750.00 y BeneficiosCenter responde
baseAmount = 2750.00 y discountAmount = 275.00. Es el caso de la verificación de campo del
2026-11-16: con base 2750 el descuento fue 275,00 (10 % de la base) y el control sin base fue
450,00 (10 % de 4.500,02).
Request y response¶
Request (campo opcional):
{
"requestId": "GW-20261116-000123",
"transaction": { "datetime": "2026-11-16T11:20:00-03:00", "amount": 4500.02, "currency": "ARS",
"base_amount": 2750.00 },
"merchant": { "branchId": "SUC-014", "posId": 7, "salesPointId": 3 },
"invoice": { "type": "B", "taxIdKind": "CUIL", "taxId": "27123456784", "extraCustomerTypeId": null }
}
Response (cada beneficio trae baseAmount):
{
"requestId": "GW-20261116-000123",
"benefits": [
{ "customerTypeCode": "DINI_NEGOCIOS", "paymentMethodId": "990", "type": "DISCOUNT",
"percentage": 10.0, "discountAmount": 275.00, "baseAmount": 2750.00, "benefitId": 41,
"description": "Jueves Dini Negocios 10%", "maxDiscountAmount": null }
]
}
En el request el nombre de wire es base_amount (snake_case), aunque el resto de los campos del
resolver usan camelCase; en la respuesta es baseAmount. Detalle de campos en
API de resolución; campos hacia el autorizador en
Contrato con el autorizador.
Compatibilidad¶
transaction.base_amountes opcional. Ausente onullequivale a la base igual al total.- Sin
base_amountla salida es la anterior; el único cambio visible esbaseAmount: nullen cada beneficio. Un cliente que ignora campos desconocidos no se ve afectado. - El campo es aditivo en todas las capas: cada una tolera que la anterior todavía no lo envíe, y
sin el POS nuevo nadie envía
base_amount, así que el sistema vuelve al cálculo sobre el total.
Auditoría y diagnóstico¶
No hay columna ni migración en BeneficiosCenter: la base cruda queda en consulta.request_json
(la clave base_amount no figura si el request no la trajo) y la base efectiva por beneficio en
consulta.response_json (baseAmount, null si no se informó). En la consola, Auditoría
permite encontrar la consulta por requestId; un descarte BASE_CERO aparece entre las
evaluaciones de la consulta. Del lado del GatewayQR, la tabla trx guarda base_amount (nulo si
el POS no lo envió).
No hay propiedades nuevas en application.yml ni migraciones Flyway en v1.6.0: alcanza con
reemplazar el jar. El orden completo de despliegue entre sistemas está en
Despliegue.
Qué cambió en cada sistema¶
| Sistema | Versión | Cambio |
|---|---|---|
| BeneficiosCenter | v1.6.0 | base_amount opcional en TransactionDto / ResolutionRequest; BenefitResolver calcula sobre la base efectiva; baseAmount en BenefitDto / ResolvedBenefit; MotivoDescarte.BASE_CERO; en la consola, tipo baseAmount y corrección de lint en MultiSelect. |
| GatewayQR | v20261116 | Columna base_amount (nullable DECIMAL(13,2)) en trx y trx_aud; reenvío al resolver; discount.base_amount hacia TECSO; lectura y auditoría del eco. Script de base de datos: releases/20261001/db-migracion-base_amount.sql. |
| POS DINO | 20261116F | Acumula los ítems de las promos base y agrega base_amount al /trxpago. POS_MAIN.EXE y las 16 POS_*.DLL se reemplazan juntas. |
| RouterQR | sin cambios | Reenvía el campo tal cual (verificado con tráfico real). |
| TECSO | — | Recibe discount.base_amount y el amount ya calculado; no recalcula. |
Criterios de aceptación y verificación¶
Los criterios AC-68 a AC-76 están en la Matriz de aceptación. La verificación de campo del 2026-11-16 se corrió por la red real (POS DINO 20261116F, GatewayQR v20261116, BeneficiosCenter v1.6.0) y se repitió sobre el binario final de entrega.
Dónde sigue¶
- Historial de versiones, en Versiones.
- Los términos nuevos (promo base, base efectiva, eco del autorizador), en el Glosario.
- La cadena completa POS → RouterQR → GatewayQR → BeneficiosCenter → TECSO, en Arquitectura del sistema.