Saltar al contenido principal
Fees Engine te da un control poderoso sobre cómo se calculan, aplican y rastrean las tarifas. Pero con esa flexibilidad viene la necesidad de una configuración cuidadosa y disciplina operacional — especialmente en entornos de producción donde la precisión y la auditabilidad no son negociables. Estas recomendaciones complementan el resumen de Fees Engine y la guía de mecánicas de cálculo.

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

Los paquetes de tarifas son la base de tu lógica de tarifas. Una estructura de paquetes bien organizada facilita el mantenimiento, la depuración y la auditoría de tu configuración de tarifas a lo largo del tiempo.
  • Usa nombres descriptivos que reflejen el contexto de negocio (ej., “pix-transfer-standard”, “wire-premium-segment”).
  • Segmenta por producto y grupo de clientes usando segmentId. Esto te permite aplicar diferentes reglas de tarifas a diferentes niveles de clientes sin crear paquetes en conflicto.
  • Mantén los paquetes enfocados. Un paquete que intenta cubrir demasiados escenarios se vuelve difícil de probar y mantener. Prefiere múltiples paquetes enfocados sobre uno que lo haga todo.
  • Documenta la estructura de tus paquetes internamente. A medida que la cantidad de paquetes crece, una referencia clara de qué paquete aplica dónde previene errores de configuración.

​
2. Configura las prioridades de tarifas con cuidado

Cuando un paquete contiene múltiples tarifas, el campo priority determina el orden de ejecución. Equivocarse en esto puede producir cálculos incorrectos.
  • La prioridad 1 siempre debe usar referenceAmount: originalAmount. Esto es aplicado por el motor.
  • Las tarifas con isDeductibleFrom: true también deben usar referenceAmount: originalAmount. Esto asegura que las tarifas deducibles siempre se calculen contra el valor total de la transacción.
  • La prioridad debe ser única dentro de un paquete. Las prioridades duplicadas serán rechazadas.
  • Piensa en las dependencias de tarifas. Si una tarifa ajusta el valor de la transacción y otra tarifa debe calcularse sobre el valor ajustado, usa referenceAmount: afterFeesAmount con un número de prioridad mayor. Si la segunda tarifa debe referir al valor original, usa originalAmount.
En caso de duda, comienza con una configuración simple (una o dos tarifas por paquete) y valida los resultados usando el endpoint de estimación antes de agregar complejidad.

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

Fees Engine proporciona un endpoint de estimación que te permite previsualizar los cálculos de tarifas sin escribir nada en el ledger. Usa la estimación para:
  • Validar nuevos paquetes antes de activarlos. Confirma que los valores calculados coincidan con tus resultados esperados en diferentes montos de transacción.
  • Probar casos límite: transacciones de monto cero, valores límite en los umbrales de minimumAmount y maximumAmount, y cuentas exentas.
  • Previsualizar tarifas para usuarios. Si tu producto muestra tarifas antes de la confirmación, usa el endpoint de estimación para proporcionar previsualizaciones precisas.
  • Depurar resultados inesperados. Si una tarifa calculada no coincide con las expectativas, 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, dándote control total sobre qué paquete probar.

​
4. Gestiona las exenciones de forma explícita

Fees Engine soporta 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 aplican las tarifas. Las transacciones fuera de este rango están exentas. Usa esto para umbrales promocionales o precios escalonados.
  • Cuentas exentas (waivedAccounts): Cuentas específicas exentas de tarifas dentro de un paquete. Usa esto para cuentas internas, cuentas de empleados o acuerdos de asociación.
Mejores prácticas para 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 exención. Si tu rango es R0–300,aseguˊratedequelastransaccionesdeexactamenteR 0–300, asegúrate de que las transacciones de exactamente R 300 y R$ 301 se comporten como se espera.

​
5. Habilita y ajusta el caché para rendimiento

Fees Engine almacena en caché los paquetes de tarifas en memoria para reducir las consultas a la base de datos durante alto tráfico. Configura el caché mediante variables de entorno: 
fees:
  configmap:
    PACKAGE_CACHE_ENABLED: "true"
    PACKAGE_CACHE_TTL_SECONDS: "600"
  • PACKAGE_CACHE_ENABLED (predeterminado: true): Habilita o deshabilita el caché de paquetes.
  • PACKAGE_CACHE_TTL_SECONDS (predeterminado: 600): Tiempo de vida en segundos antes de que los paquetes en caché se actualicen desde la base de datos.
Recomendaciones:
  • Mantén el caché habilitado en producción. Reduce significativamente la latencia para procesamiento de transacciones de alto volumen.
  • Ajusta el TTL según tu frecuencia de cambios. Si actualizas paquetes frecuentemente, usa un TTL más corto (ej., 60–120 segundos). Si los paquetes son estables, el valor predeterminado de 600 segundos es apropiado.
  • Ten en cuenta el retraso del caché. Después de actualizar un paquete, el cambio puede tardar hasta el TTL configurado en propagarse. Si necesitas efecto inmediato, reinicia el servicio o reduce temporalmente el TTL.

​
6. Usa valores numéricos correctos

Todos los valores financieros en Fees Engine deben expresarse como strings usando el tipo numeric. Esto previene errores de precisión de punto flotante que son comunes con aritmética decimal. 
"value": "12.50"
  • Siempre envía valores como strings, incluso números enteros (ej., "100" no 100).
  • Nunca uses tipos de punto flotante para cálculos monetarios en tu capa de integración.
  • Ten en cuenta que las divisiones de tarifas que involucran decimales periódicos (ej., dividir R$ 10 entre 3 cuentas) se ajustan automáticamente por el motor para mantener los totales del Ledger exactos.
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.

​
7. Usa soft delete para auditabilidad

Cuando eliminas un paquete de tarifas, Fees Engine lo marca con un timestamp deletedAt en lugar de eliminarlo de la base de datos. Esto preserva la pista de auditoría para transacciones históricas que referenciaron ese paquete.
  • No dependas del hard delete para paquetes de tarifas en producción. Las transacciones históricas pueden referenciar paquetes eliminados para conciliación.
  • Revisa periódicamente los paquetes eliminados si tu base de datos crece significativamente. Las estrategias de archivado pueden ayudar a gestionar el almacenamiento sin perder capacidad de auditoría.

​
8. Monitorea Fees Engine en producción

Fees Engine soporta OpenTelemetry para trazas y métricas. Habilítalo para obtener visibilidad del rendimiento y comportamiento de los cálculos de tarifas. 
fees:
  configmap:
    ENABLE_TELEMETRY: "true"
    OTEL_RESOURCE_SERVICE_NAME: "plugin-fees"
En producción:
  • Monitorea los endpoints de salud. Fees Engine expone /health para verificaciones de readiness y liveness (puerto predeterminado: 4002).
  • Configura alertas para latencia alta sostenida en cálculos de tarifas, lo que puede indicar contención en la base de datos o mala configuración del caché.
  • Monitorea MongoDB: uso del pool de conexiones, espacio en disco y salud de replicación. El valor predeterminado de MONGO_MAX_POOL_SIZE es 1000.
  • Revisa el uso de recursos de los pods. Los límites predeterminados son 200m CPU / 256Mi de memoria. Ajusta según tus patrones de tráfico y comportamiento de autoescalado.

​
9. Mantén las versiones compatibles

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

​
10. Revisa las recomendaciones de seguridad

Fees Engine procesa datos financieros e integra con operaciones del Ledger de Midaz. Asegúrate de que tu despliegue siga las Recomendaciones de seguridad de la plataforma, que cubren:
  • Segmentación de red y Arquitectura Zero Trust
  • Gestión y rotación de secretos (incluyendo LICENSE_KEY y credenciales de base de datos)
  • Aplicación de TLS 1.2+ para todas las comunicaciones
  • Configuración de RBAC vía Access Manager
  • Gestión de parches y escaneo de vulnerabilidades

​
11. Diseña billing packages con alcance claro

Cada billing package debe representar un cargo único y bien definido. Evita empaquetar precios no relacionados en un solo paquete.
  • Paquetes separados por ruta de transacción. Un paquete para facturación de Pix y un paquete para facturación de boletos son más claros que un solo paquete que intente 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 diferentes objetivos, crea paquetes separados — una sola llamada a /billing/calculate evalúa todos los paquetes activos.

​
12. Elige el modo de conteo correcto

El campo countMode en paquetes de volumen determina cómo se agrupan las transacciones para el cálculo de precios:
  • perRoute — Cuenta todas las transacciones coincidentes como un total único en toda la organización. Usa esto cuando el precio se aplica al volumen agregado independientemente de qué cuenta generó las transacciones.
  • perAccount — Cuenta transacciones por cuenta individual y aplica niveles de precios de forma independiente. Usa esto cuando cada cuenta de cliente tiene su propio precio basado en volumen.
Una elección incorrecta produce cargos incorrectos. Si tu modelo de precios dice “las primeras 100 transacciones por cliente son gratuitas”, usa perAccount. Si dice “las primeras 100 transacciones en toda la plataforma son gratuitas”, usa perRoute.

​
13. Planifica cuotas gratuitas y niveles de descuento con cuidado

Las cuotas gratuitas y los descuentos progresivos se evalúan en un orden específico:
  1. La cuota gratuita se resta del conteo total primero.
  2. Los niveles de precios se aplican al conteo restante.
  3. Los niveles de descuento se aplican al monto total resultante.
Consideraciones de diseño:
  • Las cuotas gratuitas se reinician cada período de facturación. Establece el valor basándote en tu acuerdo comercial por período (mensual o diario), no de por vida.
  • Los niveles de descuento son umbrales acumulativos, no rangos. Si defines descuentos en 200 y 400 transacciones, un cliente con 500 transacciones obtiene el descuento de 400+ — no ambos.
  • Prueba los límites de tus niveles. Verifica que la transición entre niveles produzca los resultados esperados, especialmente cuando freeQuota empuja el conteo facturable a un nivel inferior al esperado.
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.

​
14. Dimensiona los objetivos de cuentas de mantenimiento apropiadamente

Los paquetes de mantenimiento soportan tres tipos de objetivo con diferentes perfiles de escala:
Tipo de objetivoEscalaCaso de uso
segmentId100,000+ cuentasNiveles estándar (PF, PJ, premium)
portfolioIdMiles de cuentasPortfolios empresariales (PME, Corporate, Enterprise)
aliasesHasta 100 cuentasCuentas específicas nombradas
Elige el tipo de objetivo que coincida con tu escala operacional. Si te encuentras listando cientos de aliases, migra a un segmento o portfolio en Midaz en su lugar.

​
15. Maneja fallos de facturación con re-ejecución

El cálculo de facturación sigue una política de todo-o-nada. Si algún paquete falla, no se devuelven resultados.
  • Construye lógica de reintentos en tu orquestador. El cálculo no tiene estado — re-ejecutarlo para el mismo período produce los mismos resultados.
  • Revisa las respuestas de error para identificar el paquete y recurso específico que falló. Causas comunes: ledgerId inválido, API de Midaz inaccesible o billing packages deshabilitados.
  • Separa los cálculos de volumen y mantenimiento si un tipo tiene éxito consistentemente mientras el otro falla. Llama a /billing/calculate con "type": "volume" y "type": "maintenance" de forma independiente para aislar los fallos.