O que é Fees Engine?

​

Por que usar o Fees Engine?

---

O plugin Fees Engine ajuda você a gerenciar facilmente lógicas complexas de taxas. Seja aplicando uma taxa fixa, distribuindo taxas proporcionalmente ou simulando transações antecipadamente, este plugin foi criado para flexibilidade e escala. Veja o que ele possibilita:

• Configuração flexível de taxas via pacotes de taxas — personalizados para grupos de contas ou ledgers específicos.
• Múltiplos métodos de cálculo: taxas fixas, taxas percentuais e lógica de “máximo entre tipos”.
• Distribuição proporcional de taxas para fluxos de marketplace e operações multi-conta.
• Suporte a rotas contábeis via transactionRoute, routeFrom e routeTo.
• Ferramentas de simulação para visualizar cálculos antes de executar transações.
• Lógica de isenção de taxas por conta e faixas de valor de transação.
• Aplicação baseada em prioridade para controlar a ordem em que múltiplas taxas são aplicadas.
• Mecânica precisa de dedução com suporte a isDeductibleFrom.

​

O que são taxas?

---

Taxas são valores monetários cobrados em troca de serviços, produtos ou acesso a recursos. Seu objetivo depende do setor, mas a necessidade de clareza e consistência é universal. Abaixo estão apenas alguns exemplos:

​

Finanças

No setor financeiro, taxas são aplicadas para cobrir custos operacionais e garantir conformidade legal.

• Taxa de manutenção de conta: Mantém as contas operacionais e cobre custos administrativos.
• Taxa de transferência: Cobrada por transações como TEDs ou transferências internacionais.

​

Logística e transporte

No setor de logística, taxas estão relacionadas ao uso de serviços de transporte e armazenamento.

• Taxa de manuseio: Aplicada durante o armazenamento e movimentação física de mercadorias.
• Taxa de descarga: Cobre operações de descarga nos pontos de entrega.

​

Farmacêutico e saúde

No setor farmacêutico, taxas visam garantir a qualidade e regulamentação dos serviços.

• Taxa de registro de medicamento: Relacionada a aprovações regulatórias e entrada no mercado.
• Taxa de análise laboratorial: Cobre custos de testes e controle de qualidade.

​

Agrícola

No setor agrícola, taxas estão ligadas a processos de comercialização e regulamentação.

• Taxa de inspeção sanitária: Garante conformidade sanitária para exportações agrícolas.
• Taxa de exportação agrícola: Cobre custos administrativos e regulatórios de exportação.

​

Pacotes de taxas

---

Um Pacote de Taxas define como as taxas são aplicadas a uma transação. Ele agrupa uma ou mais regras de taxas e pode ser personalizado por segmento, ledger e rotas contábeis. Você pode criar diferentes pacotes para diferentes produtos, tipos de transação ou segmentos de clientes, cada um com sua própria lógica de cálculo, configuração de rotas e regras de prioridade. Um pacote geralmente inclui:

• transactionRoute – A rota contábil principal para a transação.
• segmentId – O produto ou segmento ao qual o pacote se aplica.
• ledgerId – O ledger que registra a transação e suas taxas.
• waivedAccounts – Contas que devem ser isentas de taxas.
• fees – Um mapa de regras individuais de taxas, cada uma incluindo:
  • priority – Define a ordem de execução.
  • routeFrom e routeTo – Rotas contábeis personalizadas para a taxa.
  • isDeductibleFrom – Se a taxa é deduzida do valor original.
  • referenceAmount – O valor base usado para cálculos.

​

Regras de validação

Para garantir consistência e prevenir erros de configuração, o Fees Engine aplica as seguintes regras:

• A prioridade da taxa deve ser única dentro de um pacote.
• *Fees withisDeductibleFrom: true must use- referenceAmount: originalAmount.
• *Fees with priority 1 must also use- referenceAmount: originalAmount.
• Campos como organizationId, ledgerId e creditAccount devem existir no Midaz e são validados usando o endpoint Recuperar uma conta por alias.

​

Escolhendo o endpoint certo: calculate vs. simulate

O Fees Engine fornece dois endpoints para aplicar taxas. Eles se comportam de forma diferente, dependendo de quanto controle e flexibilidade você precisa:

​

Calcular taxas para um pacote

• Busca automaticamente todos os pacotes disponíveis para a organização e ledger informados.
• Escolhe a melhor correspondência com base no contexto da transação.
• Aplica as regras de taxas correspondentes.
• Se nenhum pacote correspondente for encontrado, nenhuma taxa é aplicada.

​

Simular taxas de transação

• Simula taxas para um pacote específico usando seu packageId.
• Retorna as taxas calculadas somente se a transação corresponder às condições do pacote.
• Útil para testes, depuração ou para dar aos usuários uma prévia das taxas, sem gravar no ledger.

​

Roteamento de taxas

---

Cada taxa pode ter:

• Um routeFrom, que representa a rota contábil para o débito (ou origem).
• Um routeTo, que representa a rota contábil para o crédito (ou destino).
• Um transactionRoute, que representa a natureza geral da transação.

Isso permite o rastreamento granular de cada entrada de taxa no ledger.

​

Taxas dedutíveis

---

Se uma taxa é marcada como dedutível (isDeductibleFrom: true), a seguinte lógica se aplica:

• O valor total é enviado a partir da conta de origem.
• A taxa é subtraída do valor recebido pela conta de destino.
• O referenceAmount usado nos cálculos deve ser originalAmount.

Essa abordagem garante que o remetente envia o valor total, e a dedução é aplicada apenas na ponta receptora.

​

Soft delete para manutenção segura de registros

---

Nenhum dado é perdido. Quando um recurso é excluído:

• Ele é marcado com um timestamp deletedAt.
• Ele é excluído das consultas padrão, mas ainda permanece armazenado no banco de dados para auditoria e precisão histórica.

Isso garante rastreabilidade total quando necessário.

​

Integrações

---

Você pode usar o Fees Engine por conta própria ou junto com outros componentes na sua stack. Ele se integra perfeitamente com plugins da Lerian ou com sua própria implementação para aplicar taxas com base na sua lógica de negócio. Casos de uso populares incluem:

• Motores de câmbio.
• Plataformas de crédito.
• Sistemas de pagamento de contas.
• Smart contracts.
• Pix (plataforma de pagamentos instantâneos do Brasil).

​

Recomendações de segurança

---

Segurança é fundamental ao trabalhar com produtos e plugins da Lerian.
Antes de fazer deploy de qualquer componente no seu ambiente, recomendamos fortemente que você revise nossas Recomendações de Segurança. Cada produto — junto com seus plugins associados — deve ser implementado seguindo as melhores práticas de segurança, incluindo:

• Proteger limites de rede
• Gerenciar e rotacionar secrets
• Aplicar gerenciamento de patches em tempo hábil
• Impor controles de acesso rigorosos baseados em função (RBAC)

Ao seguir essas práticas, você garante que os produtos e plugins da Lerian operem de forma segura, integrem-se perfeitamente à sua infraestrutura e mantenham conformidade, integridade de dados e confiança dos usuários em todo o seu ecossistema.

​

Próximos passos

---