Valores numéricos (string)
Expresa todos los valores financieros en Fees Engine como
string con el tipo numeric. Esto ofrece manejo de decimales de alta precisión para activos como BRL o BTC. También previene errores de redondeo durante cálculos, divisiones o exenciones.
Importante
- Requerido: Midaz v3.x.x (usa
numeric). - Incompatible: Midaz v2.x.x (formato obsoleto
amount+scale).
Períodos de facturación
Al activar un cálculo de facturación, especificas la ventana de tiempo a través del campo
period. Fees Engine soporta tres formatos:
El motor usa el período para contar transacciones que califican (para paquetes de volumen) o cuentas activas (para paquetes de mantenimiento) dentro de esa ventana exacta.
Elige la granularidad que coincida con tu ciclo de facturación. Un producto de tarjeta prepago facturado diariamente usaría
2026-03-15. Una plataforma SaaS facturada mensualmente usaría 2026-03. Un marketplace que liquida semanalmente usaría 2026-W13.
Reglas de cálculo de tarifas
Cada tarifa usa una
applicationRule para definir cómo se calcula. Puedes elegir entre tres tipos de reglas:
Puedes combinar diferentes reglas en un solo paquete para ajustarse a tu caso de uso.
Otros campos clave:
isDeductibleFrom: define si la tarifa se deduce del remitente o del receptor.referenceAmount: ya seaoriginalAmountoafterFeesAmount.priority: define el orden de aplicación. La prioridad 1 siempre debe usaroriginalAmount.
maxBetweenTypes
Aplica el mayor valor entre: una tarifa fija o una basada en porcentaje. Ejemplo- Valor de tarifa fija: R$5.
- Tarifa porcentual: 2%.
- Monto de referencia: R$1,000.
flatFee
Aplica un monto de tarifa fijo. El comportamiento depende deisDeductibleFrom.
Ejemplo
- Tarifa fija: R$15.
- Monto de referencia: R$115.
percentual
Aplica una tarifa como porcentaje del monto de referencia. Ejemplo- Valor: 30%.
- Monto de referencia: R$ 389.50.
División de tarifas
Cuando una transacción tiene múltiples cuentas de origen, el Fees Engine divide las tarifas proporcionalmente.
Ejemplo
- Monto total: R$4,000.00
- Tarifa fija: R$15.00
- Impuesto: 4%
isDeductibleFrom: false
Porcentaje de participación
Fórmula: (Monto de Cuenta ÷ Monto Total) × 100
Distribución de tarifa fija
Fórmula: Tarifa fija × participación %
Impuesto proporcional
Fórmula: monto de cuenta × impuesto %
Monto final por cuenta
Fórmula: principal + tarifa + impuesto
Validaciones
- Total de participaciones = 100%
- División de tarifa coincide con tarifa fija
- División de impuesto = 4%
- Total enviado = R$ 4,175.00
Exenciones de tarifas: reglas y jerarquía
Por monto de transacción
UsaminimumAmount y maximumAmount para definir cuándo deben aplicarse las tarifas.
Por ejemplo: Si el rango es R 301 no activará tarifas.
Por cuenta
El sistema verificawaivedAccounts. Una fuente en esa lista está exenta de tarifas.
Ejemplo mixto: exenciones de tarifas y división proporcional de tarifas
Veamos un ejemplo de un paquete que incluye cuentas con exenciones de tarifas y requiere dividir las tarifas proporcionalmente.
Escenario
Estamos procesando una transacción de R$ 4,000, que incluye:- Una tarifa fija de R$ 16.
- Solo algunas cuentas están sujetas a la tarifa fija
- Un impuesto IOF del 6% a deducir.
División en el lado de origen
El motor aplica la tarifa fija solo a
@account3 y @account4.
Resultado después de Tarifa Administrativa (proporcional)
El valor total de envío aumenta a R$4,016.
Deducción de IOF (destinatario)
El motor acredita las tarifas en las cuentas definidas en el
creditAccount de cada tarifa.Decimales repetidos
Cuando una división de tarifa produce un decimal periódico (por ejemplo, 0.3333…), el Fees Engine mantiene cada línea de tarifa con precisión completa. Reconcilia el pequeño resto en la tarifa de la cuenta con el mayor valor. Esto mantiene el total exacto, evita la deriva por redondeo y mantiene tu ledger consistente.
Cálculos de facturación
Los billing packages usan un modelo de cálculo diferente al de los fee packages. En lugar de evaluar transacciones individuales, agregan datos durante un período de facturación y devuelven payloads de cargo para que tu orquestador los ejecute. La facturación soporta tres formatos de período: mensual (
YYYY-MM), semanal (YYYY-Www, ej., 2026-W13) y diario (YYYY-MM-DD).
Cálculo de facturación por volumen
La facturación por volumen cuenta transacciones que coinciden con uneventFilter (ruta de transacción + estado) dentro del período de facturación, luego aplica precios según el modelo configurado.
El cálculo sigue este orden:
- Contar transacciones que califican en el período.
- Restar el
freeQuotadel conteo total. - Aplicar precios según el
pricingModel(tieredofixed). - Aplicar descuentos de
discountTierssi el volumen total alcanza algún umbral.
Precios escalonados
Cada nivel define un rango de cantidad y un precio unitario. El motor aplica el precio correspondiente para cada unidad dentro de cada rango. Ejemplo: Un billing package para emisión de boletos con tres niveles y una cuota gratuita de 50:
Para un cliente que emitió 1,800 boletos en el mes:
- 50 exentos (cuota gratuita)
- 1,750 facturables: 500 × R$ 1.20 + 1,250 × R$ 0.80 = R$ 1,600.00
- Se aplica nivel de descuento (> 1,000 boletos → 5%): −R$ 80.00
- Total: R$ 1,520.00
Precio fijo
Un solo precio unitario se aplica a todas las transacciones facturables independientemente del volumen. El motor aún resta la cuota gratuita antes del cálculo. Ejemplo: R$ 0.10 por Pix enviado, sin cuota gratuita:- 5,000 transacciones Pix × R$ 0.10 = R$ 500.00
Modos de conteo
El campocountMode define cómo el motor agrupa las transacciones:
perRoute— Cuenta todas las transacciones coincidentes en la organización como un total único.perAccount— Cuenta transacciones por cuenta individual y aplica precios de forma independiente a cada una.
Cálculo de facturación de mantenimiento
La facturación de mantenimiento cobra un monto fijo por cuenta activa en el período de facturación. El motor resuelve las cuentas objetivo, filtra por estado activo y genera un único payload de transacción. El resultado es una transacción N:1:- Cada cuenta activa aparece como una entrada de débito (
source.from) por elfeeAmountconfigurado. - La
maintenanceCreditAccountrecibe el total completo como una única entrada de crédito (distribute.to).
- 12,000 entradas en
source.from, cada una debitada R$ 9.90 - 1 entrada en
distribute.toacreditada R$ 118,800.00
Política de fallo todo-o-nada
Si algún billing package falla durante una llamada a/billing/calculate, toda la operación falla. El motor no devuelve resultados parciales. La respuesta incluye qué paquete y recurso causó el fallo, para que puedas corregir y re-ejecutar.