Skip to main content
O Fees Engine é um componente integrado ao processo unificado do ledger do Midaz. Ele fornece configuração e cálculos de taxas e billing junto ao ledger. Faça o deploy e a configuração com o Midaz; ele não é um serviço ou plugin separado.

​
Por que usar o Fees Engine?

O Fees Engine ajuda você a gerenciar lógicas complexas de taxas. Ele aplica taxas fixas, distribui taxas proporcionalmente e estima transações antes de você executá-las. 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 de múltiplas taxas.
  • 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 Fees Engine é uma capacidade licenciada do Midaz executada dentro do processo unificado do ledger. Faça o deploy e a configuração com o Midaz. Se você deseja saber mais ou avaliá-lo para o seu caso de uso, entre em contato com nossa equipe.

​
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 cobrem custos operacionais e apoiam a conformidade legal.
  • Taxa de manutenção de conta: Mantém as contas operacionais e cobre custos administrativos.
  • Taxa de transferência: Aplica-se a transações como TEDs ou transferências internacionais.

​
Logística e transporte

No setor de logística, taxas cobrem serviços de transporte e armazenamento.
  • Taxa de manuseio: Aplica-se 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 garantem 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 cobrem 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.

​
Escopo

Fees e Billing suportam em paralelo o escopo de organização e o escopo de ledger. Na superfície v2 com escopo de ledger, o ledger indicado pela requisição é autoritativo: um parâmetro de consulta ledgerId não é aceito, e um ledgerId no corpo deve corresponder ao ledger da requisição. Um pacote de outro ledger é retornado como não encontrado.

​
Pacotes de taxas

Um Pacote de Taxas define como o motor aplica taxas a uma transação. Ele agrupa uma ou mais regras de taxas. Você o personaliza por segmento, ledger e rotas contábeis. Você pode criar diferentes pacotes para diferentes produtos, tipos de transação ou segmentos de clientes. Cada pacote tem sua própria lógica de cálculo, configuração de rotas e regras de prioridade. Um pacote inclui campos obrigatórios e pode adicionar campos opcionais de correspondência ou isenção:
  • ledgerId – O ledger que registra a transação e suas taxas.
  • transactionRoute – A rota contábil principal para a transação, para correspondência por rota.
  • segmentId – O produto ou segmento ao qual o pacote se aplica, para correspondência por segmento.
  • waivedAccounts – Contas a isentar de taxas, quando você configura isenções.
  • 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 o motor deduz a taxa do valor original.
    • referenceAmount – O valor base para cálculos.
O Fees Engine requer configuração explícita de rotas para cada taxa e direção (ex.: débito ou crédito).

​
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. O Fees Engine os valida com o endpoint Recuperar uma conta por alias.
Certifique-se de que sua configuração atenda aos padrões mais recentes do Midaz. O Fees Engine valida cada pacote e transação contra eles. Verifique as regras para ledgerId, creditAccount e referenceAmount, além de campos opcionais de correspondência como segmentId quando você os configura.

​
Aplicação e estimativa de taxas

As taxas são aplicadas em processo quando o Midaz cria uma transação; não há um endpoint público separado para calcular taxas. O ledger avalia o pacote correspondente no fluxo da transação e aplica suas regras quando encontra um.

​
Estimar taxas de transação

  • Estima taxas para um pacote específico por seu packageId.
  • Retorna as taxas calculadas somente se a transação corresponder às condições do pacote.
  • Útil para testes, depuração ou uma prévia das taxas, sem gravar no ledger.
A aplicação de taxas acontece durante a criação da transação. Use estimate quando quiser testar um pacote específico sem gravar no ledger.

​
Isenções baseadas em segmento

Pacotes de taxas suportam a isenção de contas individuais listando seus aliases em waivedAccounts. Para isentar um grupo inteiro de uma vez, adicione uma referência de segmento a essa mesma lista no formato segment:<segment-uuid> — por exemplo "segment:seg_premium_01HZ...".
O campo segmentId do próprio pacote não é uma isenção. Ele define a quais transações o pacote se aplica (correspondência de pacote no nível de segmento). As isenções sempre ficam em waivedAccounts.
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.
O Fees Engine resolve as isenções baseadas em segmento no momento do cálculo. Quando contas entram ou saem do segmento, a mudança entra em vigor no próximo cálculo. Você não atualiza o pacote.

​
Pacotes de billing

Pacotes de Billing calculam cobranças a partir do volume acumulado de transações ao longo de um período — diário ou mensal. Os pacotes de taxas cobram por transação individual. Os pacotes de billing contam as transações qualificadas e retornam payloads para o 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.
Os pacotes de billing são um motor de cálculo, não uma plataforma de billing. O motor calcula as cobranças e retorna os payloads. Seu orquestrador — Flowker, um cron job ou qualquer outro chamador — executa as cobranças reais no Midaz.

​
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. Em seguida, aplica uma cobrança a partir do 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 — Aceita perRoute ou perAccount. O cálculo por volume conta todas as transações correspondentes da rota como um total único.
  • 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.
    • portfolioId — Todas as contas no portfólio.
    • aliases — Lista explícita de aliases de contas (máximo 100 contas).
Cada pacote de manutenção suporta apenas um tipo de accountTarget. Você não pode combinar segmentId, portfolioId e aliases no mesmo pacote.

​
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

Pacotes de taxas e pacotes de billing operam de forma independente. Uma transação pode acionar um cálculo de pacote de taxas e também contar em um pacote de billing no mesmo período. Esses são eventos separados e não conflitantes.

​
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 você marca uma taxa como dedutível (isDeductibleFrom: true), a seguinte lógica se aplica:
  • A conta de origem envia o valor total.
  • O motor subtrai a taxa do valor que a conta de destino recebe.
  • O referenceAmount para os cálculos deve ser originalAmount.
Dessa forma, o remetente envia o valor total, e a conta de destino absorve a dedução.

​
Soft delete para manutenção segura de registros

O Fees Engine não perde nenhum dado. Quando você exclui um recurso:
  • O Fees Engine o marca com um timestamp deletedAt. Registros ativos retornam deletedAt: null.
  • As consultas padrão o excluem, mas o banco de dados ainda o armazena para auditoria e histórico.
Isso mantém a rastreabilidade total quando você precisa.

​
Integrações

Use o Fees Engine em uma implantação do Midaz junto com outros componentes da sua stack. Você pode invocar suas capacidades a partir de plugins da Lerian ou da sua própria implementação para aplicar taxas conforme 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 quando você trabalha com produtos e plugins da Lerian.
Antes de fazer deploy de qualquer componente, revise nossas Recomendações de Segurança. Implemente cada produto e seus plugins seguindo as melhores práticas de segurança, tais como:
  • 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)
Essas práticas mantêm os produtos e plugins da Lerian seguros e em conformidade em toda a sua stack.

​
Próximos passos

Explorar a API do Fees Engine

Consulte endpoints para pacotes de taxas, cálculos e estimativas.

Usando o Fees Engine

Aprenda a criar pacotes de taxas e pacotes de billing e aplicá-los às suas operações.