> ## 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. # Genera un estado de cuenta > Convierte las operaciones de cuenta de Midaz en un estado de cuenta claro para el cliente filtrando por fecha, dirección y ruta con el endpoint Listar operaciones por 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. Flujo de saldo de cuenta Usa el endpoint [Listar operaciones por cuenta](/es/reference/products/midaz/v2/get-all-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 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: ```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 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. ### Recomendado para estados de cuenta fáciles de entender | 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` | Midaz devuelve el movimiento del ledger. Se recomienda que el sistema integrador agregue contexto de negocio en el `metadata` de cada entrada relevante de `source.from[]` y `distribute.to[]` cuando crea la transacción. Los metadatos no se propagan de las entradas de origen a las entradas de destino. Ejemplo de transformación: ```json theme={null} { "date": "2026-05-18T14:23:11Z", "description": "Pix transfer received", "type": "CREDIT", "direction": "credit", "amount": "150.00", "asset": "BRL", "balanceAfter": "1240.55", "transactionId": "txn_987654", "metadata": { "counterparty": "John Doe", "pixKey": "john@example.com", "category": "Transfer" } } ``` ### 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. 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} 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: ```json theme={null} "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.