> ## 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. # Construir um extrato de conta > Use as operações de conta para construir uma visão de extrato clara a partir das movimentações do ledger do Midaz. Este guia explica como integradores podem transformar as operações de conta do Midaz em extratos de conta para o usuário final. Um extrato de conta no Midaz é construído a partir das operações de conta. Cada operação é uma movimentação do ledger vinculada a uma conta, como um crédito, débito, retenção, liberação ou evento de cheque especial. Para construir um extrato, recupere as operações de conta do período, mantenha as operações que afetam a visão do extrato e transforme cada operação em uma linha que os usuários consigam entender. Fluxo do saldo da conta Use o endpoint [Listar Operações por Conta](/pt/reference/midaz/list-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 retornadas pelo endpoint. ### Obrigatórios para consultas de extrato | Parâmetro | Descrição | | ----------------- | ------------------------------------------- | | `start_date` | Data de início do período do extrato | | `end_date` | Data de fim do período do extrato | | `limit` | Número de itens por página | | `sort_order=desc` | Retorna primeiro as operações mais recentes | Esses campos são obrigatórios 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 ao paginar | Parâmetro | Descrição | | --------- | ------------------------------------- | | `cursor` | Cursor retornado na resposta anterior | ### Filtros opcionais | Parâmetro | Descrição | | ------------------ | ----------------------------------------- | | `direction=credit` | Retorna apenas as operações de entrada | | `direction=debit` | Retorna apenas as operações de saída | | `type` | Filtra por tipo de operação | | `route_id` | Filtra pelo ID (UUID) da rota de operação | | `route_code` | Filtra pelo código da rota de operação | Tipos de operação suportados: | Tipo | O que significa | | ----------- | -------------------------------------------------- | | `CREDIT` | Valor entrando na conta | | `DEBIT` | Valor saindo da conta | | `ON_HOLD` | Valor temporariamente bloqueado | | `RELEASE` | Valor anteriormente bloqueado liberado | | `OVERDRAFT` | Movimentação relacionada ao uso de cheque especial | Use `type` para classificar a movimentação contábil. Use `direction` para decidir se o valor é exibido como positivo ou negativo no extrato. 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 retornado 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` | | Recibo ou referência da transação | `transactionId` | Esses campos são obrigatórios para renderizar uma linha útil do extrato. Eles não são todos obrigatórios pela API, mas um extrato sem eles 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 end-to-end | `metadata.endToEndId` | | Canal | `metadata.channel` | | Categoria | `metadata.category` | O Midaz retorna a movimentação do ledger. O sistema integrador deve adicionar o contexto de negócio em `metadata` ao criar a transação. Exemplo de transformação: ```json theme={null} { "date": "2026-05-18T14:23:11Z", "description": "Transferência Pix recebida", "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ência" } } ``` ### Use `direction` para determinar o sinal | Direção | Comportamento de exibição | | -------- | ----------------------------- | | `credit` | Exibir como um valor positivo | | `debit` | Exibir como um 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 as operações de retenção e liberação separadamente Operações com os seguintes tipos não devem ser exibidas como movimentações liquidadas regulares: * `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 ou desbloqueio de saldo ### Exiba apenas as operações liquidadas Para uma visão de extrato liquidado, inclua apenas as operações em que: ```json theme={null} "balanceAffected": true ``` Isso mantém o extrato focado nas movimentações que alteraram o saldo disponível. As respostas podem ser paginadas dependendo do `limit` selecionado. Para recuperar todas as operações: 1. Leia o campo `next_cursor` da resposta 2. Envie-o na próxima requisição usando o parâmetro `cursor` 3. Repita até que `next_cursor` não seja mais retornado Exemplo de fluxo: ```text theme={null} Requisição 1 -> retorna items + next_cursor Requisição 2 -> cursor=next_cursor -> retorna mais items + next_cursor Repetir até next_cursor ser null ``` ## Exemplo de saída do extrato Após 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 com 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. ## Adicionar 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 os metadados de negócio no payload da transação ao criá-la. O Midaz armazena esses campos junto da operação, e o extrato pode usá-los depois para mostrar quem, o quê e por quê por trás da movimentação. * `counterparty` * `document` * `pixKey` * `endToEndId` * `channel` * `category` Exemplo de metadados: ```json theme={null} "metadata": { "counterparty": "John Doe", "document": "12345678900", "pixKey": "john@example.com", "endToEndId": "E1234567890123456789012345678901", "channel": "Pix", "category": "Transferência" } ``` Isso torna possível exibir entradas como: * "Pix recebido de John Doe" * "Compra com 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 ao criar a transação, o extrato continua funcionando, mas só consegue exibir os dados contábeis retornados pela operação. O Midaz mantém o ledger consistente e auditável. O contexto de negócio pertence aos metadados da transação, adicionados pelo sistema integrador.