Skip to main content
O Fees é um componente embarcado do processo unificado do ledger do Midaz. Ele oferece configuração e cálculo de tarifas e cobrança junto com o ledger. Faça o deploy e configure-o com o Midaz. Não é um serviço ou plugin separado.

​
Por que usar o Fees Engine?

O Fees Engine ajuda você a gerenciar lógicas de tarifação complexas. Ele aplica taxas fixas, distribui tarifas proporcionalmente e estima transações antes de você executá-las. Ele oferece:
  • Configuração flexível de tarifas via pacotes de tarifas, personalizados para grupos de contas ou ledgers específicos.
  • Múltiplos métodos de cálculo: tarifas fixas, taxas percentuais e lógica de “máximo entre tipos”.
  • Distribuição proporcional de tarifas para fluxos de marketplace e operações multiconta.
  • Suporte a rotas contábeis via transactionRoute, routeFrom e routeTo.
  • Ferramentas de estimativa para pré-visualizar cálculos antes de executar transações.
  • Lógica de isenção de tarifas por conta e faixas de valor da transação.
  • Aplicação baseada em prioridade para controlar a ordem de múltiplas tarifas.
  • Mecânica de dedução precisa com suporte a isDeductibleFrom.
  • Cobrança baseada em volume via pacotes de cobrança. Cobre com base na contagem acumulada de transações por período (diário ou mensal).
  • Cobrança de manutenção para cobranças recorrentes por conta, direcionadas a contas por segmento, portfólio ou lista explícita.
  • Cotas gratuitas e descontos progressivos para modelar precificação escalonada e incentivos de volume.
  • Isenções baseadas em segmento para isentar grupos inteiros de contas de pacotes de tarifas sem listar contas individuais.
O Fees Engine é um recurso licenciado do Midaz que roda dentro do processo unificado do ledger. Faça o deploy e configure-o com o Midaz. Se quiser saber mais ou avaliar para o seu caso de uso, fale com nossa equipe.

​
O que são tarifas?

Tarifas são valores monetários cobrados em troca de serviços, produtos ou acesso a recursos. O propósito varia conforme o setor. Veja alguns exemplos abaixo:

​
Financeiro

No setor financeiro, as tarifas cobrem custos operacionais e apoiam a conformidade legal.
  • Tarifa de manutenção de conta: mantém as contas operacionais e cobre custos administrativos.
  • Tarifa de transferência: aplica-se a transações como TEDs ou transferências internacionais.

​
Logística e transporte

No setor de logística, as tarifas cobrem serviços de transporte e armazenagem.
  • Tarifa de manuseio: aplica-se durante o armazenamento e a movimentação física de mercadorias.
  • Tarifa de descarga: cobre operações de descarga nos pontos de entrega.

​
Farmacêutico e saúde

No setor farmacêutico, as tarifas garantem a qualidade e a regulação dos serviços.
  • Tarifa de registro de medicamento: relacionada a aprovações regulatórias e entrada no mercado.
  • Tarifa de análise laboratorial: cobre custos de testes e controle de qualidade.

​
Agrícola

No setor agrícola, as tarifas cobrem processos de comercialização e regulatórios.
  • Tarifa de inspeção sanitária: garante a conformidade sanitária para exportações agrícolas.
  • Tarifa de exportação agrícola: cobre custos administrativos e regulatórios de exportação.

​
Escopo

O serviço unificado do Midaz expõe Fees e Billing apenas na superfície v2 com escopo de ledger. A URL é a única entrada de ledger: um parâmetro de query ledgerId não é aceito, e um corpo de requisição que envia ledgerId é rejeitado como campo desconhecido. Um pacote pertencente a outro ledger é retornado como não encontrado.

​
Pacotes de Tarifas

Um Pacote de Tarifas define como o mecanismo aplica tarifas a uma transação. Ele agrupa uma ou mais regras de tarifa. Você o personaliza por segmento, ledger e rotas contábeis. Você pode criar pacotes diferentes para produtos, tipos de transação ou segmentos de clientes diferentes. Cada pacote tem sua própria lógica de cálculo, configuração de rota e regras de prioridade. Um pacote inclui campos obrigatórios e pode adicionar campos opcionais de correspondência ou isenção:
  • Escopo de ledger – A URL v2 identifica o ledger que registra a transação e suas tarifas. Não envie ledgerId no corpo da requisição.
  • transactionRoute – A rota contábil principal da transação, para correspondência no nível de rota.
  • segmentId – O produto ou segmento ao qual o pacote se aplica, para correspondência no nível de segmento.
  • waivedAccounts – Contas a isentar de tarifas, quando você configura isenções.
  • fees – Um mapa de regras de tarifa individuais, cada uma incluindo:
    • priority – Define a ordem de execução.
    • routeFrom e routeTo – Rotas contábeis personalizadas para a tarifa.
    • isDeductibleFrom – Se o mecanismo deduz a tarifa do valor original.
    • referenceAmount – O valor base para os cálculos.
O Fees Engine exige configuração explícita de rota para cada tarifa e direção (por exemplo, débito ou crédito).

​
Regras de validação

O Fees Engine aplica as seguintes regras:
  • A prioridade da tarifa deve ser única dentro de um pacote.
  • Tarifas com isDeductibleFrom: true devem usar referenceAmount: originalAmount.
  • Tarifas com priority 1 também devem usar referenceAmount: originalAmount.
  • A organização e o ledger indicados pela URL devem existir no Midaz. Os aliases de conta configurados, como creditAccount, devem ser resolvidos nesse escopo. O Fees Engine os valida com o endpoint Retrieve an Account by Alias.
Garanta que sua configuração atenda aos padrões mais recentes do Midaz. O Fees Engine valida cada pacote e transação em relação a eles. Verifique a organização e o ledger na URL e as regras para creditAccount e referenceAmount, além de campos de correspondência opcionais como segmentId, quando você os configura.

​
Aplicação e estimativa de tarifas

O Midaz aplica tarifas no próprio processo ao criar uma transação. Não existe um endpoint público separado de cálculo de tarifas. O ledger avalia o pacote correspondente no fluxo da transação e aplica as regras dele quando há uma correspondência.

​
Estimate transaction fees

  • Estima tarifas para um pacote específico pelo respectivo packageId.
  • Retorna tarifas calculadas apenas se a transação corresponder às condições do pacote.
  • Útil para testes, depuração ou pré-visualização de tarifas, sem gravar no ledger.
A aplicação de tarifas 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

Os pacotes de tarifas oferecem suporte à isenção de contas individuais ao listar seus aliases em waivedAccounts. Para isentar um grupo inteiro de uma vez, adicione uma referência de segmento à mesma lista usando a forma segment:<segment-uuid>, por exemplo "segment:seg_premium_01HZ...".
O campo segmentId do próprio pacote não é uma isenção. Ele define qual pacote se aplica a uma transação (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 tarifa.
  • Contas internas ou de parceiros pertencem a um segmento existente no Midaz.
  • Manter uma lista de aliases de conta individuais é inviável em escala.
O Fees Engine resolve isenções baseadas em segmento no momento do cálculo. Quando contas entram ou saem do segmento, a mudança passa a valer no próximo cálculo. Você não precisa atualizar o pacote.

​
Pacotes de Cobrança

Os Pacotes de Cobrança calculam cobranças a partir do volume acumulado de transações em um período (diário ou mensal). Os pacotes de tarifas cobram por transação individual. Os pacotes de cobrança contam as transações que se qualificam e retornam payloads para o seu orquestrador executar. Há dois tipos disponíveis:
  • Volume: cobra com base no número de transações que correspondem a um filtro de evento no período.
  • Manutenção: cobra uma tarifa fixa recorrente por conta ativa, uma vez por período de cobrança.
Os pacotes de cobrança são um mecanismo de cálculo, não uma plataforma de cobrança. O mecanismo 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 as transações que correspondem a um determinado eventFilter (rota de transação + status) dentro do período de cobrança. Em seguida, ele aplica uma cobrança a partir do modelo de precificação configurado. Campos principais:
  • eventFilter: especifica quais transações contar, usando transactionRoute e status.
  • pricingModel: tiered (o preço unitário varia conforme a 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 mecanismo subtrai essa contagem antes de aplicar a precificação.
  • discountTiers: descontos progressivos. Quando o volume total atinge um limite, o mecanismo aplica o percentual de desconto configurado ao valor final.
  • countMode: aceita perRoute ou perAccount. O cálculo de volume conta todas as transações correspondentes na rota como um único total.
  • debitAccountAlias / creditAccountAlias: rotas contábeis para a cobrança.

​
Pacotes de manutenção

Um pacote de manutenção aplica uma tarifa fixa por conta ativa no período de cobrança, independentemente da atividade de transações. Campos principais:
  • feeAmount: cobrança fixa por conta ativa.
  • assetCode: moeda da cobrança.
  • maintenanceCreditAccount: conta que recebe a receita da tarifa.
  • accountTarget: define quais contas cobrar. Use exatamente um por pacote:
    • segmentId: todas as contas do segmento.
    • portfolioId: todas as contas do portfólio.
    • aliases: lista explícita de aliases de conta (máximo de 100 contas).
Cada pacote de manutenção oferece suporte a apenas um tipo de accountTarget. Você não pode combinar segmentId, portfolioId e aliases no mesmo pacote.

​
Gerenciando pacotes de cobrança

Os seguintes endpoints gerenciam pacotes de cobrança:
  • POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages: cria um pacote de cobrança.
  • GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages: lista todos os pacotes de cobrança.
  • GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{id}: recupera um pacote de cobrança específico.
  • PATCH /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{id}: atualiza um pacote de cobrança (label, description, enable).
  • DELETE /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{id}: exclui de forma reversível um pacote de cobrança.
  • POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate: calcula a cobrança de um período.

​
Pacotes de Tarifas vs. Pacotes de Cobrança

Pacotes de tarifas e pacotes de cobrança operam de forma independente. Uma transação pode acionar o cálculo de um pacote de tarifas e também contar para um pacote de cobrança no mesmo período. São eventos separados e não conflitantes.

​
Roteamento de tarifas

Toda tarifa pode ter:
  • Um routeFrom, que representa a rota contábil do débito (ou origem).
  • Um routeTo, que representa a rota contábil do crédito (ou destino).
  • Um transactionRoute, que representa a natureza geral da transação.
Isso permite o rastreamento granular de cada lançamento de tarifa no ledger.

​
Tarifas dedutíveis

Se você marcar uma tarifa como dedutível ( isDeductibleFrom: true), a seguinte lógica se aplica:
  • A conta de origem envia o valor total.
  • O mecanismo subtrai a tarifa do valor que a conta de destino recebe.
  • O referenceAmount para os cálculos deve ser originalAmount.

​
Exclusão reversível para registro seguro

O Fees Engine não perde dados. Quando você exclui um recurso:
  • O Fees Engine o marca com um timestamp deletedAt. Registros ativos retornam deletedAt: null.
  • Consultas padrão o excluem, mas o banco de dados continua armazenando-o para auditoria e histórico.

​
Integrações

Use o Fees Engine em um deploy do Midaz junto com outros componentes do seu stack. Você pode chamar os recursos dele a partir de plugins da Lerian ou da sua própria implementação para aplicar tarifas a partir da sua lógica de negócio. Casos de uso incluem:
  • Mecanismos de câmbio
  • Plataformas de empréstimo
  • Sistemas de pagamento de contas
  • Contratos inteligentes
  • Pix (a plataforma de pagamentos instantâneos do Brasil)

​
Recomendações de segurança

A segurança é fundamental ao trabalhar com produtos e plugins da Lerian.
Antes de fazer o deploy de qualquer componente, consulte nossas Recomendações de Segurança. Implemente cada produto e seus plugins de acordo com as boas práticas de segurança, como:
  • Proteger os limites de rede
  • Gerenciar e rotacionar segredos
  • Aplicar patches de segurança em tempo hábil
  • Aplicar controles de acesso rígidos baseados em papéis (RBAC)

​
Próximos passos

Explore a API do Fees Engine

Veja os endpoints para pacotes de tarifas, cálculos e estimativas.

Usando o Fees Engine

Aprenda a criar pacotes de tarifas e aplicá-los a transações.