> ## 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. # Uso de Fees Engine > Usa Fees Engine para aplicar paquetes de comisiones por transacción y paquetes de facturación por período que coincidan con tus ledgers, segmentos y rutas de transacción. Fees Engine aplica comisiones por transacción y calcula los cargos de facturación periódicos. Esta guía cubre ambos workflows: paquetes de comisiones (por transacción) y paquetes de facturación (por período). ¿No sabes cuál usar? Los paquetes de comisiones aplican cargos en el momento de la transacción. Los paquetes de facturación calculan cargos durante un período (diario o mensual) para que tu orquestador los ejecute. Puedes usar ambos al mismo tiempo. ## Paquetes de comisiones: workflow por transacción *** Los paquetes de comisiones aplican cargos de forma síncrona cuando creas una transacción. Esta sección muestra el proceso, desde la configuración de la comisión hasta los resultados. ### Paso 1 - Crea tus paquetes de comisiones Primero, configura los **paquetes de comisiones** que definen cómo el motor aplica las comisiones. Usa el endpoint [Crear un paquete](/es/reference/products/midaz/v2/create-package). Cada paquete contiene un conjunto de reglas de comisión y criterios de coincidencia. Puedes adaptar los paquetes a distintos ledgers, segmentos y rutas de transacción mediante estos campos: * **transactionRoute** - Identifica la naturaleza de la transacción, cuando necesitas coincidencia en el nivel de ruta. * **segmentId** - Agrupa clientes o tipos de producto, cuando necesitas coincidencia en el nivel de segmento. * **Alcance del ledger** - La URL de la solicitud identifica qué ledger registra la transacción; no envíes `ledgerId` en el cuerpo del paquete. * Monto **mínimo** y **máximo** - Umbrales opcionales para la aplicación de la comisión. * **routeFrom** / **routeTo** - Definen cómo se mueve cada comisión a través de los flujos contables. Esta flexibilidad permite aplicar comisiones distintas por escenario, desde configuraciones basadas en cuentas hasta configuraciones basadas en valor. **Gestión de paquetes** Los siguientes endpoints también están disponibles para gestionar los paquetes: * [Listar paquetes](/es/reference/products/midaz/v2/get-all-packages) - Enumera todos los paquetes creados. * [Obtener un paquete](/es/reference/products/midaz/v2/get-package-by-id) - Obtiene la información de un paquete específico. * [Actualizar un paquete](/es/reference/products/midaz/v2/update-package) - Actualiza la información de un paquete específico. * [Eliminar un paquete](/es/reference/products/midaz/v2/delete-package) - Elimina lógicamente un paquete. ### (opcional) Paso 2 - Ejecuta una estimación Para previsualizar cómo se comporta un paquete de comisiones antes de confirmar una transacción real, usa el endpoint [Estimar comisiones de transacción](/es/reference/products/midaz/v2/estimate-fee-calculation). Esta estimación ayuda a validar: * Qué reglas de comisión se aplican. * Cómo se comportará el paquete con los valores indicados. * Si aplica alguna exención. ### Paso 3 - Crea una transacción Una vez que configures los paquetes, crea la transacción con el endpoint [crear una transacción](/es/reference/products/midaz/v1/create-transaction-json). Indica la misma organización y el mismo ledger en la URL de la solicitud, e incluye los campos de coincidencia configurados, como `transactionRoute` o `segmentId`, para que el motor pueda evaluar el paquete correcto. ### Paso 4 - Fees Engine entra en acción Fees Engine se ejecuta en el mismo proceso cuando Midaz crea la transacción. Evalúa si se aplica un paquete, según: * **transactionRoute**, cuando está configurado * **segmentId**, cuando está configurado * **El alcance del ledger de la URL de la solicitud** * Monto **mínimo** y **máximo** * **waivedAccounts**, cuando está configurado para exenciones de comisiones Fees Engine selecciona solo un paquete por transacción. ### Paso 5 - Verifica las exenciones El sistema verifica: * Si el monto de la transacción está fuera del rango permitido. * Si la cuenta de origen está exenta. Si alguna de las condiciones se cumple, Fees Engine no aplica comisiones y la transacción continúa con normalidad. ### Paso 6 - Cálculo y aplicación de la comisión Si se aplica un paquete, Fees Engine: * Calcula los valores de la comisión según el `applicationRule` seleccionado. * Aplica las comisiones de forma proporcional entre cuentas cuando es necesario. * Usa `isDeductibleFrom` para definir si suma o deduce la comisión. * Enruta las comisiones a la `creditAccount` correcta mediante los valores configurados de `routeFrom` y `routeTo`. * Devuelve el resultado completo de la transacción junto con el `packageAppliedID` en los metadatos. ### Paso 7 - Actualizaciones del ledger Una vez que Fees Engine calcula las comisiones, el componente **Transactions** se hace cargo. Procesa: * Débitos de las cuentas de origen * Créditos a los destinos de la comisión * Desglose de la comisión por ruta y cuenta El ledger almacena cada movimiento para garantizar trazabilidad y auditabilidad completas. ### Paso 8 - Revisa y confirma Después de la ejecución, puedes: * Inspeccionar la transacción final y los montos por cuenta. * Confirmar qué paquete de comisiones se aplicó. * Verificar todos los movimientos de comisión mediante los metadatos y los registros del ledger. ## ¿Por qué estimar una transacción? *** Las estimaciones permiten previsualizar cómo se comporta un paquete de comisiones específico, sin ejecutar una transacción real ni escribir en el ledger. Usa las estimaciones cuando: * Quieres probar un paquete específico. * Depuras reglas de comisión o umbrales. * Quieres validar exenciones, rangos de valor o divisiones proporcionales. * Necesitas una previsualización antes de crear una transacción real. * Construyes una interfaz y quieres mostrar las comisiones estimadas. Fees Engine ofrece el endpoint [Estimar comisiones de transacción](/es/reference/products/midaz/v2/estimate-fee-calculation) para este fin. Envías un `packageId`, y el endpoint devuelve lo que ocurriría si se aplicara **ese paquete exacto**. ### ¿Qué obtienes con una estimación? * Una estimación completa de las reglas de comisión. * Qué cuentas cobraría el motor. * Cómo dividiría el motor la comisión. * Ningún impacto en el ledger. Usa las estimaciones cuando no estés listo para confirmar la transacción, o quieras dar a tus usuarios una previsualización clara de la comisión. ## Errores comunes *** Fees Engine valida cada solicitud para verificar la consistencia y la lógica correcta de las comisiones. A continuación, se muestran los problemas más frecuentes que puedes encontrar al crear paquetes o procesar transacciones. | Code | Title | Message | | :------- | :--------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ | | FEE-0002 | Faltan campos en la solicitud | A tu solicitud le faltan uno o más campos obligatorios. Consulta la documentación para confirmar que se incluyan todos los campos necesarios en tu solicitud. | | FEE-0012 | Entidad no encontrada | No se encontró ninguna entidad para el ID indicado. Confirma que uses el ID correcto de la entidad que intentas gestionar. | | FEE-0013 | Prioridad de comisión inválida | El campo priority en las comisiones no es válido. El campo no puede repetirse. | | FEE-0015 | minimumAmount mayor que maximumAmount | El valor de minimumAmount es mayor que maximumAmount. | | FEE-0022 | Error al calcular la comisión | Error al hacer el cálculo de una comisión de una transacción. | | FEE-0024 | originalAmount es obligatorio cuando priority es uno | Para priority igual a uno, referenceAmount debe ser 'originalAmount' en la comisión. | | FEE-0025 | Error al aplicar la regla: flatFee o percentual | applicationRule flatFee o percentual debe tener exactamente 1 cálculo para la comisión. | | FEE-0035 | Superposición del rango de montos del paquete | El maximumAmount y el minimumAmount del nuevo paquete se superponen con el rango de montos de un paquete existente. | ¿Quieres la lista completa de códigos de error? La encontrarás en la página [Lista de errores de Fees Engine](/es/reference/products/midaz/v2/estimate-fee-calculation) dentro de la [referencia de la API](/es/reference/introduction). ## Paquetes de facturación: workflow por período *** Los paquetes de facturación calculan los cargos según el volumen acumulado de transacciones o el mantenimiento por cuenta durante un período de facturación. A diferencia de los paquetes de comisiones, tu orquestador activa la facturación. Decide cuándo calcular y ejecuta los cargos resultantes. ### Paso 1: crea los paquetes de facturación Configura los paquetes de facturación que definen tus reglas de cargo periódicas. Cada paquete es de tipo **volumen** o **mantenimiento**. **Ejemplo de paquete de volumen**, un cargo por cada Pix enviado con precios escalonados: ```json theme={null} POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages Body: { "label": "Pix Send Monthly Billing", "description": "Monthly volume billing for Pix transactions", "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": "perRoute", "assetCode": "BRL", "debitAccountAlias": "client-wallet", "creditAccountAlias": "fees-revenue" } ``` **Ejemplo de paquete de mantenimiento**, una comisión mensual por cuenta PF activa: ```json theme={null} POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages Body: { "label": "PF Account Maintenance", "description": "Monthly maintenance fee for active PF accounts", "type": "maintenance", "enable": true, "feeAmount": "9.90", "assetCode": "BRL", "maintenanceCreditAccount": "fees-maintenance-pf", "accountTarget": { "segmentId": "seg_pf_01HZ..." } } ``` ### Paso 2: activa el cálculo de facturación Llama a `POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate` con el período de facturación. La URL identifica el ledger. El motor evalúa todos los paquetes de facturación activos que coinciden con los criterios. ```json theme={null} POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate Body: { "period": "2026-03", "type": "volume" } ``` El campo `period` admite tres formatos: `YYYY-MM` (mensual), `YYYY-Www` (semanal, por ejemplo, `2026-W13`) y `YYYY-MM-DD` (diario). El campo `type` es opcional. Usa `"volume"` o `"maintenance"` para restringir el cálculo a un solo tipo. Omítelo para calcular ambos tipos en una sola llamada. ### Paso 3: recibe los resultados del cálculo El motor devuelve un array de resultados. Cada resultado contiene un `transactionPayload` listo para enviarse a Midaz. Cada resultado incluye: * El paquete de facturación que lo generó. * Los montos calculados con el desglose completo (niveles aplicados, descuentos, cuota gratuita descontada). * Un payload de transacción con `source.from` (asientos de débito) y `distribute.to` (asientos de crédito). * Metadatos de auditoría estructurados para la trazabilidad. ### Paso 4: ejecuta los cargos Envía cada `transactionPayload` a Midaz mediante `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 ejecuta los cargos. ### Paso 5: revisa y concilia 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 de cada resultado para la conciliación. * El cálculo de facturación no tiene estado. Puedes volver a ejecutarlo para el mismo período y verificar los resultados. ### Gestión de paquetes de facturación Usa estos endpoints para gestionar los paquetes de facturación existentes: * `GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages`: enumera todos los paquetes de facturación. * `GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{id}`: obtiene un paquete de facturación específico. * `PATCH /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{id}`: actualiza un paquete de facturación (solo `label`, `description`, `enable`). * `DELETE /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{id}`: elimina lógicamente un paquete de facturación. Si algún paquete falla durante el cálculo, toda la operación falla y no devuelve resultados parciales. El cálculo de facturación sigue una política de todo o nada. Corrige el paquete con errores y vuelve a ejecutar.