> ## 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 Use o endpoint [List Operations by Account](/pt/reference/products/midaz/v2/get-all-operations-by-account) 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 ``` 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 | 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 | 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 ``` 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" } } ``` ### Use `direction` para determinar o sinal | Direção | Comportamento de exibição | | -------- | -------------------------- | | `credit` | Exibir como valor positivo | | `debit` | Exibir como valor negativo | 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. 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. O Midaz mantém o ledger consistente e auditável. O sistema integrador adiciona contexto de negócio ao metadata de cada operação.