> ## 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.
# Ejemplos de paquetes de facturación del Fees Engine
> Recorre ejemplos completos de paquetes de facturación para tarifas escalonadas de boletos, descuentos por volumen y cargos de mantenimiento de cuentas, con la configuración JSON completa.
Esta página está orientada al negocio. Se enfoca en *qué* resuelve cada modelo de facturación y *cómo* configurarlo. Para detalles en el nivel de campo, consulta el [resumen de paquetes de facturación](/es/products/midaz/fees/fees-engine-overview#billing-packages) y la [referencia de la API](/es/reference/products/midaz/v2/create-billing-package).
## Facturación por volumen: emisión de boletos con precios escalonados
***
### La necesidad de negocio
Una fintech ofrece emisión de boletos a sus clientes empresariales. El precio se basa en el volumen: cuantos más boletos emite un cliente cada mes, menor es el costo unitario. Los primeros 50 boletos de cada mes son gratuitos. Los clientes que emiten 1,000 boletos o más reciben un descuento adicional del 5%. A partir de 3,000 boletos, el descuento sube al 10%.
### Estructura de precios
| Rango | Precio unitario |
| --------- | --------------- |
| 1–500 | R\$ 1.20 |
| 501–2,000 | R\$ 0.80 |
| 2,001+ | R\$ 0.45 |
### Configuración del paquete
```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"
}
```
### Cómo funciona el cálculo
Al final del mes, el orquestador llama a `POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate` con el período de facturación. El motor cuenta las transacciones de boletos aprobadas en la ruta, resta la cuota gratuita, aplica el precio escalonado y aplica el descuento correspondiente.
El precio escalonado es **precio por volumen**: el motor elige el único nivel en el que cae la cantidad facturable y cobra cada unidad facturable al precio de ese nivel. No factura cada tramo de nivel por separado.
**Resultado de ejemplo** para un cliente que emitió 1,800 boletos en marzo:
| Paso | Detalle | Monto |
| --------------------- | ------------------------- | ---------------- |
| Total emitido | 1,800 boletos | — |
| Cuota gratuita | 50 exentos | — |
| Facturable | 1,750 boletos | — |
| Nivel correspondiente | 501–2,000 → R\$ 0.80 | — |
| Bruto | 1,750 × R\$ 0.80 | R\$ 1,400.00 |
| Descuento | 5% (conteo total ≥ 1,000) | −R\$ 70.00 |
| **Total neto** | — | **R\$ 1,330.00** |
El motor devuelve un payload de transacción que debita R\$ 1,330.00 de `client-operating` y acredita a `fees-boleto-revenue`.
## Facturación de mantenimiento: cargo mensual de cuenta (*PF*)
***
### La necesidad de negocio
Un banco digital cobra una comisión mensual fija de mantenimiento para cuentas personales (PF) activas. La comisión es de R\$ 9.90 por cuenta. El motor conserva solo las cuentas cuyo código de estado es `active` y excluye cualquier otro estado. No necesitas filtrarlas manualmente.
Midaz organiza las cuentas por segmento. El segmento `seg_pf` agrupa todas las cuentas personales.
### Configuración del paquete
```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..."
}
}
```
### Cómo funciona el cálculo
El motor resuelve todas las cuentas del segmento PF y filtra por estado activo. Genera una transacción N:1: debita R\$ 9.90 de cada cuenta activa y envía el total completo a `fees-maintenance-pf`.
**Resultado de ejemplo** para 12,000 cuentas PF activas:
| Detalle | Valor |
| :-------------------------------- | :------------------------ |
| Cuentas activas | 12,000 |
| Comisión por cuenta | R\$ 9.90 |
| Entradas de transacción (origen) | 12,000 entradas de débito |
| Entradas de transacción (destino) | 1 entrada de crédito |
| **Ingreso total** | **R\$ 118,800.00** |
## Facturación por volumen: Pix a precio fijo con exención de segmento
***
### La necesidad de negocio
Una fintech cobra R\$ 0.10 por cada Pix enviado (tarifa fija, sin niveles). Los clientes de nivel premium no pagan comisión. En lugar de listar cada cuenta premium, configuras la exención en el nivel de segmento.
### Configuración del paquete
```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"
}
```
### Exención de segmento
Para exentar las cuentas premium, configura el paquete de comisiones para la ruta `pix-send`. Agrega una referencia de segmento a `waivedAccounts`:
```json theme={null}
{
"waivedAccounts": [
"segment:seg_premium_01HZ..."
]
}
```
Todas las cuentas del segmento premium quedan exentas automáticamente. Cuando las cuentas se unen o salen del segmento en Midaz, el cambio surte efecto en el siguiente cálculo. No necesitas actualizar el paquete.
### Cómo funciona el cálculo
**Resultado de ejemplo** para 5,000 transacciones Pix de cuentas estándar:
| Detalle | Valor |
| :-------------------- | :------------- |
| Total de Pix enviados | 5,000 |
| Precio unitario | R\$ 0.10 |
| **Total** | **R\$ 500.00** |
Las cuentas premium muestran cargo cero en los resultados de facturación.
## Facturación de mantenimiento: portafolios PJ con tarifas diferentes
***
### La necesidad de negocio
Una institución financiera administra varios portafolios de cuentas empresariales (PJ): PME (pequeñas y medianas empresas) y Corporate. Cada portafolio tiene una comisión de mantenimiento mensual diferente. La institución quiere calcular ambos en un solo Billing Run.
### Configuración del paquete
**Portafolio PME (R\$ 29.90/mes):**
```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..."
}
}
```
**Portafolio Corporate (R\$ 89.90/mes):**
```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..."
}
}
```
### Cómo funciona el cálculo
Una sola llamada a `POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate` con `"type": "maintenance"` procesa ambos paquetes. La respuesta incluye un resultado por paquete y un resumen consolidado.
**Resultado de ejemplo** para 500 cuentas PME + 50 cuentas Corporate:
| Portafolio | Cuentas activas | Comisión | 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** |
Ambos resultados acreditan a la misma cuenta `fees-maintenance-pj`, lo que mantiene el ingreso consolidado. El orquestador envía cada payload de transacción a Midaz de forma independiente.
## Próximos pasos
***
Referencia de la API para crear paquetes de facturación de volumen y de mantenimiento.
Activa cálculos de facturación para un período y obtén los payloads de transacción.
Mecánica detallada del precio escalonado, las cuotas gratuitas y la facturación de mantenimiento.
Guía operativa para paquetes de facturación en producción.