> ## 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](https://docs.lerian.studio/pt/products/midaz/fees/fees-engine-overview.md#billing-packages) e a [referência da API](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-billing-package.md).

## 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. Um segmento 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": "0198e5f4-7b2a-7c3d-9e1f-2a3b4c5d6e7f"
  }
}
```

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

***

### A necessidade de negócio

Uma fintech cobra R\$ 0,10 por Pix enviado (tarifa fixa, sem camadas).

### 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"
}
```

### Como o cálculo funciona

**Resultado de exemplo** para 5.000 transações Pix:

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

## 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": "0198e5f4-8c1d-7a2b-9f3e-4d5c6b7a8e9f"
  }
}
```

**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": "0198e5f4-9d2e-7b3c-8a4f-5e6d7c8b9a0e"
  }
}
```

### 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`, então a receita fica consolidada. O orquestrador envia cada payload de transação ao Midaz de forma independente.

## Próximos passos

***

> [card] [Criar um pacote de faturamento](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-billing-package.md)
>
> Referência da API para criar pacotes de faturamento de volume e manutenção.

> [card] [Calcular faturamento](https://docs.lerian.studio/pt/reference/products/midaz/v2/calculate-billing.md)
>
> Dispare cálculos de faturamento para um período e recupere payloads de transação.

> [card] [Cálculos de faturamento](https://docs.lerian.studio/pt/products/midaz/fees/fee-engine-calculation.md#billing-calculations)
>
> Mecânica detalhada da precificação em camadas, cotas gratuitas e faturamento de manutenção.

> [card] [Boas práticas](https://docs.lerian.studio/pt/products/midaz/fees/fees-engine-best-practices.md)
>
> Orientação operacional para pacotes de faturamento em produção.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.