> ## 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 planos de tarifas

> Crie um plano de tarifas, atribua-o a uma conta, leia a tarifa de cada transação e o uso do mês e cobre tarifas de serviço.

Este guia cria um plano de tarifas com uma tarifa de transação e uma tarifa de serviço e o usa em uma conta. [Planos de tarifas](https://docs.lerian.studio/pt/products/midaz/fees/account-plans.md) traz as regras que os passos seguem.

## Antes de começar

***

Você precisa de:

* Um ledger e uma conta para o cliente final, aqui com o alias `@customer_001`.
* Uma conta que recebe as tarifas, aqui com o alias `@fee_revenue`.
* As permissões `account-plans` e `fee-charges` no Midaz. Veja [Permissões](https://docs.lerian.studio/pt/products/midaz/fees/account-plans.md#permissions).

Os exemplos usam um ledger sem validação de rotas, em que uma tarifa de transação seleciona transações pelo `scheme`. Em um ledger com validação de rotas, dê também um bloco `accounting` a cada tarifa. Veja [Rotas contábeis](https://docs.lerian.studio/pt/products/midaz/fees/account-plans.md#accounting-routes).

Os exemplos usam estas variáveis de shell. Todo UUID é um valor de exemplo. Use os valores do seu próprio ambiente.

```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. Crie o plano de tarifas**

Envie o plano para [Criar um plano de tarifas](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-an-account-plan.md). A tarifa `tedSent` cobra 7.90 por cada TED que a conta envia, depois de 2 TEDs gratuitas no mês. A tarifa `paperStatement` cobra 3 por cada extrato em papel, depois de 1 extrato gratuito no mês.

```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
      }
    }
  }'
```

O Midaz responde `201` com o plano e a versão 1 dele. Ele preenche os valores padrão de `referenceAmount` e `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"
}
```

Guarde o `id` do plano:

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

**2. Atribua o plano à conta**

Envie o plano para [Atribuir um plano de tarifas a uma conta](https://docs.lerian.studio/pt/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\" }"
```

O Midaz responde `200` com a atribuição ativa:

```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 agora, os pacotes de tarifas do ledger não cobram `@customer_001` nas transações `/v2` que ela envia.

**3. Envie uma transação e leia a tarifa dela**

Envie uma TED da conta com [Criar uma Transação no modelo direto v2](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-transaction-direct.md). O `scheme` é `TED`, então a tarifa `tedSent` corresponde:

```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\" }
    ]
  }"
```

A resposta `201` traz `accountPlanFees`. A primeira TED do mês usa uma unidade 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"
  }
]
```

A terceira TED do mês passa da cota gratuita. O item dela traz `"outcome": "charged"`, `"unit": 3` e `"amount": "7.9"`. A conta envia 107.9: os 100 da TED e a tarifa, que vai para `@fee_revenue`.

Uma transação com outro `scheme`, ou sem nenhum, recebe `"outcome": "no_match"`. A conta não paga tarifa nela.

Guarde `accountPlanFees` da resposta de criação. As leituras da transação não o retornam.

**4. Leia o uso do mês**

Leia as unidades da conta com [Consultar o uso do plano de tarifas de uma conta](https://docs.lerian.studio/pt/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"
```

Depois de três TEDs, a resposta é:

```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` e `period.end` são o mês no fuso horário do plano, em UTC.

**5. Cobre tarifas de serviço**

Cobre dois extratos em papel com [Cobrar tarifas de serviço de uma conta](https://docs.lerian.studio/pt/reference/products/midaz/v2/charge-service-fees-to-an-account.md). Envie uma chave `X-Idempotency` e envie a mesma chave quando repetir a mesma cobrança:

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

O Midaz responde `201`. O primeiro extrato usa a unidade gratuita, e o segundo custa 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"
}
```

A transação de tarifa debita 3 de `@customer_001` e os credita em `@fee_revenue`. Para desfazer a cobrança no mesmo mês, estorne essa transação.

**6. Crie uma nova versão**

Aumente as TEDs gratuitas para 5 a partir de novembro. Envie só o campo que muda para [Atualizar um plano de tarifas](https://docs.lerian.studio/pt/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"
  }'
```

O Midaz cria a versão 2 com as duas tarifas, e `tedSent` tem `freeQuota: 5`. Antes de 1º de novembro no fuso horário do plano, a resposta e as transações usam a versão 1, e `currentVersion` é `2`.

**7. Termine a atribuição**

Para tirar a conta do plano, use [Terminar a atribuição de plano de tarifas de uma conta](https://docs.lerian.studio/pt/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"
```

O Midaz responde `204`. Os pacotes de tarifas do ledger voltam a se aplicar à conta.


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