Saltar a contenido

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.

  1. 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.
  2. Descuento = min(base efectiva × porcentaje / 100, maxDiscountAmount), redondeado HALF_UP a dos decimales en un solo paso. Nunca supera el total.
  3. Monto mínimo: montoMinimo se compara contra la base efectiva, no contra el total (mayor o igual).
  4. BASE_CERO: si el request informó base_amount y la base efectiva es 0, el beneficio se descarta con ese motivo y no se ofrece (respuesta 200 con benefits: []). Con base ausente no aplica: no se descarta aunque el descuento redondee a 0.
  5. 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_amount es opcional. Ausente o null equivale a la base igual al total.
  • Sin base_amount la salida es la anterior; el único cambio visible es baseAmount: null en 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.