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

# Exemplos de pacotes de faturamento do Fees Engine

> Veja exemplos completos de pacotes de faturamento para precificação em camadas de boleto, descontos por volume e cobranças de manutenção de conta, com a configuração JSON completa.

<Tip>
  Esta página tem foco de negócio. Ela mostra *o que* cada modelo de faturamento resolve e *como* configurá-lo. Para detalhes de cada campo, veja a [visão geral de Pacotes de Faturamento](/pt/products/midaz/fees/fees-engine-overview#billing-packages) e a [referência da API](/pt/reference/products/midaz/v2/create-billing-package).
</Tip>

## Faturamento por volume: emissão de boleto com precificação em camadas

***

### A necessidade de negócio

Uma fintech oferece emissão de boleto para seus clientes empresariais. A precificação é baseada em volume: quanto mais boletos um cliente emite por mês, menor o custo unitário. Os primeiros 50 boletos de cada mês são gratuitos. Clientes que emitem 1.000 boletos ou mais recebem um desconto adicional de 5%. A partir de 3.000 boletos, o desconto sobe para 10%.

### Estrutura de precificação

| Faixa     | Preço unitário |
| --------- | -------------- |
| 1–500     | R\$ 1,20       |
| 501–2.000 | R\$ 0,80       |
| 2.001+    | R\$ 0,45       |

### Configuração do pacote

```json theme={null}
POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages
Body:
{
  "label": "Boleto Issuance — Tiered",
  "description": "Monthly volume billing for boleto issuance with progressive tiers",
  "type": "volume",
  "enable": true,
  "eventFilter": {
    "transactionRoute": "boleto-issuance",
    "status": "APPROVED"
  },
  "pricingModel": "tiered",
  "tiers": [
    { "minQuantity": 1, "maxQuantity": 500, "unitPrice": "1.20" },
    { "minQuantity": 501, "maxQuantity": 2000, "unitPrice": "0.80" },
    { "minQuantity": 2001, "maxQuantity": null, "unitPrice": "0.45" }
  ],
  "freeQuota": 50,
  "discountTiers": [
    { "minQuantity": 1000, "discountPercentage": "5.00" },
    { "minQuantity": 3000, "discountPercentage": "10.00" }
  ],
  "countMode": "perRoute",
  "assetCode": "BRL",
  "debitAccountAlias": "client-operating",
  "creditAccountAlias": "fees-boleto-revenue"
}
```

### Como o cálculo funciona

No fim do mês, o orquestrador chama `POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate` com o período de faturamento. O engine conta as transações de boleto aprovadas na rota, subtrai a cota gratuita, aplica a precificação em camadas e aplica o desconto correspondente.

A precificação em camadas é **precificação por volume**: o engine identifica a única camada em que a quantidade faturável se encaixa e cobra cada unidade faturável pelo preço dessa camada. Ele não cobra a fatia de cada camada separadamente.

**Resultado de exemplo** para um cliente que emitiu 1.800 boletos em março:

| Etapa                 | Detalhe                     | Valor            |
| --------------------- | --------------------------- | ---------------- |
| Total emitido         | 1.800 boletos               | —                |
| Cota gratuita         | 50 isentos                  | —                |
| Faturável             | 1.750 boletos               | —                |
| Camada correspondente | 501–2.000 → R\$ 0,80        | —                |
| Bruto                 | 1.750 × R\$ 0,80            | R\$ 1.400,00     |
| Desconto              | 5% (contagem total ≥ 1.000) | −R\$ 70,00       |
| **Total líquido**     | —                           | **R\$ 1.330,00** |

O engine retorna um payload de transação que debita R\$ 1.330,00 de `client-operating` e credita `fees-boleto-revenue`.

## Faturamento de manutenção: tarifa mensal de conta (*PF*)

***

### A necessidade de negócio

Um banco digital cobra uma tarifa fixa de manutenção mensal para contas pessoa física (PF) ativas. A tarifa é de R\$ 9,90 por conta. O engine mantém apenas as contas cujo código de status é `active` e exclui qualquer outro status. Você não filtra essas contas manualmente.

O Midaz organiza contas por segmento. O segmento `seg_pf` agrupa todas as contas pessoa física.

### Configuração do pacote

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

### Como o cálculo funciona

O engine resolve todas as contas no segmento PF e filtra pelo status ativo. Ele gera uma transação N:1: debita R\$ 9,90 de cada conta ativa e envia o total completo para `fees-maintenance-pf`.

**Resultado de exemplo** para 12.000 contas PF ativas:

| Detalhe                            | Valor                        |
| :--------------------------------- | :--------------------------- |
| Contas ativas                      | 12.000                       |
| Tarifa por conta                   | R\$ 9,90                     |
| Lançamentos da transação (origem)  | 12.000 lançamentos de débito |
| Lançamentos da transação (destino) | 1 lançamento de crédito      |
| **Receita total**                  | **R\$ 118.800,00**           |

## Faturamento por volume: Pix com preço fixo e isenção por segmento

***

### A necessidade de negócio

Uma fintech cobra R\$ 0,10 por Pix enviado (tarifa fixa, sem camadas). Clientes do nível premium não pagam tarifa. Em vez de listar cada conta premium, você configura a isenção no nível do segmento.

### Configuração do pacote

```json theme={null}
POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages
Body:
{
  "label": "Pix Send — Standard",
  "description": "Flat-rate billing per Pix sent",
  "type": "volume",
  "enable": true,
  "eventFilter": {
    "transactionRoute": "pix-send",
    "status": "APPROVED"
  },
  "pricingModel": "fixed",
  "tiers": [
    { "minQuantity": 1, "maxQuantity": null, "unitPrice": "0.10" }
  ],
  "freeQuota": 0,
  "discountTiers": [],
  "countMode": "perRoute",
  "assetCode": "BRL",
  "debitAccountAlias": "client-wallet",
  "creditAccountAlias": "fees-pix-revenue"
}
```

### Isenção por segmento

Para isentar contas premium, configure o pacote de tarifas para a rota `pix-send`. Adicione uma referência de segmento a `waivedAccounts`:

```json theme={null}
{
  "waivedAccounts": [
    "segment:seg_premium_01HZ..."
  ]
}
```

Todas as contas no segmento premium ficam isentas automaticamente. Quando as contas entram ou saem do segmento no Midaz, a mudança passa a valer no próximo cálculo. Você não atualiza o pacote.

### Como o cálculo funciona

**Resultado de exemplo** para 5.000 transações Pix de contas padrão:

| Detalhe               | Valor          |
| :-------------------- | :------------- |
| Total de Pix enviados | 5.000          |
| Preço unitário        | R\$ 0,10       |
| **Total**             | **R\$ 500,00** |

Contas premium aparecem com cobrança zero nos resultados de faturamento.

## Faturamento de manutenção: portfólios PJ com taxas diferentes

***

### A necessidade de negócio

Uma instituição financeira gerencia múltiplos portfólios de contas empresariais (PJ): PME (pequenas e médias empresas) e Corporate. Cada portfólio tem uma tarifa de manutenção mensal diferente. A instituição quer calcular os dois em uma única execução de faturamento.

### Configuração do pacote

**Portfólio PME (R\$ 29,90/mês):**

```json theme={null}
POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages
Body:
{
  "label": "PJ Maintenance — PME",
  "description": "Monthly maintenance for PME business accounts",
  "type": "maintenance",
  "enable": true,
  "feeAmount": "29.90",
  "assetCode": "BRL",
  "maintenanceCreditAccount": "fees-maintenance-pj",
  "accountTarget": {
    "portfolioId": "port_pme_01HZ..."
  }
}
```

**Portfólio Corporate (R\$ 89,90/mês):**

```json theme={null}
POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages
Body:
{
  "label": "PJ Maintenance — Corporate",
  "description": "Monthly maintenance for Corporate business accounts",
  "type": "maintenance",
  "enable": true,
  "feeAmount": "89.90",
  "assetCode": "BRL",
  "maintenanceCreditAccount": "fees-maintenance-pj",
  "accountTarget": {
    "portfolioId": "port_corp_01HZ..."
  }
}
```

### Como o cálculo funciona

Uma única chamada a `POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate` com `"type": "maintenance"` processa os dois pacotes. A resposta inclui um resultado por pacote e um resumo consolidado.

**Resultado de exemplo** para 500 contas PME + 50 contas Corporate:

| Portfólio       | Contas ativas | Tarifa    | Total             |
| --------------- | ------------- | --------- | ----------------- |
| PME             | 500           | R\$ 29,90 | R\$ 14.950,00     |
| Corporate       | 50            | R\$ 89,90 | R\$ 4.495,00      |
| **Consolidado** | **550**       | —         | **R\$ 19.445,00** |

Os dois resultados creditam a mesma conta `fees-maintenance-pj`, mantendo a receita consolidada. O orquestrador envia cada payload de transação ao Midaz de forma independente.

## Próximos passos

***

<CardGroup cols={2}>
  <Card title="Criar um pacote de faturamento" icon="plus" href="/pt/reference/products/midaz/v2/create-billing-package">
    Referência da API para criar pacotes de faturamento de volume e manutenção.
  </Card>

  <Card title="Calcular faturamento" icon="calculator" href="/pt/reference/products/midaz/v2/calculate-billing">
    Dispare cálculos de faturamento para um período e recupere payloads de transação.
  </Card>

  <Card title="Cálculos de faturamento" icon="chart-line" href="/pt/products/midaz/fees/fee-engine-calculation#billing-calculations">
    Mecânica detalhada da precificação em camadas, cotas gratuitas e faturamento de manutenção.
  </Card>

  <Card title="Boas práticas" icon="shield-check" href="/pt/products/midaz/fees/fees-engine-best-practices">
    Orientação operacional para pacotes de faturamento em produção.
  </Card>
</CardGroup>