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.
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.
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 retornadas pelo endpoint.| 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 |
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 |
| 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 |
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: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
Tratar a paginação
As respostas podem ser paginadas dependendo do limit selecionado.Para recuperar todas as operações:
- Leia o campo
next_cursor da resposta
- Envie-o na próxima requisição usando o parâmetro
cursor
- Repita até que
next_cursor não seja mais retornado
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 ser null
| 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 |
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.
counterpartydocumentpixKeyendToEndIdchannelcategory
Exemplo de metadados:
"metadata": {
"counterparty": "John Doe",
"document": "12345678900",
"pixKey": "john@example.com",
"endToEndId": "E1234567890123456789012345678901",
"channel": "Pix",
"category": "Transferência"
}
- “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.
