Usando Fees Engine

Fees Engine aplica tarifas por transacción y calcula cargos de facturación periódicos. Esta guía cubre 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

Los fee packages aplican cargos de forma síncrona cuando creas una transacción. Esta sección muestra el proceso, desde la configuración de tarifas hasta los resultados.

Paso 1 - Crear tus paquetes de tarifas

Primero, configura paquetes de tarifas que definen cómo el motor aplica las tarifas. Usa el endpoint Create a 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 con estos campos:

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 - Lista todos los paquetes creados.
Retrieve a Package - Recupera información de un paquete específico.
Update a Package - Actualiza la información de un paquete específico.
Delete a Package - Eliminación suave de un paquete.

(opcional) Paso 2 - Ejecutar una estimación

Para previsualizar cómo se comporta 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 aplican.
Cómo se comportará el paquete con los valores dados.
Si se aplican exenciones.

Paso 3 - Crear una transacción

Una vez que configures los paquetes, crea la transacción con el endpoint create a transaction. 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 llama automáticamente al endpoint Calculate Fees for a Package. Evalúa si un paquete aplica, con base en:

transactionRoute, cuando esté configurado
segmentId, cuando esté configurado
ledgerId
Minimum y maximum amount
waivedAccounts, cuando esté configurado para exenciones de tarifas

Fees Engine selecciona solo 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 cualquiera de estas condiciones es verdadera, Fees Engine no aplica tarifas y la transacción procede normalmente.

Paso 6 - Cálculo y aplicación de tarifas

Si un paquete aplica, 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 agrega o deduce la tarifa.
Enruta tarifas a la creditAccount correcta con 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 Fees Engine calcula las tarifas, 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

El Ledger almacena cada movimiento 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 qué paquete de tarifas 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. Pasas un packageId y el endpoint devuelve lo que sucedería si aplicara ese paquete exacto.

¿Qué obtienes con una estimación?

Una estimación completa de las reglas de tarifas.
Qué cuentas cobraría el motor.
Cómo dividiría la tarifa el motor.
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 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, tu orquestador activa la facturación. 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 resultado contiene un transactionPayload listo para enviar 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 ejecuta 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.

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 que falló y re-ejecuta.

Midaz Core

CRM

Fees

Usando Fees Engine

Fee packages: flujo de trabajo por transacción

Paso 1 - Crear tus paquetes de tarifas

(opcional) Paso 2 - Ejecutar una estimación

Paso 3 - Crear una transacción

Paso 4 - El Fees Engine entra en acción

Paso 5 - Verificar exenciones

Paso 6 - Cálculo y aplicación de tarifas

Paso 7 - Actualizaciones del Ledger

Paso 8 - Revisar y confirmar

¿Por qué estimar una transacción?

¿Qué obtienes con una estimación?

Errores comunes

Billing packages: flujo de trabajo por período

Paso 1 — Crear billing packages

Paso 2 — Activar el cálculo de facturación

Paso 3 — Recibir los resultados del cálculo

Paso 4 — Ejecutar los cargos

Paso 5 — Revisar y conciliar

Gestión de billing packages

​Fee packages: flujo de trabajo por transacción

​Paso 1 - Crear tus paquetes de tarifas

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

​Paso 3 - Crear una transacción

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

​Paso 5 - Verificar exenciones

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

​Paso 7 - Actualizaciones del Ledger

​Paso 8 - Revisar y confirmar

​¿Por qué estimar una transacción?

​¿Qué obtienes con una estimación?

​Errores comunes

​Billing packages: flujo de trabajo por período

​Paso 1 — Crear billing packages

​Paso 2 — Activar el cálculo de facturación

​Paso 3 — Recibir los resultados del cálculo

​Paso 4 — Ejecutar los cargos

​Paso 5 — Revisar y conciliar

​Gestión de billing packages

Fee packages: flujo de trabajo por transacción

Paso 1 - Crear tus paquetes de tarifas

(opcional) Paso 2 - Ejecutar una estimación

Paso 3 - Crear una transacción

Paso 4 - El Fees Engine entra en acción

Paso 5 - Verificar exenciones

Paso 6 - Cálculo y aplicación de tarifas

Paso 7 - Actualizaciones del Ledger

Paso 8 - Revisar y confirmar

¿Por qué estimar una transacción?

¿Qué obtienes con una estimación?

Errores comunes

Billing packages: flujo de trabajo por período

Paso 1 — Crear billing packages

Paso 2 — Activar el cálculo de facturación

Paso 3 — Recibir los resultados del cálculo

Paso 4 — Ejecutar los cargos

Paso 5 — Revisar y conciliar

Gestión de billing packages