¿Qué es Fees Engine?

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, semanal 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.
• Deuda de comisión para comisiones diferibles: en una transacción directa /v2, una comisión sin cobertura se convierte en una deuda que los créditos siguientes liquidan.
• Planes de tarifas que asignas a cuentas, con una cuota gratuita por comisión y mes calendario, y comisiones de servicio que cobras a una cuenta.

​

¿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. Consultar, actualizar o eliminar un paquete que pertenece a otro ledger devuelve 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 – El ID de una ruta de transacción. El paquete coincide con una transacción que envía el mismo routeId.
• segmentId – Un ID de segmento. El paquete coincide cuando todas las cuentas de origen, excepto las cuentas @external, pertenecen a ese segmento.
• metadataSelector – Pares de metadatos que la transacción debe incluir, todos, para que el paquete coincida. Un par coincide solo con un valor de metadato de tipo string igual a él. Lo defines cuando creas el paquete.
• 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 de lo que recibe el destino, en lugar de sumarla encima.
  • referenceAmount – El monto base para los cálculos.
  • deferrable – Si la parte de la comisión que el pagador no puede cubrir se convierte en una deuda de comisión. El valor predeterminado es false.
• rounding – Opcional. La scale (0 a 18) y el mode (floor o halfUp) con los que el paquete redondea cada comisión. Consulta Redondeo.

​

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.
• Las comisiones con deferrable: true deben usar isDeductibleFrom: false.
• El creditAccount de cada comisión debe ser un alias de cuenta que existe en el ledger. Midaz lo verifica cuando creas o actualizas el paquete.
• Cada clave de comisión empieza con una letra minúscula, seguida solo de letras y dígitos ASCII (^[a-z][a-zA-Z0-9]*$). Midaz guarda la clave tal como la envías. Una actualización rechaza una clave nueva que coincide con una clave guardada, salvo por las mayúsculas y minúsculas.
• Cuando eliminas una cuenta, Midaz quita toda comisión que acredita su alias y quita el alias de waivedAccounts. Un paquete que queda sin comisiones se desactiva.
• Una creación o actualización puede devolver 0086 cuando otra escritura de paquete del mismo ledger se ejecuta al mismo tiempo. La solicitud no cambia nada. Vuelve a intentarlo.

​

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 el monto está dentro del rango de montos del paquete. No verifica transactionRoute ni segmentId.
• No lee las asignaciones de planes de tarifas.
• Útil para pruebas, depuración o previsualización de comisiones, 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:0198e5f4-7b2a-7c3d-9e1f-2a3b4c5d6e7f". 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.

​

Paquetes de facturación

---

Los paquetes de facturación calculan los cargos a partir del volumen de transacciones acumulado durante un período (diario, semanal 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 por cada cuenta activa en el momento en que ejecutas el cálculo.

​

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: las cuentas que el cargo debita y acredita. Ambas deben existir en el ledger.

​

Paquetes de mantenimiento

Un paquete de mantenimiento aplica una comisión fija por cada cuenta activa en el momento en que ejecutas el cálculo, 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).

​

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/{billing_package_id}: obtiene un paquete de facturación específico.
• PATCH /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{billing_package_id}: actualiza un paquete de facturación (label, description, enable).
• DELETE /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{billing_package_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.

Cuando eliminas una cuenta, Midaz quita su alias de los paquetes de facturación del ledger. Un paquete cuyo debitAccountAlias, creditAccountAlias o maintenanceCreditAccount es ese alias se desactiva. El alias también sale de accountTarget.aliases, y un paquete que queda sin alias de destino se desactiva. Crear un paquete de facturación, o activar uno desactivado, puede devolver 0086 cuando otra escritura de paquete de facturación se ejecuta al mismo tiempo. Vuelve a intentarlo.

​

Paquetes de comisiones vs. paquetes de facturación

---

​

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 en su paquete, que selecciona las transacciones a las que se aplica el paquete.

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

---

Cuando eliminas un recurso:

• Fees Engine lo marca con una marca de tiempo deletedAt.
• 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

---

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

---