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 simulación antes de agregar complejidad.

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

Fees Engine proporciona un endpoint de simulación que te permite previsualizar los cálculos de tarifas sin escribir nada en el ledger. Usa la simulació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 simulación para proporcionar previsualizaciones precisas.
  • Depurar resultados inesperados. Si una tarifa calculada no coincide con las expectativas, simula 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 simulació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