Usando o Fees Engine

O Fees Engine aplica taxas por transação e calcula cobranças periódicas de billing. Este guia cobre ambos os fluxos de trabalho: pacotes de taxas (por transação) e pacotes de billing (por período).

Não sabe qual usar? Pacotes de taxas aplicam cobranças no momento da transação. Pacotes de billing calculam cobranças ao longo de um período (diário ou mensal) para seu orquestrador executar. Você pode usar ambos simultaneamente.

Pacotes de taxas: fluxo de trabalho por transação

Os pacotes de taxas aplicam cobranças de forma síncrona quando você cria uma transação. Esta seção mostra o processo, desde a configuração das taxas até os resultados.

Passo 1 - Crie seus pacotes de taxas

Primeiro, configure pacotes de taxas que definem como o motor aplica as taxas. Use o endpoint Criar um Pacote. Cada pacote contém um conjunto de regras de taxas e critérios de correspondência. Você pode personalizar pacotes para diferentes ledgers, segmentos e rotas de transação com estes campos:

transactionRoute – Identifica a natureza da transação, quando você precisa de correspondência por rota.
segmentId – Agrupa clientes ou tipos de produto, quando você precisa de correspondência por segmento.
ledgerId – Define qual ledger registra a transação.
Valor mínimo e máximo – Limites opcionais para aplicação de taxas.
routeFrom / routeTo – Definem como cada taxa se move nos fluxos contábeis.

Essa flexibilidade permite aplicar taxas distintas por cenário, desde configurações baseadas em conta até baseadas em valor. Gerenciando Pacotes Os seguintes endpoints também estão disponíveis para você gerenciar os pacotes:

Listar Pacotes - Listar todos os pacotes criados.
Recuperar um Pacote - Recuperar informações de um pacote específico.
Atualizar um Pacote - Atualizar as informações de um pacote específico.
Excluir um Pacote - Fazer soft-delete de um pacote.

(opcional) Passo 2 - Execute uma estimativa

Para visualizar como um pacote de taxas se comporta antes de você confirmar uma transação real, use o endpoint Estimar Taxas de Transação. Essa estimativa ajuda a validar:

Quais regras de taxas se aplicam.
Como o pacote se comportará com os valores informados.
Se alguma isenção se aplica.

Passo 3 - Crie uma transação

Depois de configurar os pacotes, crie a transação com o endpoint criar uma transação. Inclua o ledgerId e os campos de correspondência configurados, como transactionRoute ou segmentId, para que o motor avalie o pacote correto.

Passo 4 - O Fees Engine entra em ação

O Fees Engine é executado em processo quando o Midaz cria a transação. Ele avalia se um pacote se aplica, com base em:

transactionRoute, quando configurado
segmentId, quando configurado
ledgerId
Valor mínimo e máximo
waivedAccounts, quando configurado para isenções de taxas

O Fees Engine seleciona apenas um pacote por transação.

Passo 5 - Verificar isenções

O sistema verifica:

Se o valor da transação está fora da faixa permitida.
Se a conta de origem é isenta.

Se qualquer uma das condições for verdadeira, o Fees Engine não aplica taxas e a transação prossegue normalmente.

Passo 6 - Cálculo e aplicação de taxas

Se um pacote se aplica, o Fees Engine:

Calcula os valores das taxas com base na applicationRule selecionada.
Aplica taxas proporcionalmente entre contas, se necessário.
Usa isDeductibleFrom para definir se adiciona ou deduz a taxa.
Roteia as taxas para a creditAccount correta com os routeFrom e routeTo configurados.
Retorna o resultado completo da transação junto com o packageAppliedID nos metadados.

Passo 7 - Atualizações no ledger

Depois que o Fees Engine calcula as taxas, o componente de Transações assume. Ele processa:

Débitos das contas de origem
Créditos para os destinos das taxas
Detalhamento das taxas por rota e conta

O ledger armazena cada movimentação para rastreabilidade e auditabilidade completas.

Passo 8 - Revisar e confirmar

Após a execução, você pode:

Inspecionar a transação final e os valores por conta.
Confirmar qual pacote de taxas se aplicou.
Verificar todas as movimentações de taxas via metadados e registros do ledger.

Por que estimar uma transação?

Estimativas permitem visualizar como um pacote de taxas específico se comporta, sem executar uma transação real ou gravar no ledger. Use estimativas quando:

Você quiser testar um pacote específico.
Estiver depurando regras de taxas ou limites.
Quiser validar isenções, faixas de valor ou divisões proporcionais.
Precisar de uma prévia antes de criar uma transação real.
Estiver construindo uma interface e quiser mostrar taxas estimadas.

O Fees Engine fornece o endpoint Estimar Taxas de Transação para esse propósito. Você passa um packageId e o endpoint retorna o que aconteceria se ele aplicasse aquele pacote exato.

O que você obtém com uma estimativa?

Uma estimativa completa das regras de taxas.
Quais contas o motor cobraria.
Como o motor dividiria a taxa.
Sem impacto no ledger.

Use estimativas quando você não estiver pronto para confirmar a transação, ou quiser dar aos seus usuários uma prévia clara das taxas.

Erros comuns

O Fees Engine valida cada requisição para garantir consistência e lógica correta de taxas. Abaixo estão os problemas mais frequentes que você pode encontrar ao criar pacotes ou processar transações.

Código	Título	Mensagem
FEE-0002	Missing fields in request	Your request is missing one or more required fields. Please refer to the documentation to ensure all necessary fields are included in your request.
FEE-0012	Entity not found	No entity was found for the given ID. Please make sure to use the correct ID for the entity you are trying to manage.
FEE-0013	Invalid fee priority	The priority field in fees is invalid. Field can not be repeated.
FEE-0015	minimumAmount greater than maximumAmount	minimumAmount value is greater than maximumAmount.
FEE-0022	Failed to calculate fee	Error to make the calculation of a fee about a transaction.
FEE-0024	originalAmount is required when priority is one	For Priority equals to one, referenceAmount must be ‘originalAmount’ for fee.
FEE-0025	Failed to apply rule: flatFee or percentual	applicationRule flatFee or percentual must have exactly 1 calculation for Fee.
FEE-0035	Package amount range overlap	The maximumAmount and minimumAmount of the new package overlap with the amount range of an existing package.

Quer a lista completa de códigos de erro? Você encontra na página Lista de erros do Fees Engine na Referência da API.

Pacotes de billing: fluxo de trabalho por período

Os pacotes de billing calculam cobranças com base no volume acumulado de transações ou na manutenção por conta ao longo de um período de billing. Diferentemente dos pacotes de taxas, seu orquestrador aciona o billing. Ele decide quando calcular e executa as cobranças resultantes.

Passo 1 — Crie pacotes de billing

Configure pacotes de billing que definem suas regras de cobrança periódica. Cada pacote é do tipo volume ou manutenção. Exemplo de pacote de volume — cobrança por Pix enviado com preços escalonados:

POST /v1/billing-packages
Headers:
  X-Organization-Id: org_01HZ...

Body:
{
  "label": "Pix Send Monthly Billing",
  "description": "Monthly volume billing for Pix transactions",
  "ledgerId": "ldg_01HZ...",
  "type": "volume",
  "enable": true,
  "eventFilter": {
    "transactionRoute": "pix-send",
    "status": "APPROVED"
  },
  "pricingModel": "tiered",
  "tiers": [
    { "minQuantity": 1, "maxQuantity": 100, "unitPrice": "0.50" },
    { "minQuantity": 101, "maxQuantity": 500, "unitPrice": "0.35" },
    { "minQuantity": 501, "maxQuantity": null, "unitPrice": "0.20" }
  ],
  "freeQuota": 10,
  "discountTiers": [
    { "minQuantity": 200, "discountPercentage": "5.00" },
    { "minQuantity": 400, "discountPercentage": "10.00" }
  ],
  "countMode": "perRoute",
  "assetCode": "BRL",
  "debitAccountAlias": "client-wallet",
  "creditAccountAlias": "fees-revenue"
}

Exemplo de pacote de manutenção — taxa mensal por conta PF ativa:

POST /v1/billing-packages
Headers:
  X-Organization-Id: org_01HZ...

Body:
{
  "label": "PF Account Maintenance",
  "description": "Monthly maintenance fee for active PF accounts",
  "ledgerId": "ldg_01HZ...",
  "type": "maintenance",
  "enable": true,
  "feeAmount": "9.90",
  "assetCode": "BRL",
  "maintenanceCreditAccount": "fees-maintenance-pf",
  "accountTarget": {
    "segmentId": "seg_pf_01HZ..."
  }
}

Passo 2 — Acione o cálculo de billing

Chame POST /v1/billing/calculate com o ID do ledger e o período de billing. O motor avalia todos os pacotes de billing ativos que correspondem aos critérios.

POST /v1/billing/calculate

Body:
{
  "ledgerId": "ldg_01HZ...",
  "period": "2026-03",
  "type": "volume"
}

O campo period suporta três formatos: YYYY-MM (mensal), YYYY-Www (semanal, ex.: 2026-W13) e YYYY-MM-DD (diário). O campo type é opcional. Use "volume" ou "maintenance" para restringir o cálculo a um tipo. Omita-o para calcular ambos os tipos em uma única chamada.

Passo 3 — Receba os resultados do cálculo

O motor retorna um array de resultados. Cada resultado contém um transactionPayload pronto para enviar ao Midaz. Cada resultado inclui:

O pacote de billing que o gerou.
Os valores calculados com detalhamento completo (faixas aplicadas, descontos, cota gratuita subtraída).
Um payload de transação com source.from (entradas de débito) e distribute.to (entradas de crédito).
Metadados de auditoria estruturados para rastreabilidade.

Passo 4 — Execute as cobranças

Envie cada transactionPayload ao Midaz via POST /transactions/json para criar as transações de billing reais. Essa etapa é responsabilidade do seu orquestrador — Flowker, um cron job ou qualquer outro sistema.

O motor de billing calcula e retorna os resultados. Ele não cria transações no Midaz. Seu orquestrador controla quando e como executa as cobranças.

Passo 5 — Revise e concilie

Após executar as cobranças:

Verifique se as transações criadas no Midaz correspondem aos resultados do cálculo de billing.
Use os metadados de auditoria de cada resultado para conciliação.
O cálculo de billing é stateless — você pode re-executá-lo para o mesmo período para verificar os resultados.

Gerenciando pacotes de billing

Use estes endpoints para gerenciar pacotes de billing existentes:

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 (apenas label, description, enable).
DELETE /v1/billing-packages/:id — Soft-delete de um pacote de billing.

Se qualquer pacote falhar durante o cálculo, toda a operação falha e não retorna nenhum resultado parcial. O cálculo de billing segue uma política tudo-ou-nada. Corrija o pacote com falha e re-execute.

Midaz Core

CRM

Fees

Usando o Fees Engine

Pacotes de taxas: fluxo de trabalho por transação

Passo 1 - Crie seus pacotes de taxas

(opcional) Passo 2 - Execute uma estimativa

Passo 3 - Crie uma transação

Passo 4 - O Fees Engine entra em ação

Passo 5 - Verificar isenções

Passo 6 - Cálculo e aplicação de taxas

Passo 7 - Atualizações no ledger

Passo 8 - Revisar e confirmar

Por que estimar uma transação?

O que você obtém com uma estimativa?

Erros comuns

Pacotes de billing: fluxo de trabalho por período

Passo 1 — Crie pacotes de billing

Passo 2 — Acione o cálculo de billing

Passo 3 — Receba os resultados do cálculo

Passo 4 — Execute as cobranças

Passo 5 — Revise e concilie

Gerenciando pacotes de billing

​Pacotes de taxas: fluxo de trabalho por transação

​Passo 1 - Crie seus pacotes de taxas

​(opcional) Passo 2 - Execute uma estimativa

​Passo 3 - Crie uma transação

​Passo 4 - O Fees Engine entra em ação

​Passo 5 - Verificar isenções

​Passo 6 - Cálculo e aplicação de taxas

​Passo 7 - Atualizações no ledger

​Passo 8 - Revisar e confirmar

​Por que estimar uma transação?

​O que você obtém com uma estimativa?

​Erros comuns

​Pacotes de billing: fluxo de trabalho por período

​Passo 1 — Crie pacotes de billing

​Passo 2 — Acione o cálculo de billing

​Passo 3 — Receba os resultados do cálculo

​Passo 4 — Execute as cobranças

​Passo 5 — Revise e concilie

​Gerenciando pacotes de billing

Pacotes de taxas: fluxo de trabalho por transação

Passo 1 - Crie seus pacotes de taxas

(opcional) Passo 2 - Execute uma estimativa

Passo 3 - Crie uma transação

Passo 4 - O Fees Engine entra em ação

Passo 5 - Verificar isenções

Passo 6 - Cálculo e aplicação de taxas

Passo 7 - Atualizações no ledger

Passo 8 - Revisar e confirmar

Por que estimar uma transação?

O que você obtém com uma estimativa?

Erros comuns

Pacotes de billing: fluxo de trabalho por período

Passo 1 — Crie pacotes de billing

Passo 2 — Acione o cálculo de billing

Passo 3 — Receba os resultados do cálculo

Passo 4 — Execute as cobranças

Passo 5 — Revise e concilie

Gerenciando pacotes de billing