Saltar al contenido principal
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. Cada paquete contiene un conjunto de reglas de tarifas y criterios de coincidencia. Puedes adaptar paquetes a diferentes segmentos o Ledgers usando:
  • transactionRoute – Identifica la naturaleza de la transacción.
  • segmentId – Agrupa clientes o tipos de productos.
  • 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:

​
(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. 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. Incluye el transactionRoute, segmentId y ledgerId apropiados para que el motor pueda evaluar el paquete coincidente.

​
Paso 4 - El Fees Engine entra en acción

Fees Engine envía automáticamente una llamada al endpoint Calculate Fees for a Package y evalúa si un paquete aplica basándose en:
  • transactionRoute
  • segmentId
  • ledgerId
  • Minimum y maximum amount
  • waivedAccounts (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 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ódigoTítuloMensaje
FEE-0002Campos faltantes en la solicitudTu 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-0012Entidad no encontradaNo 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-0013Prioridad de tarifa inválidaEl campo priority en fees es inválido. El campo no puede estar repetido.
FEE-0015minimumAmount mayor que maximumAmountEl valor de minimumAmount es mayor que maximumAmount.
FEE-0022Falló el cálculo de tarifaError al hacer el cálculo de una tarifa sobre una transacción.
FEE-0024originalAmount es requerido cuando priority es unoPara Priority igual a uno, referenceAmount debe ser ‘originalAmount’ para fee.
FEE-0025Falló aplicar regla: flatFee o percentualapplicationRule flatFee o percentual debe tener exactamente 1 cálculo para Fee.
FEE-0035Superposición de rango de monto del paqueteEl 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 en la API reference.

​
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: 
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: 
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. 
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.