Monte um extrato de conta

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.

Recuperar operações de conta

Use o endpoint List Operations by Account 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ó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:

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

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`

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

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.

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 na resposta
Envie-o como o parâmetro cursor na próxima requisição
Repita até a resposta deixar de retornar next_cursor

Exemplo de fluxo:

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:

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

Midaz Core

CRM

Fees

Monte um extrato de conta

Recuperar operações de conta

Aplicar filtros de consulta

Obrigatório para consultas de extrato

Obrigatório para paginação

Filtros opcionais

Transformar operações em lançamentos 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 operações de retenção e liberação separadamente

Defina uma política de operação liquidada

Tratar a paginação

Exemplo de saída do extrato

Adicione contexto de negócio

Recuperar operações de conta

Aplicar filtros de consulta

​Obrigatório para consultas de extrato

​Obrigatório para paginação

​Filtros opcionais

Transformar operações em lançamentos 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 operações de retenção e liberação separadamente

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

Tratar a paginação

​Exemplo de saída do extrato

​Adicione contexto de negócio

Obrigatório 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 operações de retenção e liberação separadamente

Defina uma política de operação liquidada

Exemplo de saída do extrato

Adicione contexto de negócio