Usando o Fees Engine

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

Não sabe qual usar? Os pacotes de tarifas aplicam cobranças no momento da transação. Os pacotes de faturamento calculam cobranças ao longo de um período (diário ou mensal) para o seu orquestrador executar. Você pode usar os dois simultaneamente.

Pacotes de tarifas: fluxo por transação

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

Passo 1 - Crie seus pacotes de tarifas

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

transactionRoute - Identifica a natureza da transação, quando você precisa de correspondência no nível da rota.
segmentId - Agrupa clientes ou tipos de produto, quando você precisa de correspondência no nível do segmento.
Escopo do ledger - A URL da requisição identifica qual ledger registra a transação; não envie ledgerId no corpo do pacote.
Valor mínimo e máximo - Limites opcionais para a aplicação da tarifa.
routeFrom / routeTo - Definem como cada tarifa se move pelos fluxos contábeis.

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

Listar Pacotes - Lista todos os pacotes criados.
Buscar um Pacote - Busca informações de um pacote específico.
Atualizar um Pacote - Atualiza as informações de um pacote específico.
Excluir um Pacote - Faz o soft delete de um pacote.

(opcional) Passo 2 - Execute uma estimativa

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

Quais regras de tarifa se aplicam.
Como o pacote vai 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. Informe a mesma organização e o mesmo ledger na URL da requisição, e inclua os campos de correspondência configurados, como transactionRoute ou segmentId, para que o mecanismo possa avaliar o pacote correto.

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

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

transactionRoute, quando configurado
segmentId, quando configurado
Escopo do ledger a partir da URL da requisição
Valor mínimo e máximo
waivedAccounts, quando configurado para isenções de tarifa

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

Passo 5 - Verifique as isenções

O sistema verifica:

Se o valor da transação está fora do intervalo permitido.
Se a conta de origem é isenta.

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

Passo 6 - Cálculo e aplicação da tarifa

Se um pacote se aplica, o Fees Engine:

Calcula os valores da tarifa com base no applicationRule selecionado.
Aplica as tarifas proporcionalmente entre as contas, se necessário.
Usa isDeductibleFrom para definir se adiciona ou deduz a tarifa.
Direciona as tarifas para o creditAccount correto com o routeFrom e o 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 tarifas, o componente Transactions assume. Ele processa:

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

O ledger armazena cada movimento para rastreabilidade e auditabilidade completas.

Passo 8 - Revise e confirme

Depois da execução, você pode:

Inspecionar a transação final e os valores por conta.
Confirmar qual pacote de tarifas foi aplicado.
Verificar todos os movimentos de tarifa por meio dos metadados e dos registros do ledger.

Por que estimar uma transação?

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

Você quer testar um pacote específico.
Você depura regras de tarifa ou limites.
Você quer validar isenções, intervalos de valor ou divisões proporcionais.
Você precisa de uma visualização antes de criar uma transação real.
Você constrói uma interface e quer mostrar tarifas estimadas.

O Fees Engine oferece o endpoint Estimar Tarifas de Transação para essa finalidade. Você informa um packageId, e o endpoint retorna o que aconteceria se esse pacote exato fosse aplicado.

O que você obtém com uma estimativa?

Uma estimativa completa das regras de tarifa.
Quais contas o mecanismo cobraria.
Como o mecanismo dividiria a tarifa.
Nenhum impacto no ledger.

Use estimativas quando você ainda não estiver pronto para confirmar a transação, ou quiser dar aos seus usuários uma visualização clara da tarifa.

Erros comuns

O Fees Engine valida cada requisição quanto à consistência e à lógica correta da tarifa. Abaixo estão os problemas mais frequentes que você pode ver ao criar pacotes ou processar transações.

Code	Title	Message
FEE-0002	Campos ausentes na requisição	Sua requisição está sem um ou mais campos obrigatórios. Consulte a documentação para garantir que todos os campos necessários estejam incluídos na sua requisição.
FEE-0012	Entidade não encontrada	Nenhuma entidade foi encontrada para o ID informado. Use o ID correto da entidade que você está tentando gerenciar.
FEE-0013	Prioridade de tarifa inválida	O campo de prioridade nas tarifas é inválido. O campo não pode ser repetido.
FEE-0015	minimumAmount maior que maximumAmount	O valor de minimumAmount é maior que maximumAmount.
FEE-0022	Falha ao calcular a tarifa	Erro ao calcular a tarifa de uma transação.
FEE-0024	originalAmount é obrigatório quando priority é um	Para Priority igual a um, referenceAmount deve ser ‘originalAmount’ para a tarifa.
FEE-0025	Falha ao aplicar a regra: flatFee ou percentual	O applicationRule flatFee ou percentual deve ter exatamente 1 cálculo para a tarifa.
FEE-0035	Sobreposição do intervalo de valor do pacote	O maximumAmount e o minimumAmount do novo pacote se sobrepõem ao intervalo de valor de um pacote existente.

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 faturamento: fluxo por período

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

Passo 1: Crie os pacotes de faturamento

Configure pacotes de faturamento que definem suas regras de cobrança periódica. Cada pacote é do tipo volume ou manutenção. Exemplo de pacote de volume, uma cobrança por Pix enviado com precificação em camadas:

POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages
Body:
{
  "label": "Pix Send Monthly Billing",
  "description": "Monthly volume billing for Pix transactions",
  "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, uma tarifa mensal por conta PF ativa:

POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages
Body:
{
  "label": "PF Account Maintenance",
  "description": "Monthly maintenance fee for active PF accounts",
  "type": "maintenance",
  "enable": true,
  "feeAmount": "9.90",
  "assetCode": "BRL",
  "maintenanceCreditAccount": "fees-maintenance-pf",
  "accountTarget": {
    "segmentId": "seg_pf_01HZ..."
  }
}

Passo 2: Acione o cálculo do faturamento

Chame POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate com o período de faturamento. A URL identifica o ledger. O mecanismo avalia todos os pacotes de faturamento ativos que correspondem aos critérios.

POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate

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

O campo period aceita três formatos: YYYY-MM (mensal), YYYY-Www (semanal, por exemplo, 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 os dois tipos em uma única chamada.

Passo 3: Receba os resultados do cálculo

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

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

Passo 4: Execute as cobranças

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

O mecanismo de faturamento calcula e retorna resultados. Ele não cria transações no Midaz. O seu orquestrador controla quando e como executa as cobranças.

Passo 5: Revise e concilie

Depois de executar as cobranças:

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

Gerenciando pacotes de faturamento

Use estes endpoints para gerenciar pacotes de faturamento existentes:

GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages: Lista todos os pacotes de faturamento.
GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{id}: Busca um pacote de faturamento específico.
PATCH /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{id}: Atualiza um pacote de faturamento (apenas label, description, enable).
DELETE /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{id}: Faz o soft delete de um pacote de faturamento.

Se algum pacote falhar durante o cálculo, a operação inteira falha e não retorna resultados parciais. O cálculo de faturamento segue uma política tudo ou nada. Corrija o pacote com falha e execute novamente.

Midaz Core

CRM

Fees

Usando o Fees Engine

Pacotes de tarifas: fluxo por transação

Passo 1 - Crie seus pacotes de tarifas

(opcional) Passo 2 - Execute uma estimativa

Passo 3 - Crie uma transação

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

Passo 5 - Verifique as isenções

Passo 6 - Cálculo e aplicação da tarifa

Passo 7 - Atualizações no ledger

Passo 8 - Revise e confirme

Por que estimar uma transação?

O que você obtém com uma estimativa?

Erros comuns

Pacotes de faturamento: fluxo por período

Passo 1: Crie os pacotes de faturamento

Passo 2: Acione o cálculo do faturamento

Passo 3: Receba os resultados do cálculo

Passo 4: Execute as cobranças

Passo 5: Revise e concilie

Gerenciando pacotes de faturamento

​Pacotes de tarifas: fluxo por transação

​Passo 1 - Crie seus pacotes de tarifas

​(opcional) Passo 2 - Execute uma estimativa

​Passo 3 - Crie uma transação

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

​Passo 5 - Verifique as isenções

​Passo 6 - Cálculo e aplicação da tarifa

​Passo 7 - Atualizações no ledger

​Passo 8 - Revise e confirme

​Por que estimar uma transação?

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

​Erros comuns

​Pacotes de faturamento: fluxo por período

​Passo 1: Crie os pacotes de faturamento

​Passo 2: Acione o cálculo do faturamento

​Passo 3: Receba os resultados do cálculo

​Passo 4: Execute as cobranças

​Passo 5: Revise e concilie

​Gerenciando pacotes de faturamento

Pacotes de tarifas: fluxo por transação

Passo 1 - Crie seus pacotes de tarifas

(opcional) Passo 2 - Execute uma estimativa

Passo 3 - Crie uma transação

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

Passo 5 - Verifique as isenções

Passo 6 - Cálculo e aplicação da tarifa

Passo 7 - Atualizações no ledger

Passo 8 - Revise e confirme

Por que estimar uma transação?

O que você obtém com uma estimativa?

Erros comuns

Pacotes de faturamento: fluxo por período

Passo 1: Crie os pacotes de faturamento

Passo 2: Acione o cálculo do faturamento

Passo 3: Receba os resultados do cálculo

Passo 4: Execute as cobranças

Passo 5: Revise e concilie

Gerenciando pacotes de faturamento