> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Boas práticas
> Boas práticas de configuração, operação e integração para implantar e usar o Fees Engine em produção.
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](/pt/midaz/fees/fees-engine-overview) e o guia de [mecânicas de cálculo](/pt/midaz/fees/fee-engine-calculation).
## 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 estimativa antes de adicionar complexidade.
## 3. Sempre estime antes de aplicar taxas em produção
***
O Fees Engine fornece um [endpoint de estimativa](/pt/reference/midaz/plugins/fees-engine/simulate-fees) 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](/pt/reference/midaz/plugins/fees-engine/calculate-fees) 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 é R$ 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:
```yaml theme={null}
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.
```json theme={null}
"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.
```yaml theme={null}
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](/pt/platform/plugins/midaz-version-compatibility) 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](/pt/platform/helm/midaz/midaz-upgrade-guide).
## 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](/pt/midaz/security-recommendations) 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](/pt/platform/access-manager/access-manager)
* Gerenciamento de patches e varredura de vulnerabilidades
## 11. 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.
## 12. Escolha o modo de contagem correto
***
O campo `countMode` em pacotes de volume determina como as transações são agrupadas para precificação:
* **`perRoute`** — Conta todas as transações correspondentes como um total único em toda a organização. Use quando o preço se aplica ao volume agregado, independentemente de qual conta gerou as transações.
* **`perAccount`** — Conta transações por conta individual e aplica as faixas de preço independentemente. Use quando cada conta de cliente tem seu próprio preço baseado em volume.
A escolha errada produz cobranças incorretas. Se seu modelo de preços diz "as primeiras 100 transações por cliente são gratuitas", use `perAccount`. Se diz "as primeiras 100 transações em toda a plataforma são gratuitas", use `perRoute`.
## 13. Planeje cotas gratuitas e faixas de desconto com cuidado
***
Cotas gratuitas e descontos progressivos são avaliados em uma ordem específica:
1. A cota gratuita é subtraída do total contado primeiro.
2. As faixas de preço são aplicadas à contagem restante.
3. As faixas de desconto são aplicadas ao valor total resultante.
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 ou diário), não vitalício.
* **Faixas de desconto são limites cumulativos**, não intervalos. Se você definir descontos em 200 e 400 transações, um cliente com 500 transações recebe o desconto de 400+ — não ambos.
* **Teste os limites das suas faixas**. Verifique se a transição entre faixas produz os resultados esperados, especialmente quando o `freeQuota` empurra a contagem faturável para uma faixa inferior à esperada.
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.
## 14. 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:
| Tipo de alvo | Escala | Caso de uso |
| ------------- | ------------------ | ------------------------------------------------------ |
| `segmentId` | 100.000+ contas | Níveis padrão (PF, PJ, premium) |
| `portfolioId` | Milhares de contas | Portfólios empresariais (PME, Corporativo, Enterprise) |
| `aliases` | Até 100 contas | Contas nomeadas específicas |
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.
## 15. Trate falhas de billing com re-execução
***
O cálculo de billing segue uma política tudo-ou-nada. Se qualquer pacote falhar, nenhum resultado é retornado.
* **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.