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 estimando 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 estimativa 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.
• Billing baseado em volume via pacotes de billing — cobrança baseada em contagens acumuladas de transações por período (diário ou mensal).
• Billing de manutenção para cobranças recorrentes por conta, direcionando contas por segmento, portfólio ou lista explícita.
• Cotas gratuitas e descontos progressivos para modelar preços escalonados e incentivos por volume.
• Isenções baseadas em segmento para isentar grupos inteiros de contas de pacotes de taxas sem listar contas individualmente.

​

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.
• Taxas com isDeductibleFrom: true devem usar referenceAmount: originalAmount.
• Taxas com priority 1 também devem usar 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. estimate

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.

​

Estimar taxas de transação

• Estima 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.

​

Isenções baseadas em segmento

Pacotes de taxas suportam a isenção de contas individuais via waivedAccounts. Você também pode referenciar um segmentId para isentar um grupo inteiro de contas de uma vez. Use isenções baseadas em segmento quando:

• Um nível de cliente (como contas premium) é universalmente isento de uma taxa.
• Contas internas ou de parceiros pertencem a um segmento existente no Midaz.
• Manter uma lista de aliases de contas individuais é impraticável em escala.

​

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.

​

Pacotes de billing

---

Pacotes de Billing calculam cobranças com base no volume acumulado de transações ao longo de um período — diário ou mensal. Diferentemente dos pacotes de taxas, que aplicam uma cobrança por transação individual, os pacotes de billing avaliam a contagem total de transações qualificadas e retornam payloads para seu orquestrador executar. Dois tipos estão disponíveis:

• Volume — cobranças baseadas no número de transações que correspondem a um filtro de evento no período.
• Manutenção — cobra uma taxa fixa recorrente por conta ativa, uma vez por período de billing.

​

Pacotes de volume

Um pacote de volume conta transações que correspondem a um dado eventFilter (rota de transação + status) dentro do período de billing e aplica uma cobrança com base no modelo de preços configurado. Campos principais:

• eventFilter — Especifica quais transações contar: transactionRoute e status.
• pricingModel — tiered (preço unitário varia por faixa de quantidade) ou fixed (preço unitário único independente do volume).
• tiers — Faixas de quantidade (minQuantity, maxQuantity) e unitPrice por unidade dentro de cada faixa.
• freeQuota — Número de transações isentas por período. O motor subtrai essa contagem antes de aplicar os preços.
• discountTiers — Descontos progressivos: quando o volume total atinge um limite, o motor aplica o percentual de desconto configurado ao valor final.
• countMode — perRoute (conta todas as transações correspondentes como um total único) ou perAccount (conta por conta individual).
• debitAccountAlias / creditAccountAlias — Rotas contábeis para a cobrança.

​

Pacotes de manutenção

Um pacote de manutenção aplica uma taxa fixa por conta ativa no período de billing, independentemente da atividade transacional. Campos principais:

• feeAmount — Cobrança fixa por conta ativa.
• assetCode — Moeda da cobrança.
• maintenanceCreditAccount — Conta que recebe a receita da taxa.
• accountTarget — Define quais contas cobrar. Use exatamente um por pacote:
  • segmentId — Todas as contas no segmento (suporta 100k+ contas).
  • portfolioId — Todas as contas no portfólio (suporta milhares de contas).
  • aliases — Lista explícita de aliases de contas (máximo 100 contas).

​

Gerenciando pacotes de billing

Os seguintes endpoints gerenciam pacotes de billing:

• POST /v1/billing-packages — Criar um pacote de billing.
• GET /v1/billing-packages — Listar todos os pacotes de billing.
• GET /v1/billing-packages/:id — Recuperar um pacote de billing específico.
• PATCH /v1/billing-packages/:id — Atualizar um pacote de billing (label, description, enable).
• DELETE /v1/billing-packages/:id — Soft-delete de um pacote de billing.
• POST /v1/billing/calculate — Calcular billing para um período.

​

Pacotes de taxas vs. Pacotes de billing

---

​

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

---