> ## 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 por transacción y por período, integrado con el Ledger de Midaz nativamente.

Fees Engine es un componente integrado del proceso unificado del ledger de Midaz. Proporciona configuración y cálculos de tarifas y facturación junto al 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 lógica compleja de tarifas. Aplica tarifas fijas, distribuye tarifas proporcionalmente y estima transacciones antes de que las ejecutes.

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 de 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.

<Tip>
  Fees Engine es una capacidad con licencia de Midaz que se ejecuta dentro del proceso unificado del ledger. Despliégalo y configúralo con Midaz. Si deseas obtener más información o evaluarlo para tu caso de uso, [contacta a nuestro equipo](https://lerian.studio/contact).
</Tip>

## ¿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 cubren costos operacionales y respaldan el cumplimiento legal.

* **Tarifa de mantenimiento de cuenta**: Mantiene las cuentas operativas y cubre costos administrativos.
* **Tarifa de transferencia:** Se aplica a transacciones como TEDs o transferencias internacionales.

### Logística y transporte

En el sector logístico, las tarifas cubren servicios de transporte y almacenamiento.

* **Tarifa de manejo**: Se aplica 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 garantizan la calidad y regulación de los 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 cubren 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.

## Alcance

***

Fees y Billing admiten en paralelo el ámbito de organización y el ámbito de ledger. En la superficie v2 con ámbito de ledger, el ledger indicado por la solicitud es autoritativo: no se acepta un parámetro de consulta `ledgerId`, y un `ledgerId` en el cuerpo debe coincidir con el ledger de la solicitud. Un paquete de otro ledger se devuelve como no encontrado.

## Paquetes de Tarifas

***

Un **Paquete de Tarifas** define cómo el motor aplica tarifas a una transacción. Agrupa una o más reglas de tarifas. Lo personalizas por segmento, *Ledger* y rutas contables.

Puedes crear diferentes 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:

* **ledgerId** – El *Ledger* que registra la transacción y sus tarifas.
* **transactionRoute** – La ruta contable principal para la transacción, para coincidencia por ruta.
* **segmentId** – El producto o segmento al que se aplica el paquete, para coincidencia por segmento.
* **waivedAccounts** – Cuentas a eximir de tarifas, cuando configuras 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 el motor deduce la tarifa del monto original.
  * **referenceAmount** – El monto base para cálculos.

<Note>
  El **Fees Engine** requiere configuración de ruta explícita para cada tarifa y dirección (por ejemplo, débito o crédito).
</Note>

### 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. Fees Engine los valida con el endpoint [Recuperar una Cuenta por Alias](/es/reference/midaz/retrieve-an-account-by-alias).

<Danger>
  Asegúrate de que tu configuración cumpla con los últimos estándares de Midaz. Fees Engine valida cada paquete y transacción contra ellos. Revisa las reglas para `ledgerId`, `creditAccount` y `referenceAmount`, además de campos opcionales de coincidencia como `segmentId` cuando los configuras.
</Danger>

### Elegir el endpoint correcto: calculate vs. estimate

Fees Engine proporciona dos endpoints para aplicar tarifas. Se comportan de manera diferente según el control que necesitas:

#### [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 hay paquete coincidente, el motor no aplica tarifas.

#### [Estimar comisión por Transacción](/es/reference/midaz/plugins/fees-engine/simulate-fees)

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

<Note>
  Usa `calculate` cuando quieras que el motor decida qué paquete aplicar. Usa `estimate` cuando quieras control total sobre qué paquete probar.
</Note>

### Exenciones basadas en segmento

Los fee packages soportan la exención de cuentas individuales listando sus aliases en `waivedAccounts`. Para eximir a un grupo completo de una sola vez, agrega una referencia de segmento a esa misma lista con la forma `segment:<segment-uuid>` — por ejemplo `"segment:seg_premium_01HZ..."`.

<Warning>
  El campo `segmentId` del propio paquete **no** es una exención. Define a qué transacciones se aplica el paquete (coincidencia de paquete a nivel de segmento). Las exenciones siempre viven en `waivedAccounts`.
</Warning>

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.

<Tip>
  Fees Engine resuelve las exenciones basadas en segmento en el momento del cálculo. Cuando las cuentas se unen o abandonan el segmento, el cambio surte efecto en el siguiente cálculo. No actualizas el paquete.
</Tip>

## Billing Packages

***

Los **Billing Packages** calculan cargos a partir del volumen acumulado de transacciones durante un período — diario o mensual. Los fee packages cobran por transacción individual. Los billing packages cuentan las 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.

<Note>
  Los billing packages 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 invocador — ejecuta los cargos reales contra Midaz.
</Note>

### 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. Luego aplica un cargo a partir del 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** — Acepta `perRoute` o `perAccount`. El cálculo por volumen cuenta todas las transacciones coincidentes de la ruta como un total único.
* **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.
  * `portfolioId` — Todas las cuentas en el portfolio.
  * `aliases` — Lista explícita de aliases de cuentas (máximo 100 cuentas).

<Warning>
  Cada paquete de mantenimiento soporta solo un tipo de `accountTarget`. No puedes combinar `segmentId`, `portfolioId` y `aliases` en el mismo paquete.
</Warning>

### 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, semanal o diario)                                 |
| **Modelo de precios**      | Flat, percentual, maxBetweenTypes             | Escalonado o fijo por volumen                                           |
| **Exención de cuentas**    | `waivedAccounts` (aliases o `segment:<uuid>`) | `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                   |

<Note>
  Los fee packages y billing packages operan de forma independiente. Una transacción puede activar un cálculo de fee package y también contar hacia un billing package en el mismo período. Estos son eventos separados y no conflictivos.
</Note>

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

* La **cuenta de origen envía el valor completo**.
* El **motor resta la tarifa del monto que recibe la cuenta de destino**.
* El `referenceAmount` para los cálculos debe ser `originalAmount`.

De esta forma, el remitente envía el monto completo, y la cuenta de destino absorbe la deducción.

## Eliminación suave para un registro seguro

***

Fees Engine no pierde ningún dato. 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 aún lo almacena para auditoría e historial.

Esto mantiene la trazabilidad completa cuando la necesitas.

## Integraciones

***

Usa **Fees Engine** en una implementación de Midaz junto con otros componentes de tu stack. Puedes invocar sus capacidades desde plugins de Lerian o tu propia implementación para aplicar tarifas desde tu lógica de negocio.

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 cuando trabajas con productos y plugins de Lerian.**\
Antes de desplegar cualquier componente, revisa nuestras [**Recomendaciones de Seguridad**](/es/midaz/security-recommendations). Implementa cada producto y sus plugins en línea con las mejores prácticas de seguridad, tales como:

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

Estas prácticas mantienen los productos y plugins de Lerian seguros y en cumplimiento en todo tu stack.

## Próximos pasos

***

<CardGroup cols={2}>
  <Card title="Explora la API de Fees Engine" icon="terminal" href="/es/reference/midaz/plugins/fees-engine/create-package">
    Consulta endpoints para fee packages, cálculos y estimaciones.
  </Card>

  <Card title="Usando Fees Engine" icon="rocket" href="/es/midaz/fees/using-fee-engine">
    Aprende a crear fee packages y billing packages y aplicarlos a transacciones.
  </Card>
</CardGroup>