Skip to main content
Fees es un componente integrado del proceso unificado del ledger de Midaz. Proporciona la configuración y los cálculos de comisiones y facturación junto con el ledger. Despliégalo y configúralo con Midaz. No es un servicio ni un plugin independiente.

​
¿Por qué usar Fees Engine?

El Fees Engine te ayuda a gestionar una lógica de comisiones compleja. Aplica tarifas fijas, distribuye las comisiones de forma proporcional y estima las transacciones antes de que las ejecutes. Ofrece:
  • Configuración flexible de comisiones mediante paquetes de comisiones, adaptados a grupos de cuentas o ledgers específicos.
  • Múltiples métodos de cálculo: comisiones fijas, tasas porcentuales y la lógica de “máximo entre ambos”.
  • Distribución proporcional de comisiones para flujos de marketplace y operaciones multicuenta.
  • Compatibilidad con rutas contables mediante transactionRoute, routeFrom y routeTo.
  • Herramientas de estimación para previsualizar los cálculos antes de ejecutar las transacciones.
  • Lógica de exención de comisiones por cuenta y por rangos de valor de la transacción.
  • Aplicación basada en prioridad para controlar el orden de varias comisiones.
  • Mecánica de deducción precisa con compatibilidad para isDeductibleFrom.
  • Facturación basada en volumen mediante paquetes de facturación. Cobra según el recuento acumulado de transacciones por período (diario o mensual).
  • Facturación de mantenimiento para cargos recurrentes por cuenta, dirigidos a cuentas por segmento, portafolio o lista explícita.
  • Cuotas gratuitas y descuentos progresivos para modelar precios escalonados e incentivos por volumen.
  • Exenciones basadas en segmento para eximir a grupos completos de cuentas de los paquetes de comisiones sin enumerar las cuentas individuales.
Fees Engine es una capacidad con licencia de Midaz que funciona dentro del proceso unificado del ledger. Despliégala y configúrala con Midaz. Si quieres saber más o evaluarla para tu caso de uso, ponte en contacto con nuestro equipo.

​
¿Qué son las comisiones?

Las comisiones son valores monetarios que se cobran a cambio de servicios, productos o acceso a recursos. Su propósito depende de la industria. A continuación, algunos ejemplos:

​
Finanzas

En el sector financiero, las comisiones cubren los costos operativos y respaldan el cumplimiento legal.
  • Comisión de mantenimiento de cuenta: mantiene las cuentas operativas y cubre los costos administrativos.
  • Comisión de transferencia: se aplica a transacciones como TED o transferencias internacionales.

​
Logística y transporte

En el sector de logística, las comisiones cubren los servicios de transporte y almacenamiento.
  • Comisión de manipulación: se aplica durante el almacenamiento y el movimiento físico de mercancías.
  • Comisión de descarga: cubre las operaciones de descarga en los puntos de entrega.

​
Farmacéutico y salud

En el sector farmacéutico, las comisiones garantizan la calidad y la regulación de los servicios.
  • Comisión de registro de medicamentos: relacionada con las aprobaciones regulatorias y el ingreso al mercado.
  • Comisión de análisis de laboratorio: cubre los costos de pruebas y control de calidad.

​
Agrícola

En el sector agrícola, las comisiones cubren los procesos de comercialización y regulación.
  • Comisión de inspección sanitaria: garantiza el cumplimiento sanitario en las exportaciones agrícolas.
  • Comisión de exportación agrícola: cubre los costos administrativos y regulatorios de exportación.

​
Alcance

El servicio unificado de Midaz expone Fees y Billing solo en la superficie v2 con alcance de ledger. La URL es la única entrada para el ledger: no se acepta un parámetro de consulta ledgerId, y un cuerpo de solicitud que envía ledgerId se rechaza como campo desconocido. Un paquete que pertenece a otro ledger se devuelve como no encontrado.

​
Paquetes de comisiones

Un paquete de comisiones define cómo el motor aplica las comisiones a una transacción. Agrupa una o más reglas de comisión. Lo personalizas por segmento, ledger y rutas contables. Puedes crear distintos 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:
  • Alcance del ledger – La URL v2 identifica el ledger que registra la transacción y sus comisiones. No envíes ledgerId en el cuerpo de la solicitud.
  • transactionRoute – La ruta contable principal de la transacción, para la coincidencia en el nivel de ruta.
  • segmentId – El producto o segmento al que se aplica el paquete, para la coincidencia en el nivel de segmento.
  • waivedAccounts – Cuentas que se eximen de comisiones, cuando configuras exenciones.
  • fees – Un mapa de reglas de comisión individuales, cada una con:
    • priority – Define el orden de ejecución.
    • routeFrom y routeTo – Rutas contables personalizadas para la comisión.
    • isDeductibleFrom – Indica si el motor deduce la comisión del monto original.
    • referenceAmount – El monto base para los cálculos.
Fees Engine requiere una configuración explícita de ruta para cada comisión y dirección (por ejemplo, débito o crédito).

​
Reglas de validación

Fees Engine aplica las siguientes reglas:
  • La prioridad de la comisión debe ser única dentro de un paquete.
  • Las comisiones con isDeductibleFrom: true deben usar referenceAmount: originalAmount.
  • Las comisiones con priority 1 también deben usar referenceAmount: originalAmount.
  • La organización y el ledger indicados en la URL deben existir en Midaz. Los alias de cuenta configurados, como creditAccount, deben resolverse en ese alcance. Fees Engine los valida mediante el endpoint Obtener una cuenta por alias.
Confirma que tu configuración cumpla con los estándares más recientes de Midaz. Fees Engine valida cada paquete y transacción según esos estándares. Revisa la organización y el ledger en la URL, y las reglas para creditAccount y referenceAmount, además de los campos de coincidencia opcionales como segmentId cuando los configures.

​
Aplicación y estimación de comisiones

Midaz aplica las comisiones en el mismo proceso cuando crea una transacción. No existe un endpoint público independiente para calcular comisiones. El ledger evalúa el paquete que coincide dentro del flujo de la transacción y aplica sus reglas cuando encuentra una coincidencia.

​
Estimar comisiones de transacción

  • Estima las comisiones de un paquete específico mediante su packageId.
  • Devuelve las comisiones calculadas solo si la transacción coincide con las condiciones del paquete.
  • Útil para pruebas, depuración o previsualización de comisiones, sin escribir en el ledger.
La aplicación de comisiones ocurre durante la creación de la transacción. Usa estimate cuando quieras probar un paquete específico sin escribir en el ledger.

​
Exenciones basadas en segmento

Los paquetes de comisiones permiten eximir cuentas individuales mediante la lista de sus alias en waivedAccounts. Para eximir a todo un grupo de una vez, agrega una referencia de segmento a esa misma lista con el formato segment:<segment-uuid>, por ejemplo "segment:seg_premium_01HZ...".
El campo segmentId del propio paquete no es una exención. Determina qué paquete se aplica a una transacción (coincidencia de paquete en el nivel de segmento). Las exenciones siempre están en waivedAccounts.
Usa exenciones basadas en segmento cuando:
  • Un nivel de cliente (como las cuentas premium) está exento de una comisión de forma general.
  • Las cuentas internas o de socios pertenecen a un segmento existente en Midaz.
  • Mantener una lista de alias de cuentas individuales resulta poco práctico a gran escala.
Fees Engine resuelve las exenciones basadas en segmento en el momento del cálculo. Cuando las cuentas se unen o salen del segmento, el cambio surte efecto en el siguiente cálculo. No necesitas actualizar el paquete.

​
Paquetes de facturación

Los paquetes de facturación calculan los cargos a partir del volumen de transacciones acumulado durante un período (diario o mensual). Los paquetes de comisiones cobran por cada transacción individual. Los paquetes de facturación cuentan las transacciones que califican y devuelven payloads para que tu orquestador los ejecute. Hay dos tipos disponibles:
  • Volumen: cobra según la cantidad de transacciones que coinciden con un filtro de eventos en el período.
  • Mantenimiento: cobra una comisión fija recurrente por cuenta activa, una vez por período de facturación.
Los paquetes de facturación 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 llamador) ejecuta los cargos reales contra Midaz.

​
Paquetes de volumen

Un paquete de volumen cuenta las transacciones que coinciden con un eventFilter determinado (ruta de transacción + estado) dentro del período de facturación. Luego aplica un cargo según el modelo de precios configurado. Campos clave:
  • eventFilter: especifica qué transacciones contar, mediante transactionRoute y status.
  • pricingModel: puede ser tiered (el precio unitario varía según el rango de cantidad) o fixed (un único precio unitario sin importar el 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 número antes de aplicar los precios.
  • discountTiers: descuentos progresivos. Cuando el volumen total alcanza un umbral, el motor aplica el porcentaje de descuento configurado al monto final.
  • countMode: acepta perRoute o perAccount. El cálculo de volumen cuenta todas las transacciones coincidentes de la ruta como un único total.
  • debitAccountAlias / creditAccountAlias: rutas contables para el cargo.

​
Paquetes de mantenimiento

Un paquete de mantenimiento aplica una comisión fija por cuenta activa en el período de facturación, sin importar la actividad transaccional. Campos clave:
  • feeAmount: cargo fijo por cuenta activa.
  • assetCode: moneda del cargo.
  • maintenanceCreditAccount: cuenta que recibe el ingreso por comisiones.
  • accountTarget: define qué cuentas se cobran. Usa exactamente una por paquete:
    • segmentId: todas las cuentas del segmento.
    • portfolioId: todas las cuentas del portafolio.
    • aliases: lista explícita de alias de cuenta (máximo 100 cuentas).
Cada paquete de mantenimiento admite solo un tipo de accountTarget. No puedes combinar segmentId, portfolioId y aliases en el mismo paquete.

​
Gestión de paquetes de facturación

Los siguientes endpoints gestionan los paquetes de facturación:
  • POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages: crea un paquete de facturación.
  • GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages: enumera todos los paquetes de facturación.
  • GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{id}: obtiene un paquete de facturación específico.
  • PATCH /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{id}: actualiza un paquete de facturación (label, description, enable).
  • DELETE /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{id}: elimina lógicamente un paquete de facturación.
  • POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate: calcula la facturación de un período.

​
Paquetes de comisiones vs. paquetes de facturación

Los paquetes de comisiones y los paquetes de facturación funcionan de forma independiente. Una transacción puede activar el cálculo de un paquete de comisiones y también contar para un paquete de facturación en el mismo período. Son eventos separados que no entran en conflicto.

​
Enrutamiento de comisiones

Cada comisión puede tener:
  • Un routeFrom, que representa la ruta contable para el débito (o el origen).
  • Un routeTo, que representa la ruta contable para el crédito (o el destino).
  • Un transactionRoute, que representa la naturaleza general de la transacción.
Esto permite un seguimiento detallado de cada asiento de comisión en el ledger.

​
Comisiones deducibles

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

​
Eliminación lógica para un registro seguro

Fees Engine no pierde datos. 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 lo sigue almacenando para fines de auditoría e historial.

​
Integraciones

Usa Fees Engine en un despliegue de Midaz junto con otros componentes de tu stack. Puedes llamar a sus capacidades desde plugins de Lerian o tu propia implementación para aplicar comisiones desde tu lógica de negocio. Los casos de uso incluyen:
  • Motores de intercambio
  • Plataformas de préstamos
  • Sistemas de pago de facturas
  • Contratos inteligentes
  • Pix (la 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 conforme a las mejores prácticas de seguridad, tales como:
  • Proteger los límites de red
  • Gestionar y rotar los secretos
  • Aplicar una gestión de parches oportuna
  • Aplicar controles de acceso estrictos basados en roles (RBAC)

​
Próximos pasos

Explora la API de Fees Engine

Explora los endpoints para paquetes de comisiones, cálculos y estimaciones.

Uso de Fees Engine

Aprende a crear paquetes de comisiones y aplicarlos a las transacciones.