Uso de Fees Engine

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. 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 - Enumera todos los paquetes creados.
Obtener un paquete - Obtiene la información de un paquete específico.
Actualizar un paquete - Actualiza la información de un paquete específico.
Eliminar un paquete - 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. 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. 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 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 dentro de la referencia de la API.

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:

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:

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.

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.

Midaz Core

CRM

Fees

Uso de Fees Engine

Paquetes de comisiones: workflow por transacción

Paso 1 - Crea tus paquetes de comisiones

(opcional) Paso 2 - Ejecuta una estimación

Paso 3 - Crea una transacción

Paso 4 - Fees Engine entra en acción

Paso 5 - Verifica las exenciones

Paso 6 - Cálculo y aplicación de la comisión

Paso 7 - Actualizaciones del ledger

Paso 8 - Revisa y confirma

¿Por qué estimar una transacción?

¿Qué obtienes con una estimación?

Errores comunes

Paquetes de facturación: workflow por período

Paso 1: crea los paquetes de facturación

Paso 2: activa el cálculo de facturación

Paso 3: recibe los resultados del cálculo

Paso 4: ejecuta los cargos

Paso 5: revisa y concilia

Gestión de paquetes de facturación

​Paquetes de comisiones: workflow por transacción

​Paso 1 - Crea tus paquetes de comisiones

​(opcional) Paso 2 - Ejecuta una estimación

​Paso 3 - Crea una transacción

​Paso 4 - Fees Engine entra en acción

​Paso 5 - Verifica las exenciones

​Paso 6 - Cálculo y aplicación de la comisión

​Paso 7 - Actualizaciones del ledger

​Paso 8 - Revisa y confirma

​¿Por qué estimar una transacción?

​¿Qué obtienes con una estimación?

​Errores comunes

​Paquetes de facturación: workflow por período

​Paso 1: crea los paquetes de facturación

​Paso 2: activa el cálculo de facturación

​Paso 3: recibe los resultados del cálculo

​Paso 4: ejecuta los cargos

​Paso 5: revisa y concilia

​Gestión de paquetes de facturación

Paquetes de comisiones: workflow por transacción

Paso 1 - Crea tus paquetes de comisiones

(opcional) Paso 2 - Ejecuta una estimación

Paso 3 - Crea una transacción

Paso 4 - Fees Engine entra en acción

Paso 5 - Verifica las exenciones

Paso 6 - Cálculo y aplicación de la comisión

Paso 7 - Actualizaciones del ledger

Paso 8 - Revisa y confirma

¿Por qué estimar una transacción?

¿Qué obtienes con una estimación?

Errores comunes

Paquetes de facturación: workflow por período

Paso 1: crea los paquetes de facturación

Paso 2: activa el cálculo de facturación

Paso 3: recibe los resultados del cálculo

Paso 4: ejecuta los cargos

Paso 5: revisa y concilia

Gestión de paquetes de facturación