> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # ¿Qué es Fees Engine? > Fees Engine controla cómo se configuran, calculan y rastrean tarifas y cobros en escenarios por transacción y por período. El Fees Engine forma parte de la **familia de productos Midaz**. Es un **servicio de cálculo**: tu aplicación le pide calcular las comisiones de una transacción y devuelve el resultado para que tu app lo registre — **lee** de Midaz pero nunca escribe en el ledger. Se **despliega de forma independiente** y puedes habilitarlo u omitirlo 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](/es/platform/plugins/midaz-version-compatibility). **Prueba el Fees Engine localmente** Ejecuta los plugins de Lerian sin desplegar en Kubernetes usando nuestro [repositorio plugins-docker-compose](https://github.com/LerianStudio/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](/es/reference/lerians-license). ## ¿Por qué usar Fees Engine? *** El **Fees Engine** te ayuda a gestionar lógica compleja de tarifas. Ya sea que apliques una tarifa fija, distribuyas tarifas proporcionalmente o estimes transacciones por adelantado, 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. 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](https://lerian.studio/contact). ## ¿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 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, cuando se usa coincidencia por ruta. * **segmentId** – El producto o segmento al que se aplica el paquete, cuando se usa coincidencia por segmento. * **waivedAccounts** – Cuentas que deben estar exentas de tarifas, cuando se configuran 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 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: 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](/es/reference/midaz/retrieve-an-account-by-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`, `creditAccount` y `referenceAmount`, además de campos opcionales de coincidencia como `segmentId` cuando estén configurados. ### 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](/es/reference/midaz/plugins/fees-engine/calculate-fees) * 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](/es/reference/midaz/plugins/fees-engine/simulate-fees) * 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*. 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. Las exenciones basadas en segmento se resuelven en el momento del cálculo. Cuando las cuentas se unen o abandonan el segmento, el cambio surte efecto en el siguiente cálculo de tarifas sin necesidad de actualizar el paquete. ## 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. Los billing packages son un motor de cálculo, no una plataforma de facturación. El motor calcula lo que debe cobrarse 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 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). 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 *** | | Fee Packages | Billing Packages | | -------------------------- | --------------------------------------------- | ----------------------------------------------------------------------- | | **Activación** | Por transacción (síncrono) | Por período (mensual o diario) | | **Modelo de precios** | Flat, percentual, maxBetweenTypes | Escalonado o fijo por volumen | | **Exención de cuentas** | `waivedAccounts` (individual) o `segmentId` | `accountTarget`: segmento, portfolio o lista de aliases | | **Descuentos por volumen** | No | Sí (`discountTiers`) | | **Cuotas gratuitas** | No | Sí (`freeQuota` por período) | | **Cargos recurrentes** | No | Sí (tipo maintenance) | | **Ejecución** | Automática — el motor evalúa cada transacción | Activada por el invocador — el orquestador llama a `/billing/calculate` | | **Salida** | Transacción con tarifas aplicadas | Payloads de cálculo para que el invocador los ejecute | Los fee packages y billing packages operan de forma independiente. Una transacción puede activar un cálculo de fee package y también ser contada 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 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`. Los registros activos devuelven `deletedAt: null`. * 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. ## 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**](/es/midaz/security-recommendations). 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 *** Consulta endpoints para fee packages, cálculos y estimaciones. Aprende a crear fee packages y billing packages y aplicarlos a transacciones.