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

# Usar planes de tarifas

> Crea un plan de tarifas, asígnalo a una cuenta, lee la comisión de cada transacción y el uso del mes, y cobra comisiones de servicio.

Esta guía crea un plan de tarifas con una comisión de transacción y una comisión de servicio, y lo usa en una cuenta. [Planes de tarifas](https://docs.lerian.studio/es/products/midaz/fees/account-plans.md) da las reglas que siguen los pasos.

## Antes de empezar

***

Necesitas:

* Un ledger y una cuenta para el cliente final, aquí con el alias `@customer_001`.
* Una cuenta que recibe las comisiones, aquí con el alias `@fee_revenue`.
* Los permisos `account-plans` y `fee-charges` en Midaz. Consulta [Permisos](https://docs.lerian.studio/es/products/midaz/fees/account-plans.md#permissions).

Los ejemplos usan un ledger sin validación de rutas, donde una comisión de transacción selecciona transacciones por `scheme`. En un ledger con validación de rutas, da también un bloque `accounting` a cada comisión. Consulta [Rutas contables](https://docs.lerian.studio/es/products/midaz/fees/account-plans.md#accounting-routes).

Los ejemplos usan estas variables de shell. Cada UUID es un valor de ejemplo. Usa los valores de tu propio entorno.

```bash theme={null}
MIDAZ_LEDGER_URL="https://midaz.example.com"
MIDAZ_BEARER_TOKEN="..."
MIDAZ_ORGANIZATION_ID="3fa85f64-5717-4562-b3fc-2c963f66afa6"
MIDAZ_LEDGER_ID="9c858901-8a57-4791-81fe-4a34d4dd8ab5"
MIDAZ_ACCOUNT_ID="0199a5c1-3e2f-7b4d-9a8e-5f6d7c8b9a0e"   # the account of @customer_001
```

**1. Crea el plan de tarifas**

Envía el plan a [Crear un plan de tarifas](https://docs.lerian.studio/es/reference/products/midaz/v2/create-an-account-plan.md). La comisión `tedSent` cobra 7.90 por cada TED que envía la cuenta, después de 2 TED gratuitas en el mes. La comisión `paperStatement` cobra 3 por cada extracto en papel, después de 1 extracto gratuito en el mes.

```bash theme={null}
curl -s -X POST "$MIDAZ_LEDGER_URL/v2/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/account-plans" \
  -H "Authorization: Bearer $MIDAZ_BEARER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "label": "Essential PF",
    "description": "Essential plan for individuals",
    "enable": true,
    "timezone": "America/Sao_Paulo",
    "fees": {
      "tedSent": {
        "feeLabel": "TED sent",
        "trigger": { "type": "transaction", "schemes": ["TED"], "direction": "sent" },
        "calculationModel": { "applicationRule": "flatFee", "calculations": [{ "type": "flat", "value": "7.90" }] },
        "creditAccount": "@fee_revenue",
        "freeQuota": 2
      },
      "paperStatement": {
        "feeLabel": "Paper statement",
        "trigger": { "type": "service", "serviceCode": "PAPER_STATEMENT" },
        "calculationModel": { "applicationRule": "flatFee", "calculations": [{ "type": "flat", "value": "3" }] },
        "creditAccount": "@fee_revenue",
        "freeQuota": 1
      }
    }
  }'
```

Midaz responde `201` con el plan y su versión 1. Completa los valores predeterminados de `referenceAmount` y `period`:

```json theme={null}
{
  "id": "019a3b2c-1d4e-7f60-8a9b-0c1d2e3f4a5b",
  "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "ledgerId": "9c858901-8a57-4791-81fe-4a34d4dd8ab5",
  "label": "Essential PF",
  "description": "Essential plan for individuals",
  "enable": true,
  "timezone": "America/Sao_Paulo",
  "currentVersion": 1,
  "version": 1,
  "effectiveFrom": "2026-10-30T13:00:00Z",
  "fees": {
    "paperStatement": {
      "feeLabel": "Paper statement",
      "trigger": { "type": "service", "serviceCode": "PAPER_STATEMENT" },
      "calculationModel": { "applicationRule": "flatFee", "calculations": [{ "type": "flat", "value": "3" }] },
      "referenceAmount": "originalAmount",
      "creditAccount": "@fee_revenue",
      "freeQuota": 1,
      "period": "monthly"
    },
    "tedSent": {
      "feeLabel": "TED sent",
      "trigger": { "type": "transaction", "schemes": ["TED"], "direction": "sent" },
      "calculationModel": { "applicationRule": "flatFee", "calculations": [{ "type": "flat", "value": "7.90" }] },
      "referenceAmount": "originalAmount",
      "creditAccount": "@fee_revenue",
      "freeQuota": 2,
      "period": "monthly"
    }
  },
  "createdAt": "2026-10-30T13:00:00Z",
  "updatedAt": "2026-10-30T13:00:00Z"
}
```

Guarda el `id` del plan:

```bash theme={null}
MIDAZ_ACCOUNT_PLAN_ID="019a3b2c-1d4e-7f60-8a9b-0c1d2e3f4a5b"
```

**2. Asigna el plan a la cuenta**

Envía el plan a [Asignar un plan de tarifas a una cuenta](https://docs.lerian.studio/es/reference/products/midaz/v2/assign-an-account-plan-to-an-account.md):

```bash theme={null}
curl -s -X PUT "$MIDAZ_LEDGER_URL/v2/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/accounts/$MIDAZ_ACCOUNT_ID/account-plan" \
  -H "Authorization: Bearer $MIDAZ_BEARER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d "{ \"accountPlanId\": \"$MIDAZ_ACCOUNT_PLAN_ID\" }"
```

Midaz responde `200` con la asignación activa:

```json theme={null}
{
  "id": "019a3b2d-5e6f-7a80-9b1c-2d3e4f5a6b7c",
  "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "ledgerId": "9c858901-8a57-4791-81fe-4a34d4dd8ab5",
  "accountId": "0199a5c1-3e2f-7b4d-9a8e-5f6d7c8b9a0e",
  "accountAlias": "@customer_001",
  "accountPlanId": "019a3b2c-1d4e-7f60-8a9b-0c1d2e3f4a5b",
  "startedAt": "2026-10-30T13:05:00Z",
  "endedAt": null
}
```

A partir de ahora, los paquetes de comisiones del ledger no cobran a `@customer_001` en las transacciones `/v2` que envía.

**3. Envía una transacción y lee su comisión**

Envía una TED desde la cuenta con [Crear una transacción con el modelo directo v2](https://docs.lerian.studio/es/reference/products/midaz/v2/create-transaction-direct.md). El `scheme` es `TED`, así que la comisión `tedSent` coincide:

```bash theme={null}
curl -s -X POST "$MIDAZ_LEDGER_URL/v2/transactions/direct" \
  -H "Authorization: Bearer $MIDAZ_BEARER_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'X-Idempotency: ted-0001' \
  -d "{
    \"description\": \"TED to another bank\",
    \"asset\": \"BRL\",
    \"amount\": \"100\",
    \"scheme\": \"TED\",
    \"debits\": [
      { \"alias\": \"@customer_001\", \"organizationId\": \"$MIDAZ_ORGANIZATION_ID\", \"ledgerId\": \"$MIDAZ_LEDGER_ID\", \"amount\": \"100\" }
    ],
    \"credits\": [
      { \"alias\": \"@ted_settlement\", \"organizationId\": \"$MIDAZ_ORGANIZATION_ID\", \"ledgerId\": \"$MIDAZ_LEDGER_ID\", \"amount\": \"100\" }
    ]
  }"
```

La respuesta `201` tiene `accountPlanFees`. La primera TED del mes usa una unidad gratuita:

```json theme={null}
"accountPlanFees": [
  {
    "accountId": "0199a5c1-3e2f-7b4d-9a8e-5f6d7c8b9a0e",
    "accountAlias": "@customer_001",
    "accountPlanId": "019a3b2c-1d4e-7f60-8a9b-0c1d2e3f4a5b",
    "accountPlanVersion": 1,
    "feeKey": "tedSent",
    "outcome": "quota",
    "unit": 1,
    "freeQuota": 2,
    "amount": "0"
  }
]
```

La tercera TED del mes supera la cuota gratuita. Su elemento tiene `"outcome": "charged"`, `"unit": 3` y `"amount": "7.9"`. La cuenta envía 107.9: los 100 de la TED y la comisión, que va a `@fee_revenue`.

Una transacción con otro `scheme`, o sin ninguno, recibe `"outcome": "no_match"`. La cuenta no paga comisión en ella.

Guarda `accountPlanFees` de la respuesta de creación. Las lecturas de la transacción no lo devuelven.

**4. Lee el uso del mes**

Lee las unidades de la cuenta con [Obtener el uso del plan de tarifas de una cuenta](https://docs.lerian.studio/es/reference/products/midaz/v2/get-the-account-plan-usage-of-an-account.md):

```bash theme={null}
curl -s "$MIDAZ_LEDGER_URL/v2/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/accounts/$MIDAZ_ACCOUNT_ID/account-plan/usage?period=2026-10" \
  -H "Authorization: Bearer $MIDAZ_BEARER_TOKEN"
```

Después de tres TED, la respuesta es:

```json theme={null}
{
  "accountId": "0199a5c1-3e2f-7b4d-9a8e-5f6d7c8b9a0e",
  "accountPlanId": "019a3b2c-1d4e-7f60-8a9b-0c1d2e3f4a5b",
  "accountPlanVersion": 1,
  "period": { "label": "2026-10", "start": "2026-10-01T03:00:00Z", "end": "2026-11-01T03:00:00Z" },
  "items": [
    {
      "feeKey": "paperStatement",
      "trigger": "fee:paperStatement",
      "period": { "label": "2026-10", "start": "2026-10-01T03:00:00Z", "end": "2026-11-01T03:00:00Z" },
      "freeQuota": 1,
      "used": 0,
      "remaining": 1,
      "charged": 0
    },
    {
      "feeKey": "tedSent",
      "trigger": "fee:tedSent:TED",
      "period": { "label": "2026-10", "start": "2026-10-01T03:00:00Z", "end": "2026-11-01T03:00:00Z" },
      "freeQuota": 2,
      "used": 3,
      "remaining": 0,
      "charged": 1
    }
  ]
}
```

`period.start` y `period.end` son el mes en la zona horaria del plan, en UTC.

**5. Cobra comisiones de servicio**

Cobra dos extractos en papel con [Cobrar comisiones de servicio a una cuenta](https://docs.lerian.studio/es/reference/products/midaz/v2/charge-service-fees-to-an-account.md). Envía una clave `X-Idempotency`, y envía la misma clave cuando reintentes el mismo cobro:

```bash theme={null}
curl -s -X POST "$MIDAZ_LEDGER_URL/v2/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/accounts/$MIDAZ_ACCOUNT_ID/fee-charges" \
  -H "Authorization: Bearer $MIDAZ_BEARER_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'X-Idempotency: statements-2026-10' \
  -d '{
    "serviceCodes": ["PAPER_STATEMENT", "PAPER_STATEMENT"],
    "description": "Paper statements of October"
  }'
```

Midaz responde `201`. El primer extracto usa la unidad gratuita, y el segundo cuesta 3:

```json theme={null}
{
  "id": "019a3b30-7c8d-7e90-a1b2-c3d4e5f6a7b8",
  "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "ledgerId": "9c858901-8a57-4791-81fe-4a34d4dd8ab5",
  "accountId": "0199a5c1-3e2f-7b4d-9a8e-5f6d7c8b9a0e",
  "accountPlanId": "019a3b2c-1d4e-7f60-8a9b-0c1d2e3f4a5b",
  "accountPlanVersion": 1,
  "description": "Paper statements of October",
  "items": [
    { "serviceCode": "PAPER_STATEMENT", "feeKey": "paperStatement", "outcome": "quota", "unit": 1, "freeQuota": 1, "amount": "0" },
    { "serviceCode": "PAPER_STATEMENT", "feeKey": "paperStatement", "outcome": "charged", "unit": 2, "freeQuota": 1, "amount": "3" }
  ],
  "totalAmount": "3",
  "assetCode": "BRL",
  "feeTransactionIds": ["019a3b30-8d9e-7fa0-b2c3-d4e5f6a7b8c9"],
  "period": "2026-10",
  "createdAt": "2026-10-30T14:00:00Z"
}
```

La transacción de comisión debita 3 de `@customer_001` y los acredita en `@fee_revenue`. Para deshacer el cobro en el mismo mes, revierte esa transacción.

**6. Crea una nueva versión**

Sube las TED gratuitas a 5 desde noviembre. Envía solo el campo que cambia a [Actualizar un plan de tarifas](https://docs.lerian.studio/es/reference/products/midaz/v2/update-an-account-plan.md):

```bash theme={null}
curl -s -X PATCH "$MIDAZ_LEDGER_URL/v2/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/account-plans/$MIDAZ_ACCOUNT_PLAN_ID" \
  -H "Authorization: Bearer $MIDAZ_BEARER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "fees": { "tedSent": { "freeQuota": 5 } },
    "effectiveFrom": "2026-11-01T03:00:00Z"
  }'
```

Midaz crea la versión 2 con las dos comisiones, y `tedSent` tiene `freeQuota: 5`. Antes del 1 de noviembre en la zona horaria del plan, la respuesta y las transacciones usan la versión 1, y `currentVersion` es `2`.

**7. Termina la asignación**

Para quitar la cuenta del plan, usa [Terminar la asignación de plan de tarifas de una cuenta](https://docs.lerian.studio/es/reference/products/midaz/v2/end-the-account-plan-assignment-of-an-account.md):

```bash theme={null}
curl -s -X DELETE "$MIDAZ_LEDGER_URL/v2/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/accounts/$MIDAZ_ACCOUNT_ID/account-plan" \
  -H "Authorization: Bearer $MIDAZ_BEARER_TOKEN"
```

Midaz responde `204`. Los paquetes de comisiones del ledger vuelven a aplicarse a la cuenta.


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