> ## 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.

# O que é o Fees Engine?

> O Fees Engine controla como as tarifas e a cobrança são configuradas, calculadas e rastreadas em cenários por transação e por período.

O Fees é um componente embarcado do processo unificado do ledger do Midaz. Ele oferece configuração e cálculo de tarifas e cobrança junto com o ledger. Faça o deploy e configure-o com o Midaz. Não é um serviço ou plugin separado.

## Por que usar o Fees Engine?

***

O **Fees Engine** ajuda você a gerenciar lógicas de tarifação complexas. Ele aplica taxas fixas, distribui tarifas proporcionalmente e estima transações antes de você executá-las.

Ele oferece:

* **Configuração flexível de tarifas** via pacotes de tarifas, personalizados para grupos de contas ou ledgers específicos.
* **Múltiplos métodos de cálculo**: tarifas fixas, taxas percentuais e lógica de "máximo entre tipos".
* **Distribuição proporcional de tarifas** para fluxos de marketplace e operações multiconta.
* **Suporte a rotas contábeis** via `transactionRoute`, `routeFrom` e `routeTo`.
* **Ferramentas de estimativa** para pré-visualizar cálculos antes de executar transações.
* **Lógica de isenção de tarifas** por conta e faixas de valor da transação.
* **Aplicação baseada em prioridade** para controlar a ordem de múltiplas tarifas.
* **Mecânica de dedução precisa** com suporte a `isDeductibleFrom`.
* **Cobrança baseada em volume** via pacotes de cobrança. Cobre com base na contagem acumulada de transações por período (diário ou mensal).
* **Cobrança de manutenção** para cobranças recorrentes por conta, direcionadas a contas por segmento, portfólio ou lista explícita.
* **Cotas gratuitas e descontos progressivos** para modelar precificação escalonada e incentivos de volume.
* **Isenções baseadas em segmento** para isentar grupos inteiros de contas de pacotes de tarifas sem listar contas individuais.

<Tip>
  O Fees Engine é um recurso licenciado do Midaz que roda dentro do processo unificado do ledger. Faça o deploy e configure-o com o Midaz. Se quiser saber mais ou avaliar para o seu caso de uso, [fale com nossa equipe](https://lerian.studio/contact).
</Tip>

## O que são tarifas?

***

Tarifas são valores monetários cobrados em troca de serviços, produtos ou acesso a recursos. O propósito varia conforme o setor. Veja alguns exemplos abaixo:

### Financeiro

No setor financeiro, as tarifas cobrem custos operacionais e apoiam a conformidade legal.

* **Tarifa de manutenção de conta**: mantém as contas operacionais e cobre custos administrativos.
* **Tarifa de transferência:** aplica-se a transações como TEDs ou transferências internacionais.

### Logística e transporte

No setor de logística, as tarifas cobrem serviços de transporte e armazenagem.

* **Tarifa de manuseio**: aplica-se durante o armazenamento e a movimentação física de mercadorias.
* **Tarifa de descarga**: cobre operações de descarga nos pontos de entrega.

### Farmacêutico e saúde

No setor farmacêutico, as tarifas garantem a qualidade e a regulação dos serviços.

* **Tarifa de registro de medicamento**: relacionada a aprovações regulatórias e entrada no mercado.
* **Tarifa de análise laboratorial**: cobre custos de testes e controle de qualidade.

### Agrícola

No setor agrícola, as tarifas cobrem processos de comercialização e regulatórios.

* **Tarifa de inspeção sanitária**: garante a conformidade sanitária para exportações agrícolas.
* **Tarifa de exportação agrícola**: cobre custos administrativos e regulatórios de exportação.

## Escopo

***

O serviço unificado do Midaz expõe Fees e Billing apenas na superfície v2 com escopo de ledger. A URL é a única entrada de ledger: um parâmetro de query `ledgerId` não é aceito, e um corpo de requisição que envia `ledgerId` é rejeitado como campo desconhecido. Um pacote pertencente a outro ledger é retornado como não encontrado.

## Pacotes de Tarifas

***

Um **Pacote de Tarifas** define como o mecanismo aplica tarifas a uma transação. Ele agrupa uma ou mais regras de tarifa. Você o personaliza por segmento, ledger e rotas contábeis.

Você pode criar pacotes diferentes para produtos, tipos de transação ou segmentos de clientes diferentes. Cada pacote tem sua própria lógica de cálculo, configuração de rota e regras de prioridade.

Um pacote inclui campos obrigatórios e pode adicionar campos opcionais de correspondência ou isenção:

* **Escopo de ledger** – A URL v2 identifica o ledger que registra a transação e suas tarifas. Não envie `ledgerId` no corpo da requisição.
* **transactionRoute** – A rota contábil principal da transação, para correspondência no nível de rota.
* **segmentId** – O produto ou segmento ao qual o pacote se aplica, para correspondência no nível de segmento.
* **waivedAccounts** – Contas a isentar de tarifas, quando você configura isenções.
* **fees** – Um mapa de regras de tarifa individuais, cada uma incluindo:
  * **priority** – Define a ordem de execução.
  * **routeFrom** e **routeTo** – Rotas contábeis personalizadas para a tarifa.
  * **isDeductibleFrom** – Se o mecanismo deduz a tarifa do valor original.
  * **referenceAmount** – O valor base para os cálculos.

<Note>
  O **Fees Engine** exige configuração explícita de rota para cada tarifa e direção (por exemplo, débito ou crédito).
</Note>

### Regras de validação

O Fees Engine aplica as seguintes regras:

* **A prioridade da tarifa deve ser única** dentro de um pacote.
* Tarifas com `isDeductibleFrom: true` devem usar `referenceAmount: originalAmount`.
* Tarifas com `priority` 1 também devem usar `referenceAmount: originalAmount`.
* A organização e o ledger indicados pela URL devem existir no Midaz. Os aliases de conta configurados, como `creditAccount`, devem ser resolvidos nesse escopo. O Fees Engine os valida com o endpoint [Retrieve an Account by Alias](/pt/reference/products/midaz/v2/get-account-by-alias).

<Danger>
  Garanta que sua configuração atenda aos padrões mais recentes do Midaz. O Fees Engine valida cada pacote e transação em relação a eles. Verifique a organização e o ledger na URL e as regras para `creditAccount` e `referenceAmount`, além de campos de correspondência opcionais como `segmentId`, quando você os configura.
</Danger>

### Aplicação e estimativa de tarifas

O Midaz aplica tarifas no próprio processo ao criar uma transação. Não existe um endpoint público separado de cálculo de tarifas. O ledger avalia o pacote correspondente no fluxo da transação e aplica as regras dele quando há uma correspondência.

#### [Estimate transaction fees](/pt/reference/products/midaz/v2/estimate-fee-calculation)

* Estima tarifas para um pacote **específico** pelo respectivo `packageId`.
* Retorna tarifas calculadas **apenas se a transação corresponder** às condições do pacote.
* Útil para testes, depuração ou pré-visualização de tarifas, sem gravar no ledger.

<Note>
  A aplicação de tarifas acontece durante a criação da transação. Use `estimate` quando quiser testar um pacote específico sem gravar no ledger.
</Note>

### Isenções baseadas em segmento

Os pacotes de tarifas oferecem suporte à isenção de contas individuais ao listar seus aliases em `waivedAccounts`. Para isentar um grupo inteiro de uma vez, adicione uma referência de segmento à mesma lista usando a forma `segment:<segment-uuid>`, por exemplo `"segment:seg_premium_01HZ..."`.

<Warning>
  O campo `segmentId` do próprio pacote **não** é uma isenção. Ele define qual pacote se aplica a uma transação (correspondência de pacote no nível de segmento). As isenções sempre ficam em `waivedAccounts`.
</Warning>

Use isenções baseadas em segmento quando:

* Um nível de cliente (como contas premium) é universalmente isento de uma tarifa.
* Contas internas ou de parceiros pertencem a um segmento existente no Midaz.
* Manter uma lista de aliases de conta individuais é inviável em escala.

<Tip>
  O Fees Engine resolve isenções baseadas em segmento no momento do cálculo. Quando contas entram ou saem do segmento, a mudança passa a valer no próximo cálculo. Você não precisa atualizar o pacote.
</Tip>

<h2 id="billing-packages">
  Pacotes de Cobrança
</h2>

***

Os **Pacotes de Cobrança** calculam cobranças a partir do volume acumulado de transações em um período (diário ou mensal). Os pacotes de tarifas cobram por transação individual. Os pacotes de cobrança contam as transações que se qualificam e retornam payloads para o seu orquestrador executar.

Há dois tipos disponíveis:

* **Volume**: cobra com base no número de transações que correspondem a um filtro de evento no período.
* **Manutenção**: cobra uma tarifa fixa recorrente por conta ativa, uma vez por período de cobrança.

<Note>
  Os pacotes de cobrança são um mecanismo de cálculo, não uma plataforma de cobrança. O mecanismo calcula as cobranças e retorna os payloads. Seu orquestrador (Flowker, um cron job ou qualquer outro chamador) executa as cobranças reais no Midaz.
</Note>

### Pacotes de volume

Um pacote de volume conta as transações que correspondem a um determinado `eventFilter` (rota de transação + status) dentro do período de cobrança. Em seguida, ele aplica uma cobrança a partir do modelo de precificação configurado.

Campos principais:

* **eventFilter**: especifica quais transações contar, usando `transactionRoute` e `status`.
* **pricingModel**: `tiered` (o preço unitário varia conforme a faixa de quantidade) ou `fixed` (preço unitário único, independente do volume).
* **tiers**: faixas de quantidade (`minQuantity`, `maxQuantity`) e `unitPrice` por unidade dentro de cada faixa.
* **freeQuota**: número de transações isentas por período. O mecanismo subtrai essa contagem antes de aplicar a precificação.
* **discountTiers**: descontos progressivos. Quando o volume total atinge um limite, o mecanismo aplica o percentual de desconto configurado ao valor final.
* **countMode**: aceita `perRoute` ou `perAccount`. O cálculo de volume conta todas as transações correspondentes na rota como um único total.
* **debitAccountAlias** / **creditAccountAlias**: rotas contábeis para a cobrança.

### Pacotes de manutenção

Um pacote de manutenção aplica uma tarifa fixa por conta ativa no período de cobrança, independentemente da atividade de transações.

Campos principais:

* **feeAmount**: cobrança fixa por conta ativa.
* **assetCode**: moeda da cobrança.
* **maintenanceCreditAccount**: conta que recebe a receita da tarifa.
* **accountTarget**: define quais contas cobrar. Use exatamente um por pacote:
  * `segmentId`: todas as contas do segmento.
  * `portfolioId`: todas as contas do portfólio.
  * `aliases`: lista explícita de aliases de conta (máximo de 100 contas).

<Warning>
  Cada pacote de manutenção oferece suporte a apenas um tipo de `accountTarget`. Você não pode combinar `segmentId`, `portfolioId` e `aliases` no mesmo pacote.
</Warning>

### Gerenciando pacotes de cobrança

Os seguintes endpoints gerenciam pacotes de cobrança:

* `POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages`: cria um pacote de cobrança.
* `GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages`: lista todos os pacotes de cobrança.
* `GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{id}`: recupera um pacote de cobrança específico.
* `PATCH /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{id}`: atualiza um pacote de cobrança (`label`, `description`, `enable`).
* `DELETE /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{id}`: exclui de forma reversível um pacote de cobrança.
* `POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate`: calcula a cobrança de um período.

## Pacotes de Tarifas vs. Pacotes de Cobrança

***

|                            | Pacotes de Tarifas                             | Pacotes de Cobrança                                                |
| -------------------------- | ---------------------------------------------- | ------------------------------------------------------------------ |
| **Gatilho**                | Por transação (síncrono)                       | Por período (mensal, semanal ou diário)                            |
| **Modelo de precificação** | Fixo, percentual, maxBetweenTypes              | Escalonado ou fixo por volume                                      |
| **Isenção de conta**       | `waivedAccounts` (aliases ou `segment:<uuid>`) | `accountTarget`: segmento, portfólio ou lista de aliases           |
| **Descontos por volume**   | Não                                            | Sim (`discountTiers`)                                              |
| **Cotas gratuitas**        | Não                                            | Sim (`freeQuota` por período)                                      |
| **Cobranças recorrentes**  | Não                                            | Sim (tipo manutenção)                                              |
| **Execução**               | Automática — o mecanismo avalia cada transação | Acionada pelo chamador — o orquestrador chama `/billing/calculate` |
| **Saída**                  | Transação com tarifas aplicadas                | Payloads de cálculo para o chamador executar                       |

<Note>
  Pacotes de tarifas e pacotes de cobrança operam de forma independente. Uma transação pode acionar o cálculo de um pacote de tarifas e também contar para um pacote de cobrança no mesmo período. São eventos separados e não conflitantes.
</Note>

## Roteamento de tarifas

***

Toda tarifa pode ter:

* Um `routeFrom`, que representa a rota contábil do débito (ou origem).
* Um `routeTo`, que representa a rota contábil do crédito (ou destino).
* Um `transactionRoute`, que representa a natureza geral da transação.

Isso permite o rastreamento granular de cada lançamento de tarifa no ledger.

## Tarifas dedutíveis

***

Se você marcar uma tarifa como dedutível ( `isDeductibleFrom: true`), a seguinte lógica se aplica:

* A **conta de origem envia o valor total**.
* O **mecanismo subtrai a tarifa do valor que a conta de destino recebe**.
* O `referenceAmount` para os cálculos deve ser `originalAmount`.

## Exclusão reversível para registro seguro

***

O Fees Engine não perde dados. Quando você exclui um recurso:

* O Fees Engine o marca com um timestamp `deletedAt`. Registros ativos retornam `deletedAt: null`.
* Consultas padrão o excluem, mas o banco de dados continua armazenando-o para auditoria e histórico.

## Integrações

***

Use o **Fees Engine** em um deploy do Midaz junto com outros componentes do seu stack. Você pode chamar os recursos dele a partir de plugins da Lerian ou da sua própria implementação para aplicar tarifas a partir da sua lógica de negócio.

Casos de uso incluem:

* Mecanismos de câmbio
* Plataformas de empréstimo
* Sistemas de pagamento de contas
* Contratos inteligentes
* Pix (a plataforma de pagamentos instantâneos do Brasil)

## Recomendações de segurança

***

**A segurança é fundamental ao trabalhar com produtos e plugins da Lerian.**\
Antes de fazer o deploy de qualquer componente, consulte nossas [**Recomendações de Segurança**](/pt/products/midaz/security-recommendations). Implemente cada produto e seus plugins de acordo com as boas práticas de segurança, como:

* Proteger os limites de rede
* Gerenciar e rotacionar segredos
* Aplicar patches de segurança em tempo hábil
* Aplicar controles de acesso rígidos baseados em papéis (RBAC)

## Próximos passos

***

<CardGroup cols={2}>
  <Card title="Explore a API do Fees Engine" icon="terminal" href="/pt/reference/products/midaz/v2/create-package">
    Veja os endpoints para pacotes de tarifas, cálculos e estimativas.
  </Card>

  <Card title="Usando o Fees Engine" icon="rocket" href="/pt/products/midaz/fees/using-fee-engine">
    Aprenda a criar pacotes de tarifas e aplicá-los a transações.
  </Card>
</CardGroup>