> ## 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.
# Usando o Fees Engine
> Use o Fees Engine para aplicar fee packages por transação e billing packages por período alinhados com suas regras de negócio.
Seja aplicando taxas por transação ou calculando cobranças periódicas de billing, o Fees Engine oferece controle total e flexibilidade. Este guia acompanha você por 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
***
Veja como o processo funciona, desde a configuração das taxas até a visualização dos resultados.
### Passo 1 - Crie seus pacotes de taxas
Comece configurando **pacotes de taxas** que definem como as taxas são aplicadas. Para isso, use o endpoint [Criar um Pacote](/pt/reference/midaz/plugins/fees-engine/create-package). 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 usando:
* **transactionRoute** – Identifica a natureza da transação, quando a correspondência por rota for necessária.
* **segmentId** – Agrupa clientes ou tipos de produto, quando a correspondência por segmento for necessária.
* **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](/pt/reference/midaz/plugins/fees-engine/list-packages) - Listar todos os pacotes criados.
* [Recuperar um Pacote](/pt/reference/midaz/plugins/fees-engine/retrieve-package) - Recuperar informações de um pacote específico.
* [Atualizar um Pacote](/pt/reference/midaz/plugins/fees-engine/update-package) - Atualizar as informações de um pacote específico.
* [Excluir um Pacote](/pt/reference/midaz/plugins/fees-engine/delete-package) - Fazer soft-delete de um pacote.
### (opcional) Passo 2 - Execute uma estimativa
Se você deseja visualizar como um pacote de taxas se comportaria antes de confirmar uma transação real, use o endpoint [Estimar Taxas de Transação](/pt/reference/midaz/plugins/fees-engine/simulate-fees).
Essa estimativa ajuda a validar:
* Quais regras de taxas serão acionadas.
* Como o pacote se comportará com os valores informados.
* Se alguma isenção se aplica.
### Passo 3 - Crie uma transação
Uma vez que os pacotes estejam configurados, acione a transação real usando o endpoint [criar uma transação](/pt/reference/midaz/create-a-transaction-using-json). 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 automaticamente envia uma chamada para o endpoint [Calcular Taxas para um Pacote](/pt/reference/midaz/plugins/fees-engine/calculate-fees) e 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
Apenas um pacote é selecionado 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 atendida, nenhuma taxa é aplicada e a transação prossegue normalmente.
### Passo 6 - Cálculo e aplicação de taxas
Se um pacote for aplicado, 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 a taxa é adicionada ou deduzida.
* Roteia as taxas para a `creditAccount` correta usando os `routeFrom` e `routeTo` configurados.
* Retorna o resultado completo da transação junto com o `packageAppliedID` nos metadados.
### Passo 7 - Atualizações no ledger
Após o cálculo das 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
Cada movimentação é armazenada no ledger 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 o pacote de taxas que foi aplicado.
* 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](/pt/reference/midaz/plugins/fees-engine/simulate-fees) para esse propósito. Você só precisa passar um `packageId` e o endpoint retorna o que aconteceria se **aquele pacote exato fosse aplicado**.
### O que você obtém com uma estimativa?
* Uma estimativa completa das regras de taxas.
* Quais contas seriam cobradas.
* Como a taxa seria dividida.
* 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](/pt/reference/midaz/plugins/fees-engine/fee-engine-error-list) na [Referência da API](/pt/reference/introduction).
## 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, o billing é acionado pelo chamador — seu orquestrador 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:
```json theme={null}
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": "perAccount",
"assetCode": "BRL",
"debitAccountAlias": "client-wallet",
"creditAccountAlias": "fees-revenue"
}
```
**Exemplo de pacote de manutenção** — taxa mensal por conta PF ativa:
```json theme={null}
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.
```json theme={null}
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 um contendo um `transactionPayload` pronto para ser enviado 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 as cobranças são executadas.
### 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.
O cálculo de billing segue uma política tudo-ou-nada. Se qualquer pacote falhar durante o cálculo, toda a operação falha e nenhum resultado parcial é retornado. Corrija o pacote com falha e re-execute.