> ## 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.
# Usando Fees Engine
> Usa Fees Engine para aplicar fee packages por transacción y billing packages por período alineados con tus reglas de negocio.
Ya sea que estés aplicando tarifas por transacción o calculando cargos de facturación periódicos, Fees Engine ofrece control y flexibilidad total. Esta guía te lleva a través de ambos flujos de trabajo: fee packages (por transacción) y billing packages (por período).
¿No sabes cuál usar? Los fee packages aplican cargos en el momento de la transacción. Los billing packages calculan cargos durante un período (diario o mensual) para que tu orquestador los ejecute. Puedes usar ambos simultáneamente.
## Fee packages: flujo de trabajo por transacción
***
Así es como funciona el proceso, desde la configuración de tarifas hasta ver los resultados.
### Paso 1 - Crear tus paquetes de tarifas
Comienza configurando **paquetes de tarifas** que definen cómo se aplican las tarifas. Para hacerlo, usa el endpoint [Create a Package](/es/reference/midaz/plugins/fees-engine/create-package). Cada paquete contiene un conjunto de reglas de tarifas y criterios de coincidencia.
Puedes adaptar paquetes a diferentes *Ledgers*, segmentos y rutas de transacción usando:
* **transactionRoute** – Identifica la naturaleza de la transacción, cuando necesitas coincidencia por ruta.
* **segmentId** – Agrupa clientes o tipos de productos, cuando necesitas coincidencia por segmento.
* **ledgerId** – Define qué *Ledger* registra la transacción.
* **Minimum** y **maximum** amount – Umbrales opcionales para la aplicación de tarifas.
* **routeFrom** / **routeTo** – Define cómo se mueve cada tarifa a través de los flujos contables.
Esta flexibilidad te permite aplicar tarifas distintas por escenario, desde configuraciones basadas en cuentas hasta basadas en valor.
**Gestión de Paquetes**
Los siguientes endpoints también están disponibles para que gestiones los paquetes:
* [List Packages](/es/reference/midaz/plugins/fees-engine/list-packages) - Lista todos los paquetes creados.
* [Retrieve a Package](/es/reference/midaz/plugins/fees-engine/retrieve-package) - Recupera información de un paquete específico.
* [Update a Package](/es/reference/midaz/plugins/fees-engine/update-package) - Actualiza la información de un paquete específico.
* [Delete a Package](/es/reference/midaz/plugins/fees-engine/delete-package) - Eliminación suave de un paquete.
### (opcional) Paso 2 - Ejecutar una estimación
Si quieres previsualizar cómo se comportaría un paquete de tarifas antes de confirmar una transacción real, usa el endpoint [Estimar comisión por Transacción](/es/reference/midaz/plugins/fees-engine/simulate-fees).
Esta estimación ayuda a validar:
* Qué reglas de tarifas se activarán.
* Cómo se comportará el paquete con los valores dados.
* Si se aplican exenciones.
### Paso 3 - Crear una transacción
Una vez que los paquetes estén configurados, activa la transacción real usando el endpoint [create a transaction](/es/reference/midaz/create-a-transaction-using-json). Incluye `ledgerId` y los campos de coincidencia configurados, como `transactionRoute` o `segmentId`, para que el motor evalúe el paquete correcto.
### Paso 4 - El Fees Engine entra en acción
Fees Engine envía automáticamente una llamada al endpoint [Calculate Fees for a Package](/es/reference/midaz/plugins/fees-engine/calculate-fees) y evalúa si un paquete aplica basándose en:
* **transactionRoute**, cuando esté configurado
* **segmentId**, cuando esté configurado
* **ledgerId**
* **Minimum** y **maximum** amount
* **waivedAccounts**, cuando esté configurado para exenciones de tarifas
Solo se selecciona un paquete por transacción.
### Paso 5 - Verificar exenciones
El sistema verifica:
* Si el monto de la transacción está fuera del rango permitido.
* Si la cuenta de origen está exenta.
Si se cumple cualquiera de estas condiciones, no se aplican tarifas y la transacción procede normalmente.
### Paso 6 - Cálculo y aplicación de tarifas
Si se aplica un paquete, Fees Engine:
* Calcula valores de tarifas basándose en la `applicationRule` seleccionada.
* Aplica tarifas proporcionalmente entre cuentas si es necesario.
* Usa `isDeductibleFrom` para definir si la tarifa se agrega o se deduce.
* Enruta tarifas a la `creditAccount` correcta usando el `routeFrom` y `routeTo` configurados.
* Devuelve el resultado completo de la transacción junto con el `packageAppliedID` en los metadatos.
### Paso 7 - Actualizaciones del *Ledger*
Una vez que las tarifas se calculan, el componente **Transactions** toma el control. Procesa:
* Débitos de cuentas de origen
* Créditos a destinos de tarifas
* Desglose de tarifas por ruta y cuenta
Cada movimiento se almacena en el *Ledger* para trazabilidad y auditabilidad completas.
### Paso 8 - Revisar y confirmar
Después de la ejecución, puedes:
* Inspeccionar la transacción final y los montos por cuenta.
* Confirmar el paquete de tarifas que se aplicó.
* Verificar todos los movimientos de tarifas a través de metadatos y registros del *Ledger*.
## ¿Por qué estimar una transacción?
***
Las estimaciones te permiten previsualizar cómo se comporta un paquete de tarifas específico, sin ejecutar una transacción real ni escribir en el *Ledger*.
Usa estimaciones cuando:
* Quieras probar un paquete específico.
* Estés depurando reglas de tarifas o umbrales.
* Quieras validar exenciones, rangos de valores o divisiones proporcionales.
* Necesites una vista previa antes de crear una transacción real.
* Estés construyendo una interfaz y quieras mostrar tarifas estimadas.
Fees Engine proporciona el endpoint [Estimar comisión por Transacción](/es/reference/midaz/plugins/fees-engine/simulate-fees) para este propósito. Solo tienes que pasar un `packageId` y el endpoint devuelve lo que sucedería si **se aplicara ese paquete exacto**.
### ¿Qué obtienes con una estimación?
* Una estimación completa de las reglas de tarifas.
* Qué cuentas serían cargadas.
* Cómo se dividiría la tarifa.
* Sin impacto en el *Ledger*.
Usa estimaciones cuando no estés listo para confirmar la transacción, o quieras darles a tus usuarios una vista previa clara de las tarifas.
## Errores comunes
***
Fees Engine valida cada solicitud para asegurar consistencia y lógica correcta de tarifas. A continuación se muestran los problemas más frecuentes que puedes encontrar al crear paquetes o procesar transacciones.
| Código | Título | Mensaje |
| :------- | :------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| FEE-0002 | Campos faltantes en la solicitud | Tu solicitud está faltando uno o más campos requeridos. Por favor consulta la documentación para asegurar que todos los campos necesarios estén incluidos en tu solicitud. |
| FEE-0012 | Entidad no encontrada | No se encontró ninguna entidad para el ID dado. Por favor asegúrate de usar el ID correcto para la entidad que estás intentando gestionar. |
| FEE-0013 | Prioridad de tarifa inválida | El campo priority en fees es inválido. El campo no puede estar repetido. |
| FEE-0015 | minimumAmount mayor que maximumAmount | El valor de minimumAmount es mayor que maximumAmount. |
| FEE-0022 | Falló el cálculo de tarifa | Error al hacer el cálculo de una tarifa sobre una transacción. |
| FEE-0024 | originalAmount es requerido cuando priority es uno | Para Priority igual a uno, referenceAmount debe ser 'originalAmount' para fee. |
| FEE-0025 | Falló aplicar regla: flatFee o percentual | applicationRule flatFee o percentual debe tener exactamente 1 cálculo para Fee. |
| FEE-0035 | Superposición de rango de monto del paquete | El maximumAmount y minimumAmount del nuevo paquete se superponen con el rango de monto de un paquete existente. |
¿Quieres la lista completa de códigos de error? La encontrarás en la página [Fees Engine error list](/es/reference/midaz/plugins/fees-engine/fee-engine-error-list) en la [API reference](/es/reference/introduction).
## Billing packages: flujo de trabajo por período
***
Los billing packages calculan cargos basados en el volumen acumulado de transacciones o mantenimiento por cuenta durante un período de facturación. A diferencia de los fee packages, la facturación es activada por el invocador — tu orquestador decide cuándo calcular y ejecuta los cargos resultantes.
### Paso 1 — Crear billing packages
Configura billing packages que definan tus reglas de cobro periódico. Cada paquete es de tipo **volume** o **maintenance**.
**Ejemplo de paquete de volumen** — cobro por Pix enviado con precios escalonados:
```json theme={null}
POST /v1/billing-packages
Headers:
X-Organization-Id: org_01HZ...
Body:
{
"label": "Pix Send Monthly Billing",
"description": "Monthly volume billing for Pix transactions",
"ledgerId": "ldg_01HZ...",
"type": "volume",
"enable": true,
"eventFilter": {
"transactionRoute": "pix-send",
"status": "APPROVED"
},
"pricingModel": "tiered",
"tiers": [
{ "minQuantity": 1, "maxQuantity": 100, "unitPrice": "0.50" },
{ "minQuantity": 101, "maxQuantity": 500, "unitPrice": "0.35" },
{ "minQuantity": 501, "maxQuantity": null, "unitPrice": "0.20" }
],
"freeQuota": 10,
"discountTiers": [
{ "minQuantity": 200, "discountPercentage": "5.00" },
{ "minQuantity": 400, "discountPercentage": "10.00" }
],
"countMode": "perAccount",
"assetCode": "BRL",
"debitAccountAlias": "client-wallet",
"creditAccountAlias": "fees-revenue"
}
```
**Ejemplo de paquete de mantenimiento** — tarifa mensual por cuenta PF activa:
```json theme={null}
POST /v1/billing-packages
Headers:
X-Organization-Id: org_01HZ...
Body:
{
"label": "PF Account Maintenance",
"description": "Monthly maintenance fee for active PF accounts",
"ledgerId": "ldg_01HZ...",
"type": "maintenance",
"enable": true,
"feeAmount": "9.90",
"assetCode": "BRL",
"maintenanceCreditAccount": "fees-maintenance-pf",
"accountTarget": {
"segmentId": "seg_pf_01HZ..."
}
}
```
### Paso 2 — Activar el cálculo de facturación
Llama a `POST /v1/billing/calculate` con el ID del ledger y el período de facturación. El motor evalúa todos los billing packages activos que coincidan con los criterios.
```json theme={null}
POST /v1/billing/calculate
Body:
{
"ledgerId": "ldg_01HZ...",
"period": "2026-03",
"type": "volume"
}
```
El campo `period` soporta tres formatos: `YYYY-MM` (mensual), `YYYY-Www` (semanal, ej., `2026-W13`) y `YYYY-MM-DD` (diario).
El campo `type` es opcional. Usa `"volume"` o `"maintenance"` para restringir el cálculo a un tipo. Omítelo para calcular ambos tipos en una sola llamada.
### Paso 3 — Recibir los resultados del cálculo
El motor devuelve un arreglo de resultados, cada uno conteniendo un `transactionPayload` listo para ser enviado a Midaz.
Cada resultado incluye:
* El billing package que lo generó.
* Los montos calculados con desglose completo (niveles aplicados, descuentos, cuota gratuita restada).
* Un payload de transacción con `source.from` (entradas de débito) y `distribute.to` (entradas de crédito).
* Metadatos de auditoría estructurados para trazabilidad.
### Paso 4 — Ejecutar los cargos
Envía cada `transactionPayload` a Midaz vía `POST /transactions/json` para crear las transacciones de facturación reales. Este paso es responsabilidad de tu orquestador — Flowker, un cron job, o cualquier otro sistema.
El motor de facturación calcula y devuelve resultados. No crea transacciones en Midaz. Tu orquestador controla cuándo y cómo se ejecutan los cargos.
### Paso 5 — Revisar y conciliar
Después de ejecutar los cargos:
* Verifica que las transacciones creadas en Midaz coincidan con los resultados del cálculo de facturación.
* Usa los metadatos de auditoría en cada resultado para la conciliación.
* El cálculo de facturación no tiene estado — puedes re-ejecutarlo para el mismo período para verificar resultados.
### Gestión de billing packages
Usa estos endpoints para gestionar billing packages existentes:
* `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 (solo `label`, `description`, `enable`).
* `DELETE /v1/billing-packages/:id` — Soft-delete de un billing package.
El cálculo de facturación sigue una política de todo-o-nada. Si algún paquete falla durante el cálculo, toda la operación falla y no se devuelven resultados parciales. Corrige el paquete que falló y re-ejecuta.