Genera un estado de cuenta

Generas un estado de cuenta a partir de las operaciones de cuenta de Midaz. Cada operación es un movimiento del ledger que se vincula a una cuenta, como un evento de crédito, débito, retención, liberación o sobregiro. Para generar un estado de cuenta, recupera las operaciones de cuenta del período. Conserva las operaciones que afectan la vista del estado de cuenta. Luego, transforma cada operación en una fila que los usuarios puedan entender.

Recupera 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

Aplica filtros de consulta

Usa los parámetros de consulta para definir el período del estado de cuenta, controlar la paginación y filtrar las operaciones que devuelve el endpoint.

Obligatorio para las consultas del estado de cuenta

Parámetro	Descripción
`start_date`	Fecha de inicio del período del estado de cuenta
`end_date`	Fecha de fin del período del estado de cuenta
`limit`	Número de elementos por página
`sort_order=desc`	Devuelve las operaciones más recientes primero

Necesitas estos campos para este caso de uso de estado de cuenta. Definen la ventana del estado de cuenta y hacen que el resultado sea predecible para los usuarios.

Obligatorio para la paginación

Parámetro	Descripción
`cursor`	Cursor que devuelve la respuesta anterior

Filtros opcionales

Parámetro	Descripción
`direction=credit`	Devuelve solo las operaciones entrantes
`direction=debit`	Devuelve solo las operaciones salientes
`type`	Filtra por tipo de operación
`route_id`	Filtra por el ID de la ruta de operación (UUID)
`route_code`	Filtra por el código de la ruta de operación

El endpoint puede devolver los siguientes tipos de operación:

Tipo	Qué significa
`CREDIT`	Valor que entra a la cuenta
`DEBIT`	Valor que sale de la cuenta
`ON_HOLD`	Monto retenido temporalmente
`RELEASE`	Libera un monto previamente retenido
`OVERDRAFT`	Movimiento relacionado con el uso del sobregiro
`BLOCK`	Fila complementaria generada por el sistema para el bloqueo de la cuenta
`UNBLOCK`	Fila complementaria generada por el sistema para el desbloqueo de la cuenta

Usa type para clasificar el movimiento contable. Usa direction para decidir si el estado de cuenta muestra el monto como positivo o negativo.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

Transforma las operaciones en entradas del estado de cuenta

Cada objeto del array items puede convertirse en una fila del estado de cuenta.

Obligatorio para representar el estado de cuenta

Campo del estado de cuenta	Campo de la operación
Fecha	`createdAt`
Descripción	`description`
Tipo de movimiento	`type`
Dirección	`direction`
Monto	`amount.value`
Divisa o activo	`assetCode`
Saldo después de la operación	`balanceAfter.available`
Comprobante o referencia de la transacción	`transactionId`

Necesitas estos campos para representar una fila útil del estado de cuenta. La API no exige todos ellos. Un estado de cuenta sin ellos pierde significado, trazabilidad o contexto de saldo.

Contexto del estado de cuenta	Campo de la operación
Contraparte	`metadata.counterparty`
Documento	`metadata.document`
Clave Pix	`metadata.pixKey`
ID de extremo a extremo	`metadata.endToEndId`
Canal	`metadata.channel`
Categoría	`metadata.category`

Aplica las reglas de visualización del estado de cuenta

Usa `direction` para determinar el signo

Dirección	Comportamiento de visualización
`credit`	Se muestra como un monto positivo
`debit`	Se muestra como un monto 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.

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

No muestres las operaciones con los siguientes tipos como movimientos liquidados normales:

ON_HOLD
RELEASE

En su lugar:

Se recomienda que ON_HOLD aparezca como una retención de saldo o un bloqueo temporal
Se recomienda que RELEASE aparezca como una liberación de saldo o un desbloqueo

Define una política de operaciones liquidadas

No uses balanceAffected como predicado de operación liquidada. Una operación ON_HOLD normal puede establecer balanceAffected en true sin cambiar el saldo disponible. Define explícitamente la política de tu estado de cuenta a partir del tipo y el estado de la operación, y muestra ON_HOLD y RELEASE según las reglas de retención y liberación anteriores.

Gestiona la paginación

El endpoint divide las respuestas en páginas según el valor de limit.Para recuperar todas las operaciones:

Lee el campo next_cursor de la respuesta
Envíalo como el parámetro cursor en la siguiente solicitud
Repite hasta que la respuesta ya no devuelva next_cursor

Ejemplo de flujo:

Request 1
  -> returns items + next_cursor

Request 2
  -> cursor=next_cursor
  -> returns more items + next_cursor

Repeat until next_cursor is no longer returned

Ejemplo de salida del estado de cuenta

Después de aplicar los filtros, transformar las operaciones y aplicar las reglas de visualización, el estado de cuenta final puede verse así:

Fecha	Descripción	Monto	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 estado de cuenta lista para usar. Devuelve eventos del ledger que el sistema integrador convierte en una experiencia de estado de cuenta.

Agrega contexto de negocio

El endpoint de operaciones devuelve eventos contables. Un estado de cuenta orientado al usuario necesita más contexto que el simple movimiento del ledger. Envía metadatos de negocio en los metadatos de cada operación cuando creas la transacción. Midaz almacena esos campos junto con esa operación. El estado de cuenta puede usarlos después para mostrar quién, qué y por qué hay detrás del movimiento.

counterparty
document
pixKey
endToEndId
channel
category

Ejemplo de metadatos:

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

Esto permite mostrar entradas como:

“Pix recibido de John Doe”
“Compra con tarjeta en Coffee Shop”
“Transferencia a la cuenta de ahorros”

en lugar de descripciones contables genéricas. Si el sistema integrador no envía estos campos, el estado de cuenta sigue funcionando. En ese caso, solo puede mostrar los datos contables que devuelve la operación.

Midaz mantiene el ledger coherente y auditable. El sistema integrador agrega contexto de negocio a los metadatos de cada operación.

Midaz Core

CRM

Fees

Genera un estado de cuenta

Recupera las operaciones de cuenta

Aplica filtros de consulta

Obligatorio para las consultas del estado de cuenta

Obligatorio para la paginación

Filtros opcionales

Transforma las operaciones en entradas del estado de cuenta

Obligatorio para representar el estado de cuenta

Recomendado para estados de cuenta fáciles de entender

Aplica las reglas de visualización del estado de cuenta

Usa `direction` para determinar el signo

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

Define una política de operaciones liquidadas

Gestiona la paginación

Ejemplo de salida del estado de cuenta

Agrega contexto de negocio

Recupera las operaciones de cuenta

Aplica filtros de consulta

​Obligatorio para las consultas del estado de cuenta

​Obligatorio para la paginación

​Filtros opcionales

Transforma las operaciones en entradas del estado de cuenta

​Obligatorio para representar el estado de cuenta

​Recomendado para estados de cuenta fáciles de entender

Aplica las reglas de visualización del estado de cuenta

​Usa direction para determinar el signo

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

​Define una política de operaciones liquidadas

Gestiona la paginación

​Ejemplo de salida del estado de cuenta

​Agrega contexto de negocio

Obligatorio para las consultas del estado de cuenta

Obligatorio para la paginación

Filtros opcionales

Obligatorio para representar el estado de cuenta

Recomendado para estados de cuenta fáciles de entender

Usa `direction` para determinar el signo

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

Define una política de operaciones liquidadas

Ejemplo de salida del estado de cuenta

Agrega contexto de negocio