Construir un extracto de cuenta

Usa las operaciones de cuenta para construir una vista de extracto clara a partir de los movimientos del ledger de Midaz, con saldos y filtros por período.

Esta guía explica cómo transformar las operaciones de cuenta de Midaz en extractos de cuenta para el usuario final.

Construyes un extracto 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 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. Luego transforma cada operación en una fila que los usuarios puedan entender.

Flujo del saldo de la cuenta

1. 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
   
2. Aplicar filtros de consulta

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

   ​

   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

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

   ​

   Requerido para paginación

   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

   El endpoint puede devolver los siguientes tipos 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
   BLOCK	Movimiento complementario de bloqueo de cuenta generado por el sistema
   UNBLOCK	Movimiento complementario de desbloqueo de cuenta generado por el sistema

   Usa type para clasificar el movimiento contable. Usa direction para decidir si el extracto muestra el importe 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
   
3. Transformar las operaciones en entradas del extracto

   Cada objeto 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

   Necesitas estos campos para renderizar una fila útil del extracto. La API no requiere todos ellos. Un extracto sin ellos pierde significado, trazabilidad o contexto del saldo.

   ​

   Recomendado para extractos amigables al usuario

   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

   Midaz devuelve el movimiento del ledger. El sistema integrador debe añadir el contexto de negocio en el metadata de cada entrada source.from[] y distribute.to[] relevante cuando crea la transacción; el metadata no se propaga de las entradas de origen a las de destino.

   Ejemplo de transformación:

   {
     "date": "2026-05-18T14:23:11Z",
     "description": "Transferencia Pix recibida",
     "type": "CREDIT",
     "direction": "credit",
     "amount": "150.00",
     "asset": "BRL",
     "balanceAfter": "1240.55",
     "transactionId": "txn_987654",
     "metadata": {
       "counterparty": "John Doe",
       "pixKey": "[e-mail]",
       "category": "Transferencia"
     }
   }
   
4. 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

   No muestres las operaciones con los siguientes tipos 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

   ​

   Define una política de operaciones liquidadas

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

5. Manejar la paginación

   El endpoint divide las respuestas en páginas según el valor de limit.

   Para recuperar todas las operaciones:

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

   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 ya no se devuelva
   

​

Ejemplo de salida del extracto

Después de que apliques los filtros, transformes las operaciones y apliques 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 los metadatos de cada operación cuando creas la transacción. Midaz almacena esos campos con esa operación. 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:

"send": {
  "source": {
    "from": [{
      "accountAlias": "customer_123",
      "metadata": {
        "counterparty": "John Doe",
        "document": "12345678900",
        "pixKey": "[e-mail]",
        "endToEndId": "E1234567890123456789012345678901",
        "channel": "Pix",
        "category": "Transferencia"
      }
    }]
  }
}

Esto te 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, el extracto sigue funcionando. Entonces solo puede mostrar los datos contables que la operación devuelve.

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