Skip to main content
El Fees Engine forma parte de la familia de productos Midaz. Es un servicio de cálculo. Tu aplicación le pide calcular las tarifas de una transacción, y devuelve el resultado para que tu aplicación lo registre. Lee de Midaz pero nunca escribe en el ledger. Lo despliegas de forma independiente, y lo habilitas u omites según tu caso de uso. A diferencia de CRM, funciona bajo la licencia Enterprise. Cada versión del chart corresponde a versiones específicas de Midaz Core en la tabla de compatibilidad de versiones.
Prueba el Fees Engine localmenteEjecuta los plugins de Lerian sin desplegar en Kubernetes usando nuestro repositorio plugins-docker-compose.Estos servicios requieren una licencia válida para ejecutarse. Sin ella, la aplicación no inicia. Para detalles de licencia, consulta nuestra documentación de Licencia.

​
¿Por qué usar Fees Engine?

El Fees Engine te ayuda a gestionar lógica compleja de tarifas. Aplica tarifas fijas, distribuye tarifas proporcionalmente y estima transacciones antes de que las ejecutes. Esto es lo que desbloquea:
  • Configuración flexible de tarifas a través de paquetes de tarifas—adaptados a grupos de cuentas o Ledgers específicos.
  • Múltiples métodos de cálculo: tarifas fijas, tasas porcentuales y lógica “máximo entre tipos”.
  • Distribución proporcional de tarifas para flujos de marketplace y operaciones de múltiples cuentas.
  • Soporte para rutas contables mediante transactionRoute, routeFrom y routeTo.
  • Herramientas de estimación para previsualizar cálculos antes de ejecutar transacciones.
  • Lógica de exención de tarifas por cuenta y rangos de valor de transacción.
  • Aplicación basada en prioridad para controlar el orden de múltiples tarifas.
  • Mecánicas precisas de deducción con soporte de isDeductibleFrom.
  • Facturación basada en volumen a través de billing packages — cobra según el conteo acumulado de transacciones por período (diario o mensual).
  • Facturación de mantenimiento para cargos recurrentes por cuenta, segmentando cuentas por segmento, portfolio o lista explícita.
  • Cuotas gratuitas y descuentos progresivos para modelar precios escalonados e incentivos por volumen.
  • Exenciones basadas en segmento para eximir grupos enteros de cuentas de fee packages sin listar cuentas individuales.
Fees Engine forma parte de Midaz, desplegado como un servicio independiente y disponible bajo la licencia Enterprise. Si deseas obtener más información o evaluarlo para tu caso de uso, contacta a nuestro equipo.

​
¿Qué son las tarifas?

Las tarifas son valores monetarios cobrados a cambio de servicios, productos o acceso a recursos. Su propósito depende de la industria, pero la necesidad de claridad y consistencia es universal. A continuación, algunos ejemplos:

​
Finanzas

En el sector financiero, las tarifas cubren costos operacionales y respaldan el cumplimiento legal.
  • Tarifa de mantenimiento de cuenta: Mantiene las cuentas operativas y cubre costos administrativos.
  • Tarifa de transferencia: Se aplica a transacciones como TEDs o transferencias internacionales.

​
Logística y transporte

En el sector logístico, las tarifas cubren servicios de transporte y almacenamiento.
  • Tarifa de manejo: Se aplica durante el almacenamiento y movimiento físico de mercancías.
  • Tarifa de descarga: Cubre operaciones de descarga en puntos de entrega.

​
Farmacéutica y salud

En el sector farmacéutico, las tarifas garantizan la calidad y regulación de los servicios.
  • Tarifa de registro de medicamentos: Relacionada con aprobaciones regulatorias y entrada al mercado.
  • Tarifa de análisis de laboratorio: Cubre costos de pruebas y control de calidad.

​
Agrícola

En el sector agrícola, las tarifas cubren procesos de comercialización y regulatorios.
  • Tarifa de inspección sanitaria: Garantiza cumplimiento de salud para exportaciones agrícolas.
  • Tarifa de exportación agrícola: Cubre costos administrativos y regulatorios de exportación.

​
Paquetes de Tarifas

Un Paquete de Tarifas define cómo el motor aplica tarifas a una transacción. Agrupa una o más reglas de tarifas. Lo personalizas por segmento, Ledger y rutas contables. Puedes crear diferentes paquetes para diferentes productos, tipos de transacción o segmentos de clientes. Cada paquete tiene su propia lógica de cálculo, configuración de rutas y reglas de prioridad. Un paquete incluye campos obligatorios y puede agregar campos opcionales de coincidencia o exención:
  • ledgerId – El Ledger que registra la transacción y sus tarifas.
  • transactionRoute – La ruta contable principal para la transacción, para coincidencia por ruta.
  • segmentId – El producto o segmento al que se aplica el paquete, para coincidencia por segmento.
  • waivedAccounts – Cuentas a eximir de tarifas, cuando configuras exenciones.
  • fees – Un mapa de reglas de tarifas individuales, cada una incluyendo:
    • priority – Define el orden de ejecución.
    • routeFrom y routeTo – Rutas contables personalizadas para la tarifa.
    • isDeductibleFrom – Si el motor deduce la tarifa del monto original.
    • referenceAmount – El monto base para cálculos.
El Fees Engine requiere configuración de ruta explícita para cada tarifa y dirección (por ejemplo, débito o crédito).

​
Reglas de validación

Para garantizar consistencia y prevenir errores de configuración, Fees Engine aplica las siguientes reglas:
  • La prioridad de tarifa debe ser única dentro de un paquete.
  • Las tarifas con isDeductibleFrom: true deben usar referenceAmount: originalAmount.
  • Las tarifas con prioridad 1 también deben usar referenceAmount: originalAmount.
  • Campos como organizationId, ledgerId y creditAccount deben existir en Midaz. Fees Engine los valida con el endpoint Recuperar una Cuenta por Alias.
Asegúrate de que tu configuración cumpla con los últimos estándares de Midaz. Fees Engine valida cada paquete y transacción contra ellos. Revisa las reglas para ledgerId, creditAccount y referenceAmount, además de campos opcionales de coincidencia como segmentId cuando los configuras.

​
Elegir el endpoint correcto: calculate vs. estimate

Fees Engine proporciona dos endpoints para aplicar tarifas. Se comportan de manera diferente según el control que necesitas:

​
Calcular tarifas para un paquete

  • Obtiene automáticamente todos los paquetes disponibles para la organización y Ledger dados.
  • Elige la mejor coincidencia basada en el contexto de la transacción.
  • Aplica las reglas de tarifas correspondientes.
  • Si no hay paquete coincidente, el motor no aplica tarifas.

​
Estimar comisión por Transacción

  • Estima tarifas para un paquete específico por su packageId.
  • Devuelve tarifas calculadas solo si la transacción coincide con las condiciones del paquete.
  • Útil para pruebas, depuración o una vista previa de tarifas, sin escribir en el Ledger.
Usa calculate cuando quieras que el motor decida qué paquete aplicar. Usa estimate cuando quieras control total sobre qué paquete probar.

​
Exenciones basadas en segmento

Los fee packages soportan la exención de cuentas individuales mediante waivedAccounts. También puedes referenciar un segmentId para eximir a un grupo completo de cuentas de una sola vez. Usa exenciones basadas en segmento cuando:
  • Un nivel de cliente (como cuentas premium) está universalmente exento de una tarifa.
  • Las cuentas internas o de socios pertenecen a un segmento existente en Midaz.
  • Mantener una lista de aliases de cuentas individuales es impráctico a escala.
Fees Engine resuelve las exenciones basadas en segmento en el momento del cálculo. Cuando las cuentas se unen o abandonan el segmento, el cambio surte efecto en el siguiente cálculo. No actualizas el paquete.

​
Billing Packages

Los Billing Packages calculan cargos a partir del volumen acumulado de transacciones durante un período — diario o mensual. Los fee packages cobran por transacción individual. Los billing packages cuentan las transacciones que califican y devuelven payloads para que tu orquestador los ejecute. Hay dos tipos disponibles:
  • Volume — cobra según la cantidad de transacciones que coinciden con un filtro de eventos en el período.
  • Maintenance — cobra una tarifa fija recurrente por cuenta activa, una vez por período de facturación.
Los billing packages son un motor de cálculo, no una plataforma de facturación. El motor calcula los cargos y devuelve los payloads. Tu orquestador — Flowker, un cron job, o cualquier otro invocador — ejecuta los cargos reales contra Midaz.

​
Paquetes de volumen

Un paquete de volumen cuenta transacciones que coinciden con un eventFilter dado (ruta de transacción + estado) dentro del período de facturación. Luego aplica un cargo a partir del modelo de precios configurado. Campos clave:
  • eventFilter — Especifica qué transacciones contar: transactionRoute y status.
  • pricingModel — Ya sea tiered (el precio unitario varía por rango de cantidad) o fixed (precio unitario único independientemente del volumen).
  • tiers — Rangos de cantidad (minQuantity, maxQuantity) y unitPrice por unidad dentro de cada rango.
  • freeQuota — Cantidad de transacciones exentas por período. El motor resta este conteo antes de aplicar precios.
  • discountTiers — Descuentos progresivos: cuando el volumen total alcanza un umbral, el motor aplica el porcentaje de descuento configurado al monto final.
  • countMode — Ya sea perRoute (cuenta todas las transacciones coincidentes como un total único) o perAccount (cuenta por cuenta individual).
  • debitAccountAlias / creditAccountAlias — Rutas contables para el cargo.

​
Paquetes de mantenimiento

Un paquete de mantenimiento aplica una tarifa fija por cuenta activa en el período de facturación, independientemente de la actividad transaccional. Campos clave:
  • feeAmount — Cargo fijo por cuenta activa.
  • assetCode — Moneda para el cargo.
  • maintenanceCreditAccount — Cuenta que recibe los ingresos por tarifas.
  • accountTarget — Define qué cuentas cobrar. Usa exactamente uno por paquete:
    • segmentId — Todas las cuentas en el segmento.
    • portfolioId — Todas las cuentas en el portfolio.
    • aliases — Lista explícita de aliases de cuentas (máximo 100 cuentas).
Cada paquete de mantenimiento soporta solo un tipo de accountTarget. No puedes combinar segmentId, portfolioId y aliases en el mismo paquete.

​
Gestión de billing packages

Los siguientes endpoints gestionan billing packages:
  • POST /v1/billing-packages — Crear un billing package.
  • GET /v1/billing-packages — Listar todos los billing packages.
  • GET /v1/billing-packages/:id — Recuperar un billing package específico.
  • PATCH /v1/billing-packages/:id — Actualizar un billing package (label, description, enable).
  • DELETE /v1/billing-packages/:id — Soft-delete de un billing package.
  • POST /v1/billing/calculate — Calcular facturación para un período.

​
Fee Packages vs. Billing Packages

Los fee packages y billing packages operan de forma independiente. Una transacción puede activar un cálculo de fee package y también contar hacia un billing package en el mismo período. Estos son eventos separados y no conflictivos.

​
Enrutamiento de tarifas

Cada tarifa puede tener:
  • Un routeFrom, que representa la ruta contable para el débito (u origen).
  • Un routeTo, que representa la ruta contable para el crédito (o destino).
  • Un transactionRoute, que representa la naturaleza general de la transacción.
Esto permite el seguimiento granular de cada entrada de tarifa en el Ledger.

​
Tarifas deducibles

Si marcas una tarifa como deducible (isDeductibleFrom: true), se aplica la siguiente lógica:
  • La cuenta de origen envía el valor completo.
  • El motor resta la tarifa del monto que recibe la cuenta de destino.
  • El referenceAmount para los cálculos debe ser originalAmount.
De esta forma, el remitente envía el monto completo, y la cuenta de destino absorbe la deducción.

​
Eliminación suave para un registro seguro

Fees Engine no pierde ningún dato. Cuando eliminas un recurso:
  • Fees Engine lo marca con una marca de tiempo deletedAt. Los registros activos devuelven deletedAt: null.
  • Las consultas estándar lo excluyen, pero la base de datos aún lo almacena para auditoría e historial.
Esto mantiene la trazabilidad completa cuando la necesitas.

​
Integraciones

Puedes usar el Fees Engine por sí solo o junto con otros componentes en tu stack. Funciona con plugins de Lerian o con tu propia implementación para aplicar tarifas desde tu lógica de negocio. Casos de uso populares incluyen:
  • Motores de intercambio.
  • Plataformas de préstamos.
  • Sistemas de pago de facturas.
  • Contratos inteligentes.
  • Pix (plataforma de pagos instantáneos de Brasil).

​
Recomendaciones de seguridad

La seguridad es fundamental cuando trabajas con productos y plugins de Lerian.
Antes de desplegar cualquier componente, revisa nuestras Recomendaciones de Seguridad. Implementa cada producto y sus plugins en línea con las mejores prácticas de seguridad, tales como:
  • Asegurar límites de red
  • Gestionar y rotar secretos
  • Aplicar gestión oportuna de parches
  • Hacer cumplir controles de acceso basados en roles estrictos (RBAC)
Estas prácticas mantienen los productos y plugins de Lerian seguros y en cumplimiento en todo tu stack.

​
Próximos pasos

Explora la API de Fees Engine

Consulta endpoints para fee packages, cálculos y estimaciones.

Usando Fees Engine

Aprende a crear fee packages y billing packages y aplicarlos a transacciones.