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

# Monte um extrato de conta

> Transforme as operações de conta do Midaz em um extrato claro para o cliente, filtrando por data, direção e rota com o endpoint List Operations by Account.

Você monta um extrato de conta a partir das operações de conta do Midaz. Cada operação é um lançamento do ledger vinculado a uma conta, como um crédito, débito, retenção, liberação ou evento de overdraft.

Para montar um extrato, recupere as operações de conta do período. Mantenha as operações que afetam a visualização do extrato. Em seguida, transforme cada operação em uma linha que os usuários entendam.

![Fluxo de saldo da conta](https://mintcdn.com/lerian-49cb71fc/vdBt8wfgjsNRO1rf/images/pt/d2/account-balance-flow.svg?fit=max\&auto=format\&n=vdBt8wfgjsNRO1rf\&q=85\&s=c6ef02dac869b3bde0dc4a3d875dd90d)

Fluxo de saldo da conta

## 1. Recuperar operações de conta

Use o endpoint [List Operations by Account](https://docs.lerian.studio/pt/reference/products/midaz/v2/get-all-operations-by-account.md) para listar as operações de uma conta específica:

```json theme={null}
GET /v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/operations
```

## 2. Aplicar filtros de consulta

Use parâmetros de consulta para definir o período do extrato, controlar a paginação e filtrar as operações que o endpoint retorna.

### Obrigatório para consultas de extrato

| Parâmetro | Descrição |
| - | - |
| `start_date` | Data inicial do período do extrato |
| `end_date` | Data final do período do extrato |
| `limit` | Número de itens por página |
| `sort_order=desc` | Retorna primeiro as operações mais recentes |

Você precisa desses campos para este caso de uso de extrato. Eles definem a janela do extrato e tornam o resultado previsível para os usuários.

### Obrigatório para paginação

| Parâmetro | Descrição |
| - | - |
| `cursor` | Cursor retornado pela resposta anterior |

### Filtros opcionais

| Parâmetro | Descrição |
| - | - |
| `direction=credit` | Retorna apenas operações de entrada |
| `direction=debit` | Retorna apenas operações de saída |
| `type` | Filtra por tipo de operação |
| `route_id` | Filtra pelo ID da rota da operação (UUID) |
| `route_code` | Filtra pelo código da rota da operação |
| `sort_by=created_at` | Ordena pela data de criação e depois pelo ID. O padrão é `id`. Use o mesmo valor em todas as páginas de um cursor. |

O endpoint pode retornar os seguintes tipos de operação:

| Tipo | O que significa |
| - | - |
| `CREDIT` | Valor entrando na conta |
| `DEBIT` | Valor saindo da conta |
| `ON_HOLD` | Valor temporariamente retido |
| `RELEASE` | Valor anteriormente retido, liberado |
| `OVERDRAFT` | Movimentação relacionada ao uso do overdraft |
| `BLOCK` | Linha companheira de bloqueio de conta gerada pelo sistema |
| `UNBLOCK` | Linha companheira de desbloqueio de conta gerada pelo sistema |
| `FEE_SETTLEMENT` | Liquidação de uma dívida de tarifa |
| `FEE_REFUND` | Reembolso de uma dívida de tarifa liquidada em um estorno |

Use `type` para classificar a movimentação contábil. Use `direction` para decidir se o extrato exibe o valor como positivo ou negativo.

Exemplo de requisição:

```json theme={null}
GET /v1/organizations/org_123/ledgers/ledger_001/accounts/account_456/operations?start_date=2026-05-01&end_date=2026-05-31&limit=50&sort_order=desc
```

## 3. Transformar operações em lançamentos do extrato

Cada objeto no array `items` pode se tornar uma linha do extrato.

### Obrigatório para renderizar o extrato

| Campo do extrato | Campo da operação |
| - | - |
| Data | `createdAt` |
| Descrição | `description` |
| Tipo de movimentação | `type` |
| Direção | `direction` |
| Valor | `amount.value` |
| Moeda ou ativo | `assetCode` |
| Saldo após a operação | `balanceAfter.available` |
| Referência de recibo ou transação | `transactionId` |

Você precisa desses campos para renderizar uma linha de extrato útil. A API não exige todos eles. Um extrato sem esses campos perde significado, rastreabilidade ou contexto de saldo.

### Recomendado para extratos amigáveis ao usuário

| Contexto do extrato | Campo da operação |
| - | - |
| Contraparte | `metadata.counterparty` |
| Documento | `metadata.document` |
| Chave Pix | `metadata.pixKey` |
| ID de ponta a ponta | `metadata.endToEndId` |
| Canal | `metadata.channel` |
| Categoria | `metadata.category` |

O Midaz retorna a movimentação do ledger. O sistema integrador deve adicionar contexto de negócio no `metadata` de cada entrada relevante de `source.from[]` e `distribute.to[]` ao criar a transação. Os metadados não se propagam das entradas de origem para as de destino.

Exemplo de transformação:

```json theme={null}
{
  "date": "2026-05-18T14:23:11Z",
  "description": "Pix transfer received",
  "type": "CREDIT",
  "direction": "credit",
  "amount": "150.00",
  "asset": "BRL",
  "balanceAfter": "1240.55",
  "transactionId": "txn_987654",
  "metadata": {
    "counterparty": "John Doe",
    "pixKey": "john@example.com",
    "category": "Transfer"
  }
}
```

## 4. Aplicar regras de exibição do extrato

### Use `direction` para determinar o sinal

| Direção | Comportamento de exibição |
| - | - |
| `credit` | Exibir como valor positivo |
| `debit` | Exibir como valor negativo |

> [!WARNING]
>
> Não use `type` para determinar se o valor é positivo ou negativo. O campo `type` classifica a movimentação contábil, enquanto `direction` define se o valor entra ou sai da conta.

### Trate operações de retenção e liberação separadamente

Não exiba operações com os seguintes tipos como movimentações liquidadas normais:

* `ON_HOLD`
* `RELEASE`

Em vez disso:

* `ON_HOLD` deve aparecer como uma retenção de saldo ou bloqueio temporário
* `RELEASE` deve aparecer como uma liberação de saldo ou desbloqueio

### Defina uma política de operação liquidada

Não use `balanceAffected` como predicado de operação liquidada. Uma operação `ON_HOLD` normal pode definir `balanceAffected` como `true` sem alterar o saldo disponível. Defina sua política de extrato explicitamente a partir do tipo e do status da operação, e exiba `ON_HOLD` e `RELEASE` de acordo com as regras de retenção/liberação acima.

## 5. Tratar a paginação

O endpoint divide as respostas em páginas de acordo com o valor de `limit`.

Para recuperar todas as operações:

1. Leia o campo `next_cursor` na resposta
2. Envie-o como o parâmetro `cursor` na próxima requisição
3. Repita até a resposta deixar de retornar `next_cursor`

Exemplo de fluxo:

```text theme={null}
Request 1
  -> returns items + next_cursor

Request 2
  -> cursor=next_cursor
  -> returns more items + next_cursor

Repeat until next_cursor is no longer returned
```

## Exemplo de saída do extrato

Depois de aplicar os filtros, transformar as operações e aplicar as regras de exibição, o extrato final pode ficar assim:

| Data | Descrição | Valor | Saldo após |
| - | - | - | - |
| 2026-05-18 | Pix recebido de John Doe | +150,00 BRL | 1.240,55 BRL |
| 2026-05-18 | Compra no cartão | -45,90 BRL | 1.194,65 BRL |

A API não retorna uma página de extrato pronta. Ela retorna eventos do ledger que o sistema integrador transforma em uma experiência de extrato.

## Adicione contexto de negócio

O endpoint de operações retorna eventos contábeis. Um extrato voltado ao usuário precisa de mais contexto do que apenas a movimentação do ledger.

Envie metadados de negócio no metadata de cada operação ao criar a transação. O Midaz armazena esses campos junto com a operação. O extrato pode usá-los depois para mostrar quem, o quê e por que está por trás da movimentação.

* `counterparty`
* `document`
* `pixKey`
* `endToEndId`
* `channel`
* `category`

Exemplo de metadados:

```json theme={null}
"send": {
  "source": {
    "from": [{
      "accountAlias": "customer_123",
      "metadata": {
        "counterparty": "John Doe",
        "document": "12345678900",
        "pixKey": "john@example.com",
        "endToEndId": "E1234567890123456789012345678901",
        "channel": "PIX",
        "category": "Transfer"
      }
    }]
  }
}
```

Isso permite exibir lançamentos como:

* "Pix recebido de John Doe"
* "Compra no cartão em Coffee Shop"
* "Transferência para Conta Poupança"

em vez de descrições contábeis genéricas.

Se o sistema integrador não enviar esses campos, o extrato ainda funciona. Nesse caso, ele apenas pode exibir os dados contábeis que a operação retorna.

> [!TIP]
>
> O Midaz mantém o ledger consistente e auditável. O sistema integrador adiciona contexto de negócio ao metadata de cada operação.


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