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 para obtener el conteo facturable. - Aplicar precios según el
pricingModel(tieredofixed). - Aplicar un descuento de
discountTiers, evaluado contra el conteo total (antes de restar la cuota gratuita).
Precios escalonados
Los precios escalonados son precios por volumen, no precios graduados. El motor encuentra el único nivel cuyo rango de cantidad contiene el conteo facturable y luego cobra cada unidad facturable al precio unitario de ese nivel. No aplica el precio de cada rango a las unidades que caen dentro de él. El rango de un nivel es inclusivo en ambos extremos. Si omites el límite superior, el nivel queda sin tope. El motor busca un nivel solo cuando el conteo facturable es positivo. Si el conteo facturable es positivo y ningún nivel lo cubre, el cálculo falla para ese paquete. Un conteo facturable de cero omite la búsqueda de nivel y produce un monto cero, así que tus niveles no necesitan cubrir el cero. 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
- 1,750 cae en el nivel 501–2,000, así que todas las 1,750 unidades se cobran a R$ 0.80: R$ 1,400.00 bruto
- Se aplica el nivel de descuento sobre el conteo total de 1,800 (≥ 1,000 → 5%): −R$ 70.00
- Total neto: R$ 1,330.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. El precio fijo toma su precio unitario del primer nivel del paquete, así que un paquete fijo debe declarar al menos un nivel — de lo contrario el cálculo falla. Ejemplo: R$ 0.10 por Pix enviado, sin cuota gratuita:- 5,000 transacciones Pix × R$ 0.10 = R$ 500.00
Niveles de descuento
Se aplica como máximo un nivel de descuento: el que tiene elminQuantity más alto que el conteo total alcanza o supera. Su porcentaje se aplica al monto bruto. Los descuentos se evalúan contra el conteo total de transacciones, no contra el conteo facturable.
Alcance del conteo
El cálculo por volumen cuenta transacciones por ruta de transacción en todo el ledger. La cuota gratuita, los niveles y los niveles de descuento se aplican a ese total por ruta. Para contar dos flujos por separado, crea un paquete por ruta de transacción.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, conserva solo las activas 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).
active; cualquier otro estado queda excluido. Si no se resuelve ninguna cuenta, el paquete devuelve un payload vacío ({}) en lugar de una transacción.
Ejemplo: Mantenimiento mensual de R$ 9.90 para un segmento con 12,000 cuentas PF activas:
- 12,000 entradas en
source.from, cada una debitada R$ 9.90 - 1 entrada en
distribute.toacreditada R$ 118,800.00
Resultados con monto cero
Cuando el monto neto de un paquete resulta cero — por ejemplo, si la cuota gratuita cubrió todas las transacciones — el motor aún devuelve un resultado para ese paquete, pero con un payload de transacción vacío ({}). Interprétalo como “procesado, nada que enviar”.
El uso totalmente exento llega a este resultado sin una búsqueda de nivel. La cuota gratuita lleva el conteo facturable a cero, el motor omite la coincidencia de niveles y el monto es cero. Un paquete cuyos niveles empiezan en 1 es correcto para este caso.
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.
Metadatos de auditoría
Cada resultado de cálculo de facturación incluye metadatos estructurados para trazabilidad. Los resultados de volumen incluyen el tipo de facturación, el id y la etiqueta del paquete, el período, los conteos de eventos totales y facturables, la cuota gratuita utilizada, el modelo de precios, los montos bruto y neto, y el detalle del descuento (porcentaje, monto yminQuantity) cuando se aplicó alguno. Los resultados de mantenimiento incluyen el tipo de facturación, el id y la etiqueta del paquete, el período, el conteo total de cuentas y el monto de la tarifa por cuenta.