> ## 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. # 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. 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. Flujo del saldo de la cuenta Usa el endpoint [Listar Operaciones por Cuenta](/es/reference/midaz/list-operations-by-account) para listar las operaciones de una cuenta específica: ```json theme={null} GET /v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/operations ``` 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: ```json theme={null} 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 ``` 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. ### 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 `metadata` cuando se crea la transacción. Ejemplo de transformación: ```json theme={null} { "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": "john@example.com", "category": "Transferencia" } } ``` ### 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: ```json theme={null} "balanceAffected": true ``` Esto mantiene el extracto enfocado en los movimientos que cambiaron el saldo disponible. Las respuestas pueden estar paginadas según el `limit` seleccionado. Para recuperar todas las operaciones: 1. Lee el campo `next_cursor` de la respuesta 2. Envíalo en la siguiente solicitud usando el parámetro `cursor` 3. Repite hasta que `next_cursor` ya no se devuelva Ejemplo de flujo: ```text theme={null} 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: ```json theme={null} "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.