Valores numéricos (string)
Expresse todos os valores financeiros no Fees Engine como uma
string do tipo numeric. Isso garante alta precisão decimal para ativos como BRL ou BTC. Também evita erros de arredondamento durante cálculos, divisões ou isenções.
Exemplo:
Períodos de faturamento
Ao acionar um cálculo de faturamento, você especifica a janela de tempo pelo campo
period. O Fees Engine aceita três formatos:
O mecanismo usa o período para contar as transações qualificadas (para pacotes de volume) ou as contas ativas (para pacotes de manutenção) dentro dessa janela exata.
Escolha a granularidade que corresponde ao seu ciclo de faturamento. Um produto de cartão pré-pago faturado diariamente usaria
2026-03-15. Uma plataforma SaaS faturada mensalmente usaria 2026-03. Um marketplace que liquida semanalmente usaria 2026-W13.
Regras de cálculo de tarifa
Cada tarifa usa uma
applicationRule para definir como ela é calculada. Você pode escolher entre três tipos de regra:
Você pode combinar regras diferentes em um único pacote para atender ao seu caso de uso.
Outros campos importantes:
isDeductibleFrom: define se a tarifa é deduzida do remetente ou do destinatário.referenceAmount:originalAmountouafterFeesAmount.priority: define a ordem de aplicação. A prioridade 1 deve sempre usaroriginalAmount.
maxBetweenTypes
Aplica o que for maior: uma tarifa fixa ou uma tarifa percentual. Exemplo- Valor da tarifa fixa: R$ 5.
- Tarifa percentual: 2%.
- Valor de referência: R$ 1.000.
flatFee
Aplica um valor de tarifa fixo. O comportamento depende deisDeductibleFrom.
Exemplo
- Tarifa fixa: R$ 15.
- Valor de referência: R$ 115.
percentual
Aplica uma tarifa como percentual do valor de referência. Exemplo- Valor: 30%.
- Valor de referência: R$ 389,50.
Divisão de tarifas
Quando uma transação tem múltiplas contas de origem, o Fees Engine divide as tarifas proporcionalmente.
Exemplo
- Valor total: R$ 4.000,00
- Tarifa fixa: R$ 15,00
- Imposto: 4%
isDeductibleFrom: false
Participação %
Fórmula: (Valor da Conta ÷ Valor Total) × 100
Distribuição da tarifa fixa
Fórmula: fixed Fee × participation %
Imposto proporcional
Fórmula: account amount × tax %
Valor final por conta
Fórmula: principal + fee + tax
Validações
- Total das participações = 100%
- A divisão da tarifa corresponde à tarifa fixa
- Divisão do imposto = 4%
- Total enviado = R$ 4.175,00
Isenções de tarifa: regras e hierarquia
Por valor da transação
UseminimumAmount e maximumAmount para definir a faixa em que as tarifas se aplicam.
Por exemplo: se a faixa for R 301 não aciona tarifas.
Por conta
O sistema verificawaivedAccounts. Uma origem nessa lista é isenta de tarifas.
Exemplo combinado: isenções de tarifa e divisão proporcional de tarifas
Este pacote inclui contas com isenções de tarifa e exige a divisão proporcional das tarifas.
Cenário
Estamos processando uma transação de R$ 4.000, que inclui:- Uma tarifa fixa de R$ 16.
- Apenas algumas contas estão sujeitas à tarifa fixa
- Um imposto IOF de 6% a ser deduzido.
Divisão do lado da origem
O mecanismo aplica a tarifa fixa apenas a
@account3 e @account4.
Resultado após a Tarifa Administrativa (proporcional)
O valor total enviado aumenta para R$ 4.016.
Dedução de IOF (destinatário)
O mecanismo credita as tarifas nas contas definidas no
creditAccount de cada tarifa.Dízimas periódicas
Quando a divisão de uma tarifa gera uma dízima periódica (por exemplo, 0,3333…), o Fees Engine mantém cada trecho da tarifa com precisão total. Ele reconcilia o pequeno resto na tarifa 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 faturamento
Os pacotes de faturamento usam um modelo de cálculo diferente dos pacotes de tarifas. Em vez de avaliar transações individuais, eles agregam dados ao longo de um período de faturamento e retornam payloads de cobrança para o seu orquestrador executar. O faturamento aceita três formatos de período: mensal (
YYYY-MM), semanal (YYYY-Www, por exemplo, 2026-W13) e diário (YYYY-MM-DD).
Cálculo de faturamento por volume
O faturamento por volume conta as transações que correspondem a umeventFilter (rota de transação + status) dentro do período de faturamento, e então aplica a precificação com base no modelo configurado.
O cálculo segue esta ordem:
- Conta as transações qualificadas no período.
- Subtrai a
freeQuotada contagem total para obter a contagem faturável. - Aplica a precificação com base no
pricingModel(tieredoufixed). - Aplica um desconto de
discountTiers, avaliado sobre a contagem total (antes de subtrair a cota gratuita).
Precificação em camadas
A precificação em camadas é precificação por volume, não precificação graduada. O mecanismo encontra a única camada cuja faixa de quantidade contém a contagem faturável, e então cobra cada unidade faturável pelo preço unitário dessa camada. Ele não precifica cada unidade dentro da sua própria faixa. A faixa de uma camada é inclusiva nas duas pontas. Se você omitir o limite superior, a camada fica sem limite. O mecanismo busca uma camada apenas quando a contagem faturável é positiva. Se a contagem faturável for positiva e nenhuma camada a cobrir, o cálculo falha para esse pacote. Uma contagem faturável igual a zero pula a busca de camada e produz um valor zero, então suas camadas não precisam cobrir o zero. Exemplo: um pacote de faturamento para emissão de boleto com três camadas 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 camada 501–2.000, então todas as 1.750 unidades são precificadas a R$ 0,80: R$ 1.400,00 bruto
- O desconto se aplica sobre a contagem total de 1.800 (≥ 1.000 → 5%): −R$ 70,00
- Total líquido: R$ 1.330,00
Precificação fixa
Um único preço unitário se aplica a todas as transações faturáveis, independentemente do volume. O mecanismo ainda subtrai a cota gratuita antes do cálculo. A precificação fixa usa o preço unitário da primeira camada do pacote, então um pacote fixo ainda deve declarar pelo menos uma camada. 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
Camadas de desconto
No máximo uma camada de desconto se aplica: a que tem o maiorminQuantity que a contagem total atinge ou ultrapassa. O mecanismo aplica o percentual dela ao valor bruto. Os descontos são avaliados sobre a contagem total de transações, não sobre a contagem faturável.
Escopo da contagem
O cálculo de volume conta as transações por rota de transação em todo o ledger. A cota gratuita, as camadas e as camadas de desconto se aplicam a esse total no nível da rota. Para contar dois fluxos separadamente, crie um pacote por rota de transação.Cálculo de faturamento de manutenção
O faturamento de manutenção cobra um valor fixo por conta ativa no período de faturamento. O mecanismo 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 um lançamento de débito (
source.from) no valor configurado emfeeAmount. - A
maintenanceCreditAccountrecebe o total completo como um único lançamento de crédito (distribute.to).
active e exclui qualquer outro status. 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 lançamentos em
source.from, cada um debitado em R$ 9,90 - 1 lançamento em
distribute.tocreditado em R$ 118.800,00
Resultados com valor zero
Quando o valor líquido de um pacote é zero (por exemplo, quando a cota gratuita cobriu todas as transações), o mecanismo ainda retorna um resultado para esse pacote, mas com um payload de transação vazio ({}). Trate isso como “processado, nada a enviar”.
Um uso totalmente isento chega a esse resultado sem buscar camada. A cota gratuita leva a contagem faturável a zero, o mecanismo pula a correspondência de camada e o valor é zero. Um pacote cujas camadas começam em 1 está correto para esse caso.
Política de falha tudo ou nada
Se algum pacote de faturamento falhar durante uma chamada a/billing/calculate, a operação inteira falha. O mecanismo não retorna resultados parciais. A resposta indica qual pacote e recurso causou a falha, para você corrigir e executar novamente.
Metadados de auditoria
Cada resultado de cálculo de faturamento carrega metadados estruturados para rastreabilidade. Os resultados de volume incluem o tipo de faturamento, o id e o rótulo do pacote, o período, as contagens total e faturável de eventos, a cota gratuita usada, o modelo de precificação, os valores bruto e líquido, e o detalhe do desconto (percentual, valor eminQuantity) quando aplicável. Os resultados de manutenção incluem o tipo de faturamento, o id e o rótulo do pacote, o período, a contagem total de contas e o valor da tarifa por conta.