¿Qué es Fees Engine?

​

¿Por qué usar Fees Engine?

---

El plugin Fees Engine te ayuda a gestionar fácilmente lógica compleja de tarifas. Ya sea que apliques una tarifa fija, distribuyas tarifas proporcionalmente o estimes transacciones por adelantado, este plugin está construido para flexibilidad y escala. 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 en que se aplican 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.

​

¿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 se aplican para cubrir costos operacionales y garantizar cumplimiento legal.

• Tarifa de mantenimiento de cuenta: Mantiene las cuentas operativas y cubre costos administrativos.
• Tarifa de transferencia: Cobrada por transacciones como TEDs o transferencias internacionales.

​

Logística y transporte

En el sector logístico, las tarifas están relacionadas con el uso de servicios de transporte y almacenamiento.

• Tarifa de manejo: Aplicada 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 buscan garantizar la calidad y regulación de 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 están vinculadas a 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 se aplican las tarifas a una transacción. Agrupa una o más reglas de tarifas y puede personalizarse por segmento, Ledger y rutas contables. Puedes crear diferentes paquetes para diferentes productos, tipos de transacción o segmentos de clientes, cada uno con su propia lógica de cálculo, configuración de rutas y reglas de prioridad. Un paquete típicamente incluye:

• transactionRoute – La ruta contable principal para la transacción.
• segmentId – El producto o segmento al que se aplica el paquete.
• ledgerId – El Ledger que registra la transacción y sus tarifas.
• waivedAccounts – Cuentas que deben estar exentas de tarifas.
• 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 la tarifa se deduce del monto original.
  • referenceAmount – El monto base usado para cálculos.

​

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 y se validan usando el endpoint Recuperar una Cuenta por Alias.

​

Elegir el endpoint correcto: calculate vs. estimate

Fees Engine proporciona dos endpoints para aplicar tarifas. Se comportan de manera diferente, dependiendo de cuánto control y flexibilidad necesites:

​

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 se encuentra un paquete coincidente, no se aplican tarifas.

​

Estimar comisión por Transacción

• Estima tarifas para un paquete específico usando su packageId.
• Devuelve tarifas calculadas solo si la transacción coincide con las condiciones del paquete.
• Útil para pruebas, depuración o dar a los usuarios una vista previa de tarifas, sin escribir en el Ledger.

​

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.

​

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 una tarifa se marca como deducible (isDeductibleFrom: true), se aplica la siguiente lógica:

• El valor completo se envía desde la cuenta de origen.
• La tarifa se resta del valor recibido por la cuenta de destino.
• El referenceAmount usado en los cálculos debe ser originalAmount.

Este enfoque garantiza que el remitente envíe el monto completo y la deducción se aplique solo en el extremo receptor.

​

Eliminación suave para un registro seguro

---

No se pierde ningún dato. Cuando se elimina un recurso:

• Se marca con una marca de tiempo deletedAt.
• Se excluye de consultas estándar, pero se mantiene almacenado en la base de datos para auditoría y precisión histórica.

Esto garantiza trazabilidad completa si es necesario.

​

Billing Packages

---

Los Billing Packages calculan cargos basados en el volumen acumulado de transacciones durante un período — diario o mensual. A diferencia de los fee packages, que aplican un cargo por transacción individual, los billing packages evalúan el conteo total de 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.

​

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 y aplica un cargo basado en el 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 (soporta 100k+ cuentas).
  • portfolioId — Todas las cuentas en el portfolio (soporta miles de cuentas).
  • aliases — Lista explícita de aliases de cuentas (máximo 100 cuentas).

​

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

---

​

Integraciones

---

Puedes usar el Fees Engine por sí solo o junto con otros componentes en tu stack. Se integra sin problemas con plugins de Lerian o tu propia implementación para aplicar tarifas basadas en tu lógica de negocio única. 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 al trabajar con productos y plugins de Lerian.
Antes de desplegar cualquier componente en tu entorno, recomendamos encarecidamente revisar nuestras Recomendaciones de Seguridad. Cada producto—junto con sus plugins asociados—debe implementarse en línea con las mejores prácticas de seguridad, incluyendo:

• 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)

Siguiendo estas prácticas, garantizas que los productos y plugins de Lerian operen de forma segura, se integren sin problemas con tu infraestructura y mantengan cumplimiento, integridad de datos y confianza del usuario en todo tu ecosistema.

​

Próximos pasos

---