Valores numéricos (string)
Expresse todos os valores financeiros no Fees Engine como
string com o tipo numeric. Isso oferece manuseio decimal de alta precisão para ativos como BRL ou BTC. Também previne erros de arredondamento durante cálculos, divisões ou isenções.
Importante
- Requerido: Midaz v3.x.x (usa
numeric). - Incompatível: Midaz v2.x.x (formato
amount+scaledescontinuado).
Períodos de billing
Ao acionar um cálculo de billing, você especifica a janela de tempo através do campo
period. O Fees Engine suporta três formatos:
O motor usa o período para contar transações qualificadas (para pacotes de volume) ou contas ativas (para pacotes de manutenção) dentro dessa janela exata.
Escolha a granularidade que corresponde ao seu ciclo de billing. Um produto de cartão pré-pago cobrado diariamente usaria
2026-03-15. Uma plataforma SaaS cobrada mensalmente usaria 2026-03. Um marketplace que faz liquidação semanal usaria 2026-W13.
Regras de cálculo de taxas
Cada taxa usa uma
applicationRule para definir como é calculada. Você pode escolher entre três tipos de regra:
Você pode combinar diferentes regras em um único pacote para atender ao seu caso de uso.
Outros campos importantes:
isDeductibleFrom: define se a taxa é deduzida do remetente ou do destinatário.referenceAmount: pode seroriginalAmountouafterFeesAmount.priority: define a ordem de aplicação. A prioridade 1 deve sempre usaroriginalAmount.
maxBetweenTypes
Aplica o que for maior: uma taxa fixa ou uma taxa baseada em percentual. Exemplo- Valor da taxa fixa: R$5.
- Taxa percentual: 2%.
- Valor de referência: R$1.000.
flatFee
Aplica um valor fixo de taxa. O comportamento depende doisDeductibleFrom.
Exemplo
- Taxa fixa: R$15.
- Valor de referência: R$115.
percentual
Aplica uma taxa como percentual do valor de referência. Exemplo- Valor: 30%.
- Valor de referência: R$ 389,50.
Divisão de taxas
Quando uma transação tem múltiplas contas de origem, o Fees Engine divide as taxas proporcionalmente.
Exemplo
- Valor total: R$4.000,00
- Taxa fixa: R$15,00
- Imposto: 4%
isDeductibleFrom: false
Participação %
Fórmula: (Valor da Conta ÷ Valor Total) × 100
Distribuição da taxa fixa
Fórmula: taxa fixa × participação %
Imposto proporcional
Fórmula: valor da conta × % do imposto
Valor final por conta
Fórmula: principal + taxa + imposto
Validações
- Total das participações = 100%
- Divisão da taxa corresponde à taxa fixa
- Divisão do imposto = 4%
- Total enviado = R$ 4.175,00
Isenções de taxas: regras e hierarquia
Por valor da transação
UseminimumAmount e maximumAmount para definir quando as taxas devem ser aplicadas.
Por exemplo: Se a faixa é R$ 0–300, uma transação de R$ 301 não acionará taxas.
Por conta
O sistema verificawaivedAccounts. Uma origem nessa lista é isenta de taxas.
Exemplo misto: isenções de taxas e divisão proporcional de taxas
Vamos ver um exemplo de um pacote que inclui contas com isenções de taxas e requer divisão proporcional das taxas.
Cenário
Estamos processando uma transação de R$ 4.000, que inclui:- Uma taxa fixa de R$ 16.
- Apenas algumas contas estão sujeitas à taxa fixa.
- Um IOF de 6% a ser deduzido.
Divisão no lado da origem
O motor aplica a taxa fixa apenas a
@account3 e @account4.
Resultado após Taxa Administrativa (proporcional)
O valor total enviado aumenta para R$4.016.
Dedução de IOF (destinatário)
O motor credita as taxas nas contas definidas no
creditAccount de cada taxa.Dízimas periódicas
Quando uma divisão de taxa produz uma dízima periódica (por exemplo, 0,3333…), o Fees Engine mantém cada linha de taxa com precisão completa. Ele reconcilia o pequeno resto na taxa da conta com o maior valor. Isso mantém o total exato, evita desvios de arredondamento e mantém seu ledger consistente.
Cálculos de billing
Os pacotes de billing usam um modelo de cálculo diferente dos pacotes de taxas. Em vez de avaliar transações individuais, eles agregam dados ao longo de um período de billing e retornam payloads de cobrança para seu orquestrador executar. O billing suporta três formatos de período: mensal (
YYYY-MM), semanal (YYYY-Www, ex.: 2026-W13) e diário (YYYY-MM-DD).
Cálculo de billing por volume
O billing por volume conta transações que correspondem a umeventFilter (rota de transação + status) dentro do período de billing e então aplica preços com base no modelo configurado.
O cálculo segue esta ordem:
- Conta as transações qualificadas no período.
- Subtrai o
freeQuotado total contado para obter a contagem faturável. - Aplica preços com base no
pricingModel(tieredoufixed). - Aplica um desconto dos
discountTiers, avaliado contra a contagem total (antes de subtrair a cota gratuita).
Preço escalonado
O preço escalonado é preço por volume, não preço graduado. O motor encontra a única faixa cujo intervalo de quantidade contém a contagem faturável e então cobra cada unidade faturável pelo preço unitário dessa faixa. Ele não aplica o preço de cada intervalo às unidades que caem dentro dele. O intervalo de uma faixa é inclusivo nas duas pontas. Se você omitir o limite superior, a faixa fica sem teto. O motor busca uma faixa apenas quando a contagem faturável é positiva. Se a contagem faturável é positiva e nenhuma faixa a cobre, o cálculo falha para aquele pacote. Uma contagem faturável de zero dispensa a busca de faixa e produz um valor zero, então suas faixas não precisam cobrir o zero. Exemplo: Um pacote de billing para emissão de boletos com três faixas e uma cota gratuita de 50:
Para um cliente que emitiu 1.800 boletos no mês:
- 50 isentos (cota gratuita) → 1.750 faturáveis
- 1.750 cai na faixa 501–2.000, então todas as 1.750 unidades são cobradas a R$ 0,80: R$ 1.400,00 bruto
- A faixa de desconto é aplicada sobre a contagem total de 1.800 (≥ 1.000 → 5%): −R$ 70,00
- Total líquido: R$ 1.330,00
Preço fixo
Um único preço unitário se aplica a todas as transações faturáveis, independentemente do volume. O motor ainda subtrai a cota gratuita antes do cálculo. O preço fixo usa o preço unitário da primeira faixa do pacote, então um pacote fixo precisa declarar pelo menos uma faixa — caso contrário o cálculo falha. Exemplo: R$ 0,10 por Pix enviado, sem cota gratuita:- 5.000 transações Pix × R$ 0,10 = R$ 500,00
Faixas de desconto
No máximo uma faixa de desconto é aplicada: aquela com o maiorminQuantity que a contagem total atinge ou supera. Seu percentual incide sobre o valor bruto. Os descontos são avaliados contra a contagem total de transações, não contra a contagem faturável.
Escopo da contagem
O cálculo por volume conta transações por rota de transação em todo o ledger. A cota gratuita, as faixas e as faixas de desconto se aplicam a esse total por rota. Para contar dois fluxos separadamente, crie um pacote por rota de transação.Cálculo de billing de manutenção
O billing de manutenção cobra um valor fixo por conta ativa no período de billing. O motor resolve as contas-alvo, mantém apenas as ativas e gera um único payload de transação. O resultado é uma transação N:1:- Cada conta ativa aparece como uma entrada de débito (
source.from) pelo valor configurado emfeeAmount. - A
maintenanceCreditAccountrecebe o total completo como uma única entrada de crédito (distribute.to).
active são incluídas; qualquer outro status fica de fora. Se nenhuma conta for resolvida, o pacote retorna um payload vazio ({}) em vez de uma transação.
Exemplo: Manutenção mensal de R$ 9,90 para um segmento com 12.000 contas PF ativas:
- 12.000 entradas em
source.from, cada uma debitada em R$ 9,90 - 1 entrada em
distribute.tocreditada em R$ 118.800,00
Resultados com valor zero
Quando o valor líquido de um pacote resulta em zero — por exemplo, se a cota gratuita cobriu todas as transações — o motor ainda retorna um resultado para aquele pacote, mas com um payload de transação vazio ({}). Interprete isso como “processado, nada a enviar”.
O uso totalmente isento chega a esse resultado sem uma busca de faixa. A cota gratuita leva a contagem faturável a zero, o motor dispensa a correspondência de faixas e o valor é zero. Um pacote cujas faixas começam em 1 está correto para esse caso.
Política de falha tudo-ou-nada
Se qualquer pacote de billing falhar durante uma chamada/billing/calculate, toda a operação falha. O motor não retorna nenhum resultado parcial. A resposta inclui qual pacote e recurso causou a falha, para que você possa corrigir e re-executar.
Metadados de auditoria
Cada resultado de cálculo de billing carrega metadados estruturados para rastreabilidade. Resultados de volume incluem o tipo de billing, o id e o label do pacote, o período, as contagens de eventos totais e faturáveis, a cota gratuita utilizada, o modelo de preços, os valores bruto e líquido, e o detalhe do desconto (percentual, valor eminQuantity) quando algum foi aplicado. Resultados de manutenção incluem o tipo de billing, o id e o label do pacote, o período, a contagem total de contas e o valor da taxa por conta.