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.
Esta guía explica cómo los integradores pueden transformar las operaciones de cuenta de Midaz en extractos de cuenta para el usuario final.
Un extracto de cuenta en Midaz se construye a partir de las operaciones de cuenta. Cada operación es un movimiento del ledger vinculado a una cuenta, como un crédito, débito, retención, liberación o evento de sobregiro.
Para construir un extracto, recupera las operaciones de cuenta del período, conserva las operaciones que afectan a la vista del extracto y transforma cada operación en una fila que los usuarios puedan entender.
Recuperar las operaciones de cuenta
Usa el endpoint Listar Operaciones por Cuenta para listar las operaciones de una cuenta específica:GET /v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/operations
Aplicar filtros de consulta
Usa parámetros de consulta para definir el período del extracto, controlar la paginación y filtrar las operaciones devueltas por el endpoint.| Parámetro | Descripción |
|---|
start_date | Fecha de inicio del período del extracto |
end_date | Fecha de fin del período del extracto |
limit | Número de elementos por página |
sort_order=desc | Devuelve primero las operaciones más recientes |
Requerido al paginar
| Parámetro | Descripción |
|---|
cursor | Cursor devuelto en la respuesta anterior |
Filtros opcionales
| Parámetro | Descripción |
|---|
direction=credit | Devuelve solo las operaciones de entrada |
direction=debit | Devuelve solo las operaciones de salida |
type | Filtra por tipo de operación |
| Tipo | Qué significa |
|---|
CREDIT | Valor que entra en la cuenta |
DEBIT | Valor que sale de la cuenta |
ON_HOLD | Importe bloqueado temporalmente |
RELEASE | Importe previamente bloqueado que se libera |
OVERDRAFT | Movimiento relacionado con el uso del sobregiro |
type para clasificar el movimiento contable. Usa direction para decidir si el importe se muestra como positivo o negativo en el extracto.Ejemplo de solicitud: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
Manejar la paginación
Las respuestas pueden estar paginadas según el limit seleccionado.Para recuperar todas las operaciones:
- Lee el campo
next_cursor de la respuesta
- Envíalo en la siguiente solicitud usando el parámetro
cursor
- Repite hasta que
next_cursor ya no se devuelva
Ejemplo de flujo:Solicitud 1
-> devuelve items + next_cursor
Solicitud 2
-> cursor=next_cursor
-> devuelve más items + next_cursor
Repetir hasta que next_cursor sea null
| Fecha | Descripción | Importe | Saldo después |
|---|
| 2026-05-18 | Pix recibido de John Doe | +150,00 BRL | 1.240,55 BRL |
| 2026-05-18 | Compra con tarjeta | -45,90 BRL | 1.194,65 BRL |
Añadir contexto de negocio
El endpoint de operaciones devuelve eventos contables. Un extracto orientado al usuario necesita más contexto que el solo movimiento del ledger.
Envía los metadatos de negocio en el payload de la transacción al crearla. Midaz almacena esos campos junto a la operación, y el extracto puede usarlos más tarde para mostrar quién, qué y por qué detrás del movimiento.
counterpartydocumentpixKeyendToEndIdchannelcategory
Ejemplo de metadatos:
"metadata": {
"counterparty": "John Doe",
"document": "12345678900",
"pixKey": "john@example.com",
"endToEndId": "E1234567890123456789012345678901",
"channel": "Pix",
"category": "Transferencia"
}
- “Pix recibido de John Doe”
- “Compra con tarjeta en Coffee Shop”
- “Transferencia a Cuenta de Ahorros”
en lugar de descripciones contables genéricas.
Si el sistema integrador no envía estos campos al crear la transacción, el extracto sigue funcionando, pero solo puede mostrar los datos contables devueltos por la operación.
Midaz mantiene el ledger consistente y auditable. El contexto de negocio pertenece a los metadatos de la transacción, añadidos por el sistema integrador.
