Pular para o conteúdo principal
O Fees Engine oferece controle poderoso sobre como as taxas são calculadas, aplicadas e rastreadas. Mas com essa flexibilidade vem a necessidade de configuração cuidadosa e disciplina operacional — especialmente em ambientes de produção onde precisão e auditabilidade não são negociáveis. Essas recomendações complementam a visão geral do Fees Engine e o guia de mecânicas de cálculo.

​
1. Projete pacotes de taxas com nomes claros e segmentação

Os pacotes de taxas são a base da sua lógica de tarifação. Uma estrutura de pacotes bem organizada facilita a manutenção, depuração e auditoria da sua configuração de taxas ao longo do tempo.
  • Use nomes descritivos que reflitam o contexto de negócio (ex.: “pix-transfer-standard”, “wire-premium-segment”).
  • Segmente por produto e grupo de clientes usando segmentId. Isso permite aplicar diferentes regras de taxas a diferentes níveis de clientes sem criar pacotes conflitantes.
  • Mantenha os pacotes focados. Um pacote que tenta cobrir muitos cenários se torna difícil de testar e manter. Prefira múltiplos pacotes focados em vez de um que faça tudo.
  • Documente a estrutura dos seus pacotes internamente. À medida que a quantidade de pacotes cresce, uma referência clara de qual pacote se aplica onde previne erros de configuração.

​
2. Configure as prioridades de taxas com cuidado

Quando um pacote contém múltiplas taxas, o campo priority determina a ordem de execução. Errar nisso pode produzir cálculos incorretos.
  • A prioridade 1 deve sempre usar referenceAmount: originalAmount. Isso é aplicado pelo motor.
  • Taxas com isDeductibleFrom: true também devem usar referenceAmount: originalAmount. Isso garante que taxas dedutíveis sejam sempre calculadas contra o valor total da transação.
  • A prioridade deve ser única dentro de um pacote. Prioridades duplicadas serão rejeitadas.
  • Pense nas dependências de taxas. Se uma taxa ajusta o valor da transação e outra taxa deve ser calculada sobre o valor ajustado, use referenceAmount: afterFeesAmount com um número de prioridade maior. Se a segunda taxa deve referenciar o valor original, use originalAmount.
Em caso de dúvida, comece com uma configuração simples (uma ou duas taxas por pacote) e valide os resultados usando o endpoint de simulação antes de adicionar complexidade.

​
3. Sempre simule antes de aplicar taxas em produção

O Fees Engine fornece um endpoint de simulação que permite previsualizar os cálculos de taxas sem escrever nada no ledger. Use a simulação para:
  • Validar novos pacotes antes de ativá-los. Confirme que os valores calculados correspondem aos seus resultados esperados em diferentes valores de transação.
  • Testar casos limite: transações de valor zero, valores de fronteira nos limites de minimumAmount e maximumAmount, e contas isentas.
  • Previsualizar taxas para usuários. Se seu produto exibe taxas antes da confirmação, use o endpoint de simulação para fornecer previsualizações precisas.
  • Depurar resultados inesperados. Se uma taxa calculada não corresponde às expectativas, simule a mesma transação com um packageId específico para isolar o problema.
O endpoint de cálculo seleciona automaticamente o pacote que melhor corresponde. O endpoint de simulação requer um packageId específico, dando a você controle total sobre qual pacote testar.

​
4. Gerencie as isenções de forma explícita

O Fees Engine suporta dois tipos de isenções: por faixa de valor de transação e por conta.
  • Faixas de valor (minimumAmount, maximumAmount): Definem a janela de valor de transação na qual as taxas se aplicam. Transações fora dessa faixa estão isentas. Use isso para limites promocionais ou preços escalonados.
  • Contas isentas (waivedAccounts): Contas específicas isentas de taxas dentro de um pacote. Use isso para contas internas, contas de funcionários ou acordos de parceria.
Boas práticas para isenções:
  • Mantenha as listas de contas isentas curtas e revisadas. Listas grandes se tornam difíceis de auditar. Revise periodicamente quais contas estão isentas e por quê.
  • Documente a razão de negócio de cada isenção nos seus registros internos.
  • Teste os limites de isenção. Se sua faixa é R0–300,certifique−sedequetransac\co~esdeexatamenteR 0–300, certifique-se de que transações de exatamente R 300 e R$ 301 se comportem como esperado.

​
5. Habilite e ajuste o cache para desempenho

O Fees Engine armazena pacotes de taxas em cache na memória para reduzir consultas ao banco de dados durante alto tráfego. Configure o cache através de variáveis de ambiente: 
fees:
  configmap:
    PACKAGE_CACHE_ENABLED: "true"
    PACKAGE_CACHE_TTL_SECONDS: "600"
  • PACKAGE_CACHE_ENABLED (padrão: true): Habilita ou desabilita o cache de pacotes.
  • PACKAGE_CACHE_TTL_SECONDS (padrão: 600): Tempo de vida em segundos antes que os pacotes em cache sejam atualizados a partir do banco de dados.
Recomendações:
  • Mantenha o cache habilitado em produção. Ele reduz significativamente a latência para processamento de transações de alto volume.
  • Ajuste o TTL com base na sua frequência de mudanças. Se você atualiza pacotes frequentemente, use um TTL mais curto (ex.: 60–120 segundos). Se os pacotes são estáveis, o padrão de 600 segundos é apropriado.
  • Esteja ciente do atraso do cache. Após atualizar um pacote, a mudança pode levar até o TTL configurado para se propagar. Se você precisa de efeito imediato, reinicie o serviço ou reduza temporariamente o TTL.

​
6. Use valores numéricos corretos

Todos os valores financeiros no Fees Engine devem ser expressos como strings usando o tipo numeric. Isso previne erros de precisão de ponto flutuante que são comuns com aritmética decimal. 
"value": "12.50"
  • Sempre envie valores como strings, inclusive números inteiros (ex.: "100" e não 100).
  • Nunca use tipos de ponto flutuante para cálculos monetários na sua camada de integração.
  • Esteja ciente de que divisões de taxas envolvendo dízimas periódicas (ex.: dividir R$ 10 entre 3 contas) são automaticamente ajustadas pelo motor para manter os totais do ledger exatos.
O Fees Engine requer Midaz v3.x.x ou posterior. O formato amount + scale do v2.x.x não é compatível. Atualize o Midaz antes de implantar o Fees Engine.

​
7. Use soft delete para auditabilidade

Quando você exclui um pacote de taxas, o Fees Engine o marca com um timestamp deletedAt em vez de removê-lo do banco de dados. Isso preserva a trilha de auditoria para transações históricas que referenciaram esse pacote.
  • Não dependa do hard delete para pacotes de taxas em produção. Transações históricas podem referenciar pacotes excluídos para conciliação.
  • Revise periodicamente os pacotes excluídos se seu banco de dados crescer significativamente. Estratégias de arquivamento podem ajudar a gerenciar o armazenamento sem perder capacidade de auditoria.

​
8. Monitore o Fees Engine em produção

O Fees Engine suporta OpenTelemetry para traces e métricas. Habilite-o para obter visibilidade do desempenho e comportamento dos cálculos de taxas. 
fees:
  configmap:
    ENABLE_TELEMETRY: "true"
    OTEL_RESOURCE_SERVICE_NAME: "plugin-fees"
Em produção:
  • Monitore os endpoints de saúde. O Fees Engine expõe /health para verificações de readiness e liveness (porta padrão: 4002).
  • Configure alertas para latência alta sustentada nos cálculos de taxas, o que pode indicar contenção no banco de dados ou configuração incorreta do cache.
  • Monitore o MongoDB: uso do pool de conexões, espaço em disco e saúde da replicação. O valor padrão de MONGO_MAX_POOL_SIZE é 1000.
  • Revise o uso de recursos dos pods. Os limites padrão são 200m CPU / 256Mi de memória. Ajuste com base nos seus padrões de tráfego e comportamento de autoescalamento.

​
9. Mantenha as versões compatíveis

Antes de atualizar o Fees Engine:
  • Consulte a tabela de compatibilidade de versões para confirmar compatibilidade com sua versão do Midaz Core.
  • Sempre atualize o Midaz Core primeiro, depois o Fees Engine.
  • Faça backup dos seus dados do MongoDB e valores de Helm antes de qualquer atualização maior.
  • Teste a atualização em um ambiente de staging antes de aplicá-la em produção.
Para procedimentos de atualização, consulte o guia de atualização do Helm.

​
10. Revise as recomendações de segurança

O Fees Engine processa dados financeiros e integra com operações do ledger do Midaz. Certifique-se de que seu deploy siga as Recomendações de segurança da plataforma, que cobrem:
  • Segmentação de rede e Arquitetura Zero Trust
  • Gerenciamento e rotação de secrets (incluindo LICENSE_KEY e credenciais do banco de dados)
  • Aplicação de TLS 1.2+ para todas as comunicações
  • Configuração de RBAC via Access Manager
  • Gerenciamento de patches e varredura de vulnerabilidades