Skip to main content
O Fees Engine controla como você calcula, aplica e rastreia as taxas. O uso em produção exige configuração cuidadosa e disciplina operacional, porque 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. O motor aplica isso.
  • Taxas com isDeductibleFrom: true também devem usar referenceAmount: originalAmount. As taxas dedutíveis se aplicam então sempre ao valor total da transação.
  • A prioridade deve ser única dentro de um pacote. O motor rejeita prioridades duplicadas.
  • 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 estimativa antes de adicionar complexidade.

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

O Fees Engine fornece um endpoint de estimativa que permite previsualizar os cálculos de taxas sem escrever nada no ledger. Use a estimativa 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 estimativa para fornecer previsualizações precisas.
  • Depurar resultados inesperados. Se uma taxa calculada não corresponde às expectativas, estime 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 estimativa 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. Use valores numéricos corretos

Expresse todos os valores financeiros no Fees Engine como strings usando o tipo numeric. Isso previne erros de precisão de ponto flutuante que são comuns com aritmética decimal.
  • 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 o motor ajusta automaticamente as divisões de taxas com dízimas periódicas (ex.: R$ 10 dividido entre 3 contas) 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.

​
6. 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.

​
7. Monitore o processamento de taxas em produção

As taxas são executadas dentro do processo de ledger do Midaz. Use a configuração compartilhada de OpenTelemetry e os endpoints de saúde do ledger para observar o processamento de taxas; consulte Variáveis de ambiente para a configuração suportada. Em produção:
  • Monitore os endpoints de saúde do ledger e seus traces e logs.
  • Configure alertas para latência alta sustentada ou erros nos cálculos de taxas.
  • Monitore o deployment do MongoDB configurado: uso do pool de conexões, espaço em disco e saúde da replicação.
  • Revise o uso de recursos dos pods do ledger com base nos seus padrões de tráfego e comportamento de autoescalamento.

​
8. 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.

​
9. 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

​
10. Projete pacotes de billing com escopo claro

Cada pacote de billing deve representar uma cobrança única e bem definida. Evite agrupar preços não relacionados em um único pacote.
  • Separe pacotes por rota de transação. Um pacote para billing de Pix e um pacote para billing de boleto são mais claros do que um único pacote que tenta lidar com ambos.
  • Use labels descritivos que incluam o tipo de billing e o alvo: “Pix Send Monthly Billing — Standard Tier” é melhor do que “Billing Package 1”.
  • Um tipo de accountTarget por pacote de manutenção. Você não pode combinar segmentId, portfolioId e aliases no mesmo pacote. Se precisar de alvos diferentes, crie pacotes separados — uma única chamada /billing/calculate avalia todos os pacotes ativos.

​
11. Escreva termos comerciais sobre o volume por rota

O cálculo por volume conta transações por rota de transação em todo o ledger. A cota gratuita, as faixas e as faixas de desconto se aplicam a esse total por rota.
  • Expresse os limites como volume por rota. “As primeiras 100 transações na rota pix-send são gratuitas” se traduz diretamente em um pacote. Escreva o contrato nos mesmos termos em que o motor cobra.
  • Separe rotas para separar contagens. Um pacote por rota de transação mantém cada fluxo com sua própria cota, suas faixas e seus descontos.

​
12. Planeje cotas gratuitas e faixas de desconto com cuidado

O Fees Engine avalia cotas gratuitas e descontos em uma ordem específica:
  1. O motor subtrai a cota gratuita do total contado para obter a contagem faturável.
  2. O motor precifica a contagem faturável — em pacotes escalonados, cobra cada unidade faturável pela tarifa da única faixa que corresponde (preço por volume, não graduado).
  3. O motor aplica uma faixa de desconto ao valor bruto, escolhida contra a contagem total (antes de subtrair a cota gratuita).
Considerações de design:
  • Cotas gratuitas são reiniciadas a cada período de billing. Defina o valor com base no seu acordo comercial por período (mensal, semanal ou diário), não vitalício.
  • Faixas são brackets de volume, não fatias. Uma contagem faturável de 1.750 contra uma faixa 501–2.000 cobra todas as 1.750 unidades pela tarifa daquela faixa. Cruzar o limite de um bracket muda a tarifa de todo o volume, então os limites de faixa podem mover a fatura de forma abrupta.
  • Cubra toda contagem faturável positiva. Se a contagem faturável é positiva e o intervalo de nenhuma faixa a contém, o cálculo falha para aquele pacote. Deixe o limite superior da última faixa em aberto. Comece a primeira faixa em 1 — uma contagem faturável de zero produz um valor zero e um payload vazio sem uma busca de faixa.
  • Faixas de desconto são limites cumulativos, não intervalos, e apenas uma se aplica: o maior minQuantity que a contagem total alcança. Se você definir descontos em 200 e 400 transações, um cliente com 500 transações recebe o desconto de 400+ — não ambos.
  • Atenção às duas contagens diferentes. A precificação usa a contagem faturável (após a cota gratuita); o desconto usa a contagem total (antes dela).
Use cálculos de teste com contagens de transações conhecidas para validar sua configuração de faixas e descontos antes de habilitar o pacote em produção.

​
13. Dimensione os alvos de contas de manutenção adequadamente

Os pacotes de manutenção suportam três tipos de alvo com diferentes perfis de escala: Escolha o tipo de alvo que corresponde à sua escala operacional. Se você se encontrar listando centenas de aliases, migre para um segmento ou portfólio no Midaz.

​
14. Trate falhas de billing com re-execução

O cálculo de billing segue uma política tudo-ou-nada. Se qualquer pacote falhar, o motor não retorna nenhum resultado.
  • Implemente lógica de retry no seu orquestrador. O cálculo é stateless — re-executar para o mesmo período produz os mesmos resultados.
  • Verifique as respostas de erro para identificar o pacote e recurso específicos que falharam. Causas comuns: ledgerId inválido, API do Midaz inacessível ou pacotes de billing desabilitados.
  • Separe cálculos de volume e manutenção se um tipo consistentemente tem sucesso enquanto o outro falha. Chame /billing/calculate com "type": "volume" e "type": "maintenance" independentemente para isolar falhas.