Prueba el Plugin Fees Engine localmenteEjecuta los plugins de Lerian sin desplegar en Kubernetes usando nuestro repositorio plugins-docker-compose.Ten en cuenta que estos servicios requieren una licencia válida para ejecutarse. Sin ella, la aplicación no iniciará. Para detalles de licencia, consulta nuestra documentación de Licencia.
¿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 simules 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 libros mayores 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,routeFromyrouteTo. - Herramientas de simulació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.
Fees Engine es un plugin separado. 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 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, libro mayor 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 libro mayor 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.
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: truedeben usarreferenceAmount: originalAmount. - Las tarifas con prioridad 1 también deben usar
referenceAmount: originalAmount. - Campos como
organizationId,ledgerIdycreditAccountdeben existir en Midaz y se validan usando el endpoint Recuperar una Cuenta por Alias.
Fees Engine valida todos los paquetes y transacciones según los últimos estándares de Midaz. Asegúrate de que tu configuración cumpla con las reglas requeridas para campos como
ledgerId, segmentId, creditAccount y referenceAmount.Elegir el endpoint correcto: calculate vs. simulate
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 libro mayor 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.
Simular tarifas de transacción
- Simula 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 libro mayor.
Usa
calculate cuando quieras que el motor decida qué paquete aplicar. Usa simulate cuando quieras control total sobre qué paquete probar.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.
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
referenceAmountusado en los cálculos debe seroriginalAmount.
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.
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)