Construir un extracto de cuenta

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.

Requeridos para consultas de extracto

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

Estos campos son requeridos para este caso de uso de extracto. Definen la ventana del extracto y hacen que el resultado sea predecible para los usuarios.

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
`route_id`	Filtra por el ID (UUID) de la ruta de operación
`route_code`	Filtra por el código de la ruta de operación

Tipos de operación admitidos:

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

Usa 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

Transformar las operaciones en entradas del extracto

Cada objeto devuelto en el array items puede convertirse en una fila del extracto.

Requerido para renderizar el extracto

Campo del extracto	Campo de la operación
Fecha	`createdAt`
Descripción	`description`
Tipo de movimiento	`type`
Dirección	`direction`
Importe	`amount.value`
Moneda o activo	`assetCode`
Saldo después de la operación	`balanceAfter.available`
Recibo o referencia de la transacción	`transactionId`

Estos campos son requeridos para renderizar una fila útil del extracto. No todos son requeridos por la API, pero un extracto sin ellos pierde significado, trazabilidad o contexto del saldo.

Contexto del extracto	Campo de la operación
Contraparte	`metadata.counterparty`
Documento	`metadata.document`
Clave Pix	`metadata.pixKey`
ID end-to-end	`metadata.endToEndId`
Canal	`metadata.channel`
Categoría	`metadata.category`

Aplicar reglas de visualización del extracto

Usa `direction` para determinar el signo

Dirección	Comportamiento de visualización
`credit`	Mostrar como un importe positivo
`debit`	Mostrar como un importe negativo

No uses type para determinar si el valor es positivo o negativo. El campo type clasifica el movimiento contable, mientras que direction define si el valor entra o sale de la cuenta.

Trata las operaciones de retención y liberación por separado

Las operaciones con los siguientes tipos no deben mostrarse como movimientos liquidados regulares:

ON_HOLD
RELEASE

En su lugar:

ON_HOLD debe aparecer como una retención de saldo o bloqueo temporal
RELEASE debe aparecer como una liberación o desbloqueo de saldo

Muestra solo las operaciones liquidadas

Para una vista de extracto liquidado, incluye solo las operaciones donde:

"balanceAffected": true

Esto mantiene el extracto enfocado en los movimientos que cambiaron el saldo disponible.

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

Ejemplo de salida del extracto

Tras aplicar los filtros, transformar las operaciones y aplicar las reglas de visualización, el extracto final puede verse así:

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

La API no devuelve una página de extracto lista. Devuelve eventos del ledger que el sistema integrador convierte en una experiencia de extracto.

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.

counterparty
document
pixKey
endToEndId
channel
category

Ejemplo de metadatos:

"metadata": {
  "counterparty": "John Doe",
  "document": "12345678900",
  "pixKey": "john@example.com",
  "endToEndId": "E1234567890123456789012345678901",
  "channel": "Pix",
  "category": "Transferencia"
}

Esto permite mostrar entradas como:

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

Recuperar las operaciones de cuenta

Aplicar filtros de consulta

​Requeridos para consultas de extracto

​Requerido al paginar

​Filtros opcionales

Transformar las operaciones en entradas del extracto

​Requerido para renderizar el extracto

​Recomendado para extractos amigables al usuario

Aplicar reglas de visualización del extracto

​Usa direction para determinar el signo

​Trata las operaciones de retención y liberación por separado

​Muestra solo las operaciones liquidadas

Manejar la paginación

​Ejemplo de salida del extracto

​Añadir contexto de negocio

Requeridos para consultas de extracto

Requerido al paginar

Filtros opcionales

Requerido para renderizar el extracto

Recomendado para extractos amigables al usuario

Usa `direction` para determinar el signo

Trata las operaciones de retención y liberación por separado

Muestra solo las operaciones liquidadas

Ejemplo de salida del extracto

Añadir contexto de negocio