> ## 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, 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 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 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: ```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 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: ```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 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. 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: ```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 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: ```json theme={null} "send": { "source": { "from": [{ "accountAlias": "customer_123", "metadata": { "counterparty": "John Doe", "document": "12345678900", "pixKey": "john@example.com", "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.