Valores numéricos (string)
Expresa todos los valores financieros en Fees Engine como un
string con el tipo numeric. Esto brinda manejo decimal de alta precisión para activos como BRL o BTC. También evita errores de redondeo durante los cálculos, las divisiones o las exenciones.
Ejemplo:
Períodos de facturación
Al activar un cálculo de facturación, especificas la ventana de tiempo mediante el campo
period. Fees Engine admite tres formatos:
El motor usa el período para contar las transacciones que califican (para paquetes de volumen) o las 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 a diario 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 comisiones
Cada comisión usa un
applicationRule para definir cómo se calcula. Puedes elegir entre tres tipos de regla:
Puedes combinar distintas reglas en un mismo paquete para adaptarte a tu caso de uso.
Otros campos clave:
isDeductibleFrom: define si la comisión se deduce del remitente o del destinatario.referenceAmount: puede seroriginalAmountoafterFeesAmount.priority: define el orden de aplicación. La prioridad 1 siempre debe usaroriginalAmount.
maxBetweenTypes
Aplica el valor que sea mayor: una comisión fija o una basada en porcentaje. Ejemplo- Valor de la comisión fija: R$5.
- Comisión porcentual: 2%.
- Monto de referencia: R$1,000.
flatFee
Aplica un monto de comisión fijo. El comportamiento depende deisDeductibleFrom.
Ejemplo
- Comisión fija: R$15.
- Monto de referencia: R$115.
percentual
Aplica una comisión como porcentaje del monto de referencia. Ejemplo- Valor: 30%.
- Monto de referencia: R$ 389.50.
División de comisiones
Cuando una transacción tiene varias cuentas de origen, Fees Engine divide las comisiones de forma proporcional.
Ejemplo
- Monto total: R$4,000.00
- Comisión fija: R$15.00
- Impuesto: 4%
isDeductibleFrom: false
% de participación
Fórmula: (Monto de la cuenta ÷ Monto total) × 100
Distribución de la comisión fija
Fórmula: fixed Fee × participation %
Impuesto proporcional
Fórmula: account amount × tax %
Monto final por cuenta
Fórmula: principal + fee + tax
Validaciones
- El total de participaciones = 100%
- La división de la comisión coincide con la comisión fija
- La división del impuesto = 4%
- El monto total enviado = R$ 4,175.00
Exenciones de comisiones: reglas y jerarquía
Por monto de transacción
UsaminimumAmount y maximumAmount para definir cuándo deben aplicarse las comisiones.
Por ejemplo: si el rango es R 301 no generará comisiones.
Por cuenta
El sistema verificawaivedAccounts. Una cuenta de origen en esa lista está exenta de comisiones.
Ejemplo mixto: exenciones de comisiones y división proporcional de comisiones
Este paquete incluye cuentas con exenciones de comisiones y requiere dividir las comisiones de forma proporcional.
Escenario
Estamos procesando una transacción de R$ 4,000, que incluye:- Una comisión fija de R$ 16.
- Solo algunas cuentas están sujetas a la comisión fija
- Un impuesto IOF de 6% que se debe deducir.
División en el lado de origen
El motor aplica la comisión fija solo a
@account3 y @account4.
Resultado después de la comisión administrativa (proporcional)
El valor total enviado aumenta a R$4,016.
Deducción de IOF (destinatario)
El motor acredita las comisiones a las cuentas definidas en el
creditAccount de cada comisión.Decimales periódicos
Cuando una división de comisión produce un decimal periódico (por ejemplo, 0.3333…), Fees Engine mantiene cada tramo de la comisión con precisión completa. Reconcilia el pequeño resto en la comisión de la cuenta con el valor más alto. Esto mantiene el total exacto, evita desviaciones por redondeo y mantiene tu ledger consistente.
Cálculos de facturación
Los paquetes de facturación usan un modelo de cálculo distinto al de los paquetes de comisiones. En lugar de evaluar transacciones individuales, agregan datos durante un período de facturación y devuelven payloads de cobro para que tu orquestador los ejecute. La facturación admite tres formatos de período: mensual (
YYYY-MM), semanal (YYYY-Www, por ejemplo, 2026-W13), y diario (YYYY-MM-DD).
Cálculo de facturación por volumen
La facturación por volumen cuenta las transacciones que coinciden con uneventFilter (ruta de transacción + estado) dentro del período de facturación y luego aplica precios según el modelo configurado.
El cálculo sigue este orden:
- Contar las 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 graduales. 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 calcula el precio de cada unidad dentro de su propio rango. El rango de un nivel es inclusivo en ambos extremos. Si omites el límite superior, el nivel no tiene límite. 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, por lo que tus niveles no necesitan cubrir el cero. Ejemplo: Un paquete de facturación para la 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, por lo que todas las 1,750 unidades se cobran a R$ 0.80: R$ 1,400.00 bruto
- El nivel de descuento se aplica sobre el conteo total de 1,800 (≥ 1,000 → 5%): −R$ 70.00
- Total neto: R$ 1,330.00
Precios fijos
Un único precio unitario se aplica a todas las transacciones facturables, sin importar el volumen. El motor igual resta la cuota gratuita antes del cálculo. Los precios fijos toman su precio unitario del primer nivel del paquete, por lo que un paquete fijo igual 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
Como máximo se aplica un nivel de descuento: el que tiene elminQuantity más alto que el conteo total alcanza o supera. El motor aplica su porcentaje al monto bruto. Los descuentos se evalúan contra el conteo total de transacciones, no contra el conteo facturable.
Ámbito de conteo
El cálculo por volumen cuenta las transacciones por ruta de transacción en todo el ledger. La cuota gratuita, los niveles y los niveles de descuento se aplican todos a ese total en el nivel de 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 cada 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 un asiento de débito (
source.from) por elfeeAmountconfigurado. - El
maintenanceCreditAccountrecibe el total completo como un único asiento de crédito (distribute.to).
active y excluye cualquier otro estado. 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 asientos en
source.from, cada uno debitado por R$ 9.90 - 1 asiento en
distribute.toacreditado por R$ 118,800.00
Resultados de monto cero
Cuando el monto neto de un paquete resulta en cero (por ejemplo, la cuota gratuita cubrió todas las transacciones), el motor igual devuelve un resultado para ese paquete, pero con un payload de transacción vacío ({}). Trata esto 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 paquete de facturación falla durante una llamada a/billing/calculate, toda la operación falla. El motor no devuelve resultados parciales. La respuesta incluye qué paquete y qué recurso causaron el fallo, para que puedas corregirlo y volver a ejecutarlo.
Metadatos de auditoría
Cada resultado de cálculo de facturación lleva 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 usada, el modelo de precios, los montos bruto y neto, y el detalle del descuento (porcentaje, monto yminQuantity) cuando se aplicó uno. 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 comisión por cuenta.