Skip to main content
Fees Engine controla cómo calculas, aplicas y das seguimiento a las comisiones. El uso en producción exige una configuración cuidadosa y disciplina operativa. Estas recomendaciones complementan la descripción general de Fees Engine y la guía de mecánica de cálculo.

​
1. Diseña paquetes de comisiones con nombres claros y segmentación

Una estructura de paquetes bien organizada facilita el mantenimiento, la depuración y la auditoría de tu configuración de comisiones a lo largo del tiempo.
  • Usa nombres descriptivos que reflejen el contexto de negocio (por ejemplo, “pix-transfer-standard”, “wire-premium-segment”).
  • Segmenta por producto y grupo de clientes usando segmentId. Esto permite aplicar distintas reglas de comisiones a diferentes niveles de clientes sin crear paquetes conflictivos.
  • Mantén los paquetes enfocados. Un paquete que intenta cubrir demasiados escenarios se vuelve difícil de probar y mantener. Prefiere varios paquetes enfocados en lugar de uno que lo haga todo.
  • Documenta la estructura de tus paquetes internamente. A medida que crece la cantidad de paquetes, una referencia clara de dónde se aplica cada uno evita configuraciones incorrectas.

​
2. Establece las prioridades de comisiones con cuidado

Cuando un paquete contiene varias comisiones, el campo priority determina el orden de ejecución. Si te equivocas aquí, puedes producir cálculos incorrectos.
  • La prioridad 1 siempre debe usar referenceAmount: originalAmount. El motor exige esto.
  • Las comisiones con isDeductibleFrom: true también deben usar referenceAmount: originalAmount. Las comisiones deducibles entonces siempre se aplican sobre el valor total de la transacción.
  • La prioridad debe ser única dentro de un paquete. El motor rechaza prioridades duplicadas.
  • Piensa en las dependencias entre comisiones. Si una comisión ajusta el valor de la transacción y se recomienda que se calcule otra comisión sobre el valor ajustado, usa referenceAmount: afterFeesAmount con un número de prioridad mayor. Si se recomienda que la segunda comisión haga referencia al valor original, usa originalAmount.
Si tienes dudas, empieza con una configuración simple (una o dos comisiones por paquete) y valida los resultados con el endpoint de estimación antes de agregar complejidad.

​
3. Siempre estima antes de aplicar comisiones en producción

Fees Engine ofrece un endpoint de estimación que permite previsualizar los cálculos de comisiones sin escribir nada en el ledger. Usa la estimación para:
  • Validar paquetes nuevos antes de activarlos. Confirma que los valores calculados coincidan con los resultados esperados en distintos montos de transacción.
  • Probar casos límite: transacciones de monto cero, valores frontera en los umbrales de minimumAmount y maximumAmount, y cuentas exentas.
  • Previsualizar comisiones para los usuarios. Si tu producto muestra las comisiones antes de la confirmación, usa el endpoint de estimación para ofrecer previsualizaciones precisas.
  • Depurar resultados inesperados. Si una comisión calculada no coincide con lo esperado, estima la misma transacción con un packageId específico para aislar el problema.
El endpoint de cálculo selecciona automáticamente el paquete que mejor coincide. El endpoint de estimación requiere un packageId específico, lo que te da control total sobre qué paquete probar.

​
4. Administra las exenciones de forma explícita

Fees Engine admite dos tipos de exenciones: por rango de monto de transacción y por cuenta.
  • Rangos de monto (minimumAmount, maximumAmount): definen la ventana de valor de transacción en la que se aplican las comisiones. Las transacciones fuera de este rango están exentas. Úsalo para umbrales promocionales o precios escalonados.
  • Cuentas exentas (waivedAccounts): cuentas específicas exentas de comisiones dentro de un paquete. Úsalo para cuentas internas, cuentas de empleados o acuerdos de asociación.
Mejores prácticas para las exenciones:
  • Mantén las listas de cuentas exentas cortas y revisadas. Las listas grandes se vuelven difíciles de auditar. Revisa periódicamente qué cuentas están exentas y por qué.
  • Documenta la razón de negocio de cada exención en tus registros internos.
  • Prueba los límites de la exención. Si tu rango es R0–300,confirmaquelastransaccionesenexactamenteR 0–300, confirma que las transacciones en exactamente R 300 y R$ 301 se comporten como se espera.

​
5. Usa los valores numéricos correctos

Expresa todos los valores financieros en Fees Engine como strings usando el tipo numeric. Esto evita errores de precisión de punto flotante que son comunes con la aritmética decimal.
  • Siempre envía los valores como strings, incluso los números enteros (por ejemplo, "100" y no 100).
  • Nunca uses tipos de punto flotante para cálculos monetarios en tu capa de integración.
  • El motor ajusta automáticamente las divisiones de comisiones con decimales periódicos (por ejemplo, R$ 10 dividido entre 3 cuentas) para mantener exactos los totales del ledger.
Fees Engine requiere Midaz v3.x.x o posterior. El formato amount + scale de v2.x.x no es compatible. Actualiza Midaz antes de desplegar Fees Engine.

​
6. Usa eliminación lógica para la auditabilidad

Cuando eliminas un paquete de comisiones, Fees Engine lo marca con una marca de tiempo deletedAt en lugar de eliminarlo de la base de datos. Esto conserva el registro de auditoría de las transacciones históricas que hicieron referencia a ese paquete.
  • No dependas de la eliminación física para los paquetes de comisiones en producción. Las transacciones históricas pueden hacer referencia a paquetes eliminados para la conciliación.
  • Revisa periódicamente los paquetes eliminados si tu base de datos crece significativamente. Las estrategias de archivado pueden ayudar a administrar el almacenamiento sin perder la capacidad de auditoría.

​
7. Supervisa el procesamiento de comisiones en producción

Las comisiones se ejecutan dentro del proceso del ledger de Midaz. Usa la configuración compartida de OpenTelemetry del ledger y los endpoints de salud para observar el procesamiento de comisiones. Consulta Variables de entorno para conocer la configuración compatible. En producción:
  • Supervisa los endpoints de salud del ledger y sus trazas y logs.
  • Configura alertas para latencia sostenida alta o errores en los cálculos de comisiones.
  • Supervisa el despliegue de MongoDB configurado: uso del pool de conexiones, espacio en disco y estado de la replicación.
  • Revisa el uso de recursos del pod del ledger según tus patrones de tráfico y el comportamiento de autoescalado.

​
8. Mantén las versiones compatibles

Antes de actualizar Fees Engine:
  • Consulta la tabla de compatibilidad de versiones para confirmar la compatibilidad con tu versión de Midaz Core.
  • Siempre actualiza primero Midaz Core y después Fees Engine.
  • Respalda tus datos de MongoDB y tus valores de Helm antes de cualquier actualización mayor.
  • Prueba la actualización en un entorno de staging antes de aplicarla a producción.
Para conocer los procedimientos de actualización, consulta la guía de actualización de Helm.

​
9. Revisa las recomendaciones de seguridad

Fees Engine procesa datos financieros y se integra con las operaciones del ledger de Midaz. Confirma que tu despliegue siga las Recomendaciones de seguridad de toda la plataforma, que cubren:
  • Segmentación de red y arquitectura Zero Trust
  • Gestión y rotación de secretos (incluida LICENSE_KEY y las credenciales de la base de datos)
  • Aplicación de TLS 1.2+ para todas las comunicaciones
  • Configuración de RBAC mediante Access Manager
  • Gestión de parches y análisis de vulnerabilidades

​
10. Diseña paquetes de facturación con un alcance claro

Se recomienda que cada paquete de facturación represente un cargo único y bien definido. Evita agrupar precios no relacionados en un mismo paquete.
  • Separa los paquetes por ruta de transacción. Un paquete para la facturación de Pix y un paquete para la facturación de boletos son más claros que un solo paquete que intenta manejar ambos.
  • Usa etiquetas descriptivas que incluyan el tipo de facturación y el objetivo: “Pix Send Monthly Billing — Standard Tier” es mejor que “Billing Package 1”.
  • Un tipo de accountTarget por paquete de mantenimiento. No puedes combinar segmentId, portfolioId y aliases en el mismo paquete. Si necesitas objetivos distintos, crea paquetes separados. Una sola llamada a /billing/calculate evalúa todos los paquetes activos.

​
11. Redacta los términos comerciales en función del volumen de la ruta

El cálculo por volumen cuenta las transacciones por ruta de transacción en todo el ledger. La cuota gratuita, los niveles y los niveles de descuento se aplican todos a ese total en el nivel de ruta.
  • Expresa los umbrales como volumen de ruta. “Las primeras 100 transacciones en la ruta pix-send son gratuitas” se traduce directamente en un paquete. Redacta el contrato en los mismos términos en que el motor factura.
  • Divide las rutas para dividir los conteos. Un paquete por ruta de transacción mantiene cada flujo con su propia cuota, niveles y descuentos.

​
12. Planifica las cuotas gratuitas y los niveles de descuento con cuidado

Fees Engine evalúa las cuotas gratuitas y los descuentos en un orden específico:
  1. El motor resta la cuota gratuita del conteo total para obtener el conteo facturable.
  2. El motor calcula el precio del conteo facturable. Para los paquetes escalonados, cobra cada unidad facturable a la tarifa del único nivel coincidente (precios por volumen, no graduales).
  3. El motor aplica un nivel de descuento al monto bruto, elegido según el conteo total (antes de restar la cuota gratuita).
Consideraciones de diseño:
  • Las cuotas gratuitas se reinician en cada período de facturación. Establece el valor según tu acuerdo comercial por período (mensual, semanal o diario), no de por vida.
  • Los niveles son tramos de volumen, no rebanadas. Un conteo facturable de 1,750 contra un nivel de 501–2,000 cobra las 1,750 unidades a la tarifa de ese nivel. Cruzar el límite de un tramo cambia la tarifa para todo el volumen, por lo que los límites de nivel pueden mover la factura de forma abrupta.
  • Cubre cada conteo facturable positivo. Si el conteo facturable es positivo y ningún rango de nivel lo contiene, el cálculo falla para ese paquete. Deja abierto el límite superior del nivel más alto. Empieza el primer nivel en 1 (un conteo facturable de cero produce un monto cero y un payload vacío sin una búsqueda de nivel).
  • Los niveles de descuento son umbrales acumulativos, no rangos, y solo se aplica uno: el minQuantity más alto que el conteo total alcanza. Si defines descuentos en 200 y 400 transacciones, un cliente con 500 transacciones obtiene el descuento de 400+, no ambos.
  • Presta atención a los dos conteos distintos. El precio usa el conteo facturable (después de la cuota gratuita); el descuento usa el conteo total (antes de ella).
Usa cálculos de prueba con conteos de transacciones conocidos para validar tu configuración de niveles y descuentos antes de habilitar el paquete en producción.

​
13. Dimensiona los objetivos de cuentas de mantenimiento de forma adecuada

Los paquetes de mantenimiento admiten tres tipos de objetivo con diferentes perfiles de escala: Elige el tipo de objetivo que coincida con tu escala operativa. Si te encuentras enumerando cientos de alias, migra a un segmento o portafolio en Midaz en su lugar.

​
14. Maneja los fallos de facturación mediante la reejecución

El cálculo de facturación sigue una política de todo o nada. Si algún paquete falla, el motor no devuelve resultados.
  • Incorpora lógica de reintento en tu orquestador. El cálculo no tiene estado. Volver a ejecutarlo para el mismo período produce los mismos resultados.
  • Revisa las respuestas de error para el paquete y el recurso específicos que fallaron. Causas comunes: ledgerId inválido, API de Midaz inalcanzable o paquetes de facturación deshabilitados.
  • Separa los cálculos de volumen y mantenimiento si un tipo tiene éxito de forma consistente mientras el otro falla. Llama a /billing/calculate con "type": "volume" y "type": "maintenance" de forma independiente para aislar los fallos.