Documentation Index
Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
Use this file to discover all available pages before exploring further.
Valores numéricos (string)
Todos os valores financeiros no Fees Engine devem ser expressos como
string, usando o tipo numeric. Isso garante o manuseio decimal de alta precisão para ativos como BRL ou BTC, e 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:
| Formato | Exemplo | Janela |
|---|---|---|
| Diário | 2026-03-15 | Início do dia → início do dia seguinte (UTC) |
| Semanal | 2026-W13 | Segunda-feira 00:00 UTC da semana ISO → segunda-feira seguinte 00:00 UTC |
| Mensal | 2026-03 | Primeiro instante do mês → primeiro instante do mês seguinte (UTC) |
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.
isDeductibleFrom | Fórmula | Taxa Total |
|---|---|---|
false | referenceAmount + fee | R$ 130,00 |
true | referenceAmount - fee | R$ 100,00 |
percentual
Aplica uma taxa como percentual do valor de referência. Exemplo- Valor: 30%.
- Valor de referência: R$ 389,50.
isDeductibleFrom | Fórmula | Taxa Total |
|---|---|---|
false | referenceAmount * value | R$ 116,85 |
true | referenceAmount - (referenceAmount * value) | R$ 272,65 |
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
| Conta | Participação | Valor |
|---|---|---|
| @account1 | 25% | R$ 1.000 |
| @account2 | 25% | R$ 1.000 |
| @account3 | 40% | R$ 1.600 |
| @account4 | 10% | R$ 400 |
Distribuição da taxa fixa
Fórmula: taxa fixa × participação %
| Conta | Parcela da Taxa | Total |
|---|---|---|
| @account1 | R$ 3,75 | R$ 1.003,75 |
| @account2 | R$ 3,75 | R$ 1.003,75 |
| @account3 | R$ 6,00 | R$ 1.606,00 |
| @account4 | R$ 1,50 | R$ 401,50 |
Imposto proporcional
Fórmula: valor da conta × % do imposto
| Conta | Imposto | Total c/ Imposto |
|---|---|---|
| @account1 | R$ 40,00 | R$ 1.040,00 |
| @account2 | R$ 40,00 | R$ 1.040,00 |
| @account3 | R$ 64,00 | R$ 1.664,00 |
| @account4 | R$ 16,00 | R$ 416,00 |
Valor final por conta
Fórmula: principal + taxa + imposto
| Conta | Taxa | Imposto | Total Final |
|---|---|---|---|
| @account1 | R$ 3,75 | R$ 40,00 | R$ 1.043,75 |
| @account2 | R$ 3,75 | R$ 40,00 | R$ 1.043,75 |
| @account3 | R$ 6,00 | R$ 64,00 | R$ 1.670,00 |
| @account4 | R$ 1,50 | R$ 16,00 | R$ 417,50 |
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. Se a origem está listada, ela é 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
| Conta de Origem | % | Valor Proporcional |
|---|---|---|
| @account1 | 15% | R$ 600 |
| @account2 | 35% | R$ 1.400 |
| @account3 | 40% | R$ 1.600 |
| @account4 | 10% | R$ 400 |
@account3 e @account4.
Resultado após Taxa Administrativa (proporcional)
| Conta | Taxa Admin | Total |
|---|---|---|
| @account1 | Isenta | R$ 600 |
| @account2 | Isenta | R$ 1.400 |
| @account3 | R$ 12,80 | R$ 1.612,80 |
| @account4 | R$ 3,20 | R$ 403,20 |
Dedução de IOF (destinatário)
| Destinatário | % | Bruto | IOF (6%) | Líquido |
|---|---|---|---|---|
| @donation1 | 25% | R$ 1.000 | R$ 60 | R$ 940 |
| @donation2 | 25% | R$ 1.000 | R$ 60 | R$ 940 |
| @donation3 | 25% | R$ 1.000 | R$ 60 | R$ 940 |
| @donation4 | 25% | R$ 1.000 | R$ 60 | R$ 940 |
As taxas são creditadas nas contas definidas no
creditAccount de cada taxa.Dízimas periódicas
Quando uma divisão de taxa resulta em dízimas periódicas (ex.: 0,3333…), o Fees Engine ajusta automaticamente o primeiro ou maior valor em um centavo para garantir que o total permaneça exato. Isso 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. - Aplica preços com base no
pricingModel(tieredoufixed). - Aplica descontos dos
discountTiersse o volume total atingir algum limite.
Preço escalonado
Cada faixa define um intervalo de quantidade e um preço unitário. O motor aplica o preço correspondente para cada unidade dentro de cada intervalo. Exemplo: Um pacote de billing para emissão de boletos com três faixas e uma cota gratuita de 50:| Faixa | Preço unitário |
|---|---|
| 1–500 | R$ 1,20 |
| 501–2.000 | R$ 0,80 |
| 2.001+ | R$ 0,45 |
- 50 isentos (cota gratuita)
- 1.750 faturáveis: 500 × R$ 1,20 + 1.250 × R$ 0,80 = R$ 1.600,00
- Faixa de desconto aplicada (> 1.000 boletos → 5%): −R$ 80,00
- Total: R$ 1.520,00
Preço fixo
Um único preço unitário se aplica a todas as transações faturáveis, independentemente do volume. A cota gratuita ainda é subtraída antes do cálculo. Exemplo: R$ 0,10 por Pix enviado, sem cota gratuita:- 5.000 transações Pix × R$ 0,10 = R$ 500,00
Modos de contagem
O campocountMode determina como as transações são agrupadas:
perRoute— Conta todas as transações correspondentes na organização como um total único.perAccount— Conta transações por conta individual e aplica os preços independentemente para cada uma.
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, filtra pelo status ativo 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).
- 12.000 entradas em
source.from, cada uma debitada em R$ 9,90 - 1 entrada em
distribute.tocreditada em R$ 118.800,00
Política de falha tudo-ou-nada
Se qualquer pacote de billing falhar durante uma chamada/billing/calculate, toda a operação falha. Nenhum resultado parcial é retornado. A resposta inclui qual pacote e recurso causou a falha, para que você possa corrigir e re-executar.