Construir um extrato de conta

Este guia explica como transformar as operações de conta do Midaz em extratos de conta para o usuário final. Você constrói um extrato de conta a partir das operações de conta do Midaz. Cada operação é uma movimentação do ledger que se vincula 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. Depois transforme cada operação em uma linha que os usuários consigam entender.

Recuperar as operações de conta

Use o endpoint Listar Operações por Conta para listar as operações de uma conta específica:

GET /v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/operations

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ó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

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

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 bloqueado
`RELEASE`	Valor anteriormente bloqueado liberado
`OVERDRAFT`	Movimentação relacionada ao uso de cheque especial
`BLOCK`	Movimentação complementar de bloqueio de conta gerada pelo sistema
`UNBLOCK`	Movimentação complementar 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:

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

Transformar as operações em entradas 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`
Recibo ou referência da transação	`transactionId`

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

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`

Aplicar regras de exibição do extrato

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

Não exiba as operações com os seguintes tipos 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

Defina uma política de Operations liquidadas

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

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:

Leia o campo next_cursor da resposta
Envie-o como o parâmetro cursor na próxima requisição
Repita até que a resposta não retorne mais next_cursor

Exemplo de fluxo:

Requisição 1
  -> retorna items + next_cursor

Requisição 2
  -> cursor=next_cursor
  -> retorna mais items + next_cursor

Repetir até next_cursor não ser mais retornado

Exemplo de saída do extrato

Depois de você 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 em cada entrada source.from[] e distribute.to[] quando você cria a transação. O Midaz armazena esses campos na Operation correspondente. 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:

"send": {
  "source": {
    "from": [{
      "accountAlias": "customer_123",
      "metadata": {
        "counterparty": "John Doe",
        "document": "12345678900",
        "pixKey": "john@example.com",
        "endToEndId": "E1234567890123456789012345678901",
        "channel": "Pix",
        "category": "Transferência"
      }
    }]
  }
}

Isso permite que você exiba 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, o extrato continua funcionando. Então ele só consegue exibir os dados contábeis que a operação retorna.

O Midaz mantém o ledger consistente e auditável. O sistema integrador adiciona o contexto de negócio aos metadados de cada Operation.

Midaz Core

CRM

Fees

Construir um extrato de conta

Recuperar as operações de conta

Aplicar filtros de consulta

Obrigatórios para consultas de extrato

Obrigatório para paginação

Filtros opcionais

Transformar as operações em entradas do extrato

Obrigatório para renderizar o extrato

Recomendado para extratos amigáveis ao usuário

Aplicar regras de exibição do extrato

Use `direction` para determinar o sinal

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

Defina uma política de Operations liquidadas

Tratar a paginação

Exemplo de saída do extrato

Adicionar contexto de negócio

Recuperar as operações de conta

Aplicar filtros de consulta

​Obrigatórios para consultas de extrato

​Obrigatório para paginação

​Filtros opcionais

Transformar as operações em entradas do extrato

​Obrigatório para renderizar o extrato

​Recomendado para extratos amigáveis ao usuário

Aplicar regras de exibição do extrato

​Use direction para determinar o sinal

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

​Defina uma política de Operations liquidadas

Tratar a paginação

​Exemplo de saída do extrato

​Adicionar contexto de negócio

Obrigatórios para consultas de extrato

Obrigatório para paginação

Filtros opcionais

Obrigatório para renderizar o extrato

Recomendado para extratos amigáveis ao usuário

Use `direction` para determinar o sinal

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

Defina uma política de Operations liquidadas

Exemplo de saída do extrato

Adicionar contexto de negócio