> ## 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. # Saldos > Rastrea múltiples Saldos por Cuenta para segmentar fondos — reservas, límites de crédito y fondos operativos sin Cuentas adicionales. Un **Saldo** representa el valor poseído por una cuenta específica en Midaz. Refleja el resultado de todas las operaciones (débitos y créditos) ejecutadas a lo largo del tiempo, y siempre está vinculado a un **Activo** específico, como BRL, USD o BTC. ## Múltiples saldos *** Una única cuenta puede poseer varios saldos, cada uno identificado por una clave única. Esto permite a las instituciones **segmentar fondos** sin crear múltiples cuentas para el mismo cliente. Las cuentas externas no pueden tener múltiples saldos. **Cada cuenta externa está limitada a un único saldo.** Los casos de uso típicos incluyen: * Reservas de inversión * Límites de crédito * Fondos de garantía (*collateral*) (bloqueados) * Fondos operativos del día a día Este enfoque (*Figura 1*) aumenta la flexibilidad mientras mantiene intacto el modelo de doble entrada (débito y crédito), asegurando la consistencia contable, la trazabilidad y la transparencia. Account Multiple Balances Jp Si no se proporciona ninguna `balanceKey` en una transacción, Midaz utiliza automáticamente el saldo por defecto de la cuenta. ### Balance key Cada saldo está identificado por un campo `key` que lo identifica de forma única dentro de la cuenta. * **Longitud máxima**: 100 caracteres — no se permiten espacios en blanco. * **Clave por defecto**: `"default"` — asignada automáticamente cuando una cuenta se utiliza por primera vez en una transacción. * **Unicidad**: Las claves deben ser únicas por cuenta. Intentar crear un saldo con una clave que ya existe en la misma cuenta devuelve un error. * **En transacciones**: Si no se especifica ningún `balanceKey` en una transacción, Midaz utiliza automáticamente el saldo con clave `"default"`. El campo `key` se define en el momento de la creación y no puede modificarse. Elige claves descriptivas como `"credit"`, `"collateral"` o `"savings"` para que tu modelo de saldos sea autodocumentado. ### Permission flags Cada saldo tiene dos `permission flags` independientes que controlan si puede participar en transacciones: | Flag | Tipo | Descripción | | ---------------- | ------- | ----------------------------------------------- | | `allowSending` | boolean | Si se pueden enviar fondos **desde** este saldo | | `allowReceiving` | boolean | Si se pueden recibir fondos **en** este saldo | Estos son flags **por saldo** — se aplican a un saldo específico, no a la cuenta en su conjunto. Ambos tienen valor por defecto `true` cuando no se especifican. **Casos de uso comunes:** * **Congelar un saldo**: Establece `allowSending` y `allowReceiving` en `false` para bloquear cualquier movimiento. * **Saldo solo para recepción**: Establece `allowSending` en `false` para bloquear transferencias salientes mientras sigue aceptando entradas. * **Saldo solo para envío**: Establece `allowReceiving` en `false` para impedir que nuevos fondos entren en este saldo. Ambos flags pueden establecerse al crear un saldo y actualizarse de forma independiente mediante el endpoint [Actualizar un Saldo](/es/reference/midaz/update-a-balance). Omitir un flag en una solicitud de actualización deja su valor actual sin cambios. Los `permission flags` se evalúan en el momento de la transacción. Cambiar un flag afecta solo a las **transacciones futuras** — no tiene efecto sobre las operaciones ya procesadas. ## Ejemplos de uso *** * **Billetera de Usuario (BRL)**: Una billetera digital que muestra un saldo disponible de R\$500. * *Caso de uso*: Mostrar saldo en una aplicación de banca móvil y validar fondos antes de autorizar un pago. * **Cuenta de Liquidación (USD)**: Una cuenta de proveedor de liquidez con un saldo en USD de \$120,000. * *Caso de uso*: Asegurar que las operaciones diarias de tesorería mantengan suficiente margen para las liquidaciones FX. * **Saldo Bloqueado (BRL)**: Un saldo de cuenta reservado como garantía (*collateral*). * *Caso de uso*: Prevenir el uso de fondos hasta que se cierre un préstamo o se cumplan las condiciones. Un saldo bloqueado (de garantía) restringe fondos a **nivel de saldo** — el valor se mantiene en un saldo separado y, combinado con las `permission flags`, se impide que se gaste. Esto es diferente de una [transacción de bloqueo](/es/midaz/transactions#bloqueo-y-desbloqueo-de-fondos), que registra un movimiento en el ledger con operaciones del tipo `BLOCK` para marcar fondos por motivos como una retención por cumplimiento. Usa un saldo de garantía para una restricción operacional permanente; usa una transacción de bloqueo cuando necesites una entrada auditable en el ledger. ## Estructura del Saldo *** * **Saldo > Cuenta**: Cada Saldo pertenece a una Cuenta, que posee y mueve valor. * **Saldo > Activo**: Cada Saldo está asociado a un Activo específico, como BRL o BTC. * **Saldo > *Ledger***: Los Saldos existen dentro de un *Ledger*, permitiendo entornos de múltiples libros. * **Saldo > Clave**: Cada Saldo tiene una clave única dentro de la cuenta (p. ej., `default`, `credit`, `collateral`). En la *Figura 2*, puedes encontrar un ejemplo de la estructura. Balance Structure Relationships Jp Un saldo es más que solo un número. Incluye metadatos sobre el estado de los fondos, como operaciones pendientes y disponibilidad efectiva. ## Características clave *** * **Seguimiento en tiempo real**: Los saldos se actualizan con cada operación confirmada. * **Múltiples saldos por cuenta**: Las cuentas pueden poseer varios saldos, cada uno con sus propias reglas. * **Fuente única de verdad**: Los saldos reflejan la suma neta de todas las operaciones en la cuenta. * **Consulta por contexto**: Los saldos se pueden listar por organización, *Ledger*, activo, cuenta o clave de saldo. * **Compatible con cuentas externas**: Los saldos se pueden recuperar para cuentas internas o externas, incluyendo *liquidity pools* o socios. ## Uso de saldos en transacciones *** El campo `balanceKey` se ha añadido a los siguientes *endpoints* de transacción para especificar qué saldo usar: * [Crear una Transacción usando JSON](/es/reference/midaz/create-a-transaction-using-json) * [Crear una Transacción de Entrada (*Inflow*)](/es/reference/midaz/create-an-inflow-transaction) * [Crear una Transacción de Salida (*Outflow*)](/es/reference/midaz/create-an-outflow-transaction) * [Crear una Anotación de Transacción](/es/reference/midaz/create-a-transaction-annotation) Si no se proporciona ninguna `balanceKey`, el sistema utiliza por defecto el saldo principal de la cuenta. ### Nuevos campos en las respuestas * `balanceKey` - Se devuelve en Transacciones y Operaciones, indicando qué saldo se utilizó. * `key` - Se devuelve en Saldos, identificando de forma única cada saldo. Utiliza siempre la `balanceKey` de forma coherente en las solicitudes y respuestas para evitar desajustes cuando las cuentas poseen múltiples saldos. ## Cambios en la clave de caché (Valkey) *** Los saldos almacenados en la caché (Valkey) incluyen la `balanceKey`. ### Formato anterior ```json theme={null} :: ``` ### Nuevo formato ```json theme={null} ::: ``` Cualquier integración que lea saldos directamente desde Valkey debe actualizarse para incluir la `balanceKey`. De lo contrario, solo estará disponible el saldo por defecto. ## Overdraft *** Los saldos soportan **overdraft** — la capacidad de ser debitados más allá de los fondos disponibles. Cuando el overdraft está habilitado, el déficit se rastrea como `OverdraftUsed` y Midaz maneja automáticamente el split de la operación y el reembolso. Dos campos soportan esta funcionalidad: * **`direction`** — Define si un saldo se comporta como activo (`credit`, por defecto) o pasivo (`debit`). Se define en la creación, inmutable. * **`settings`** — Controla el comportamiento de overdraft: `allowOverdraft`, `overdraftLimitEnabled` y `overdraftLimit`. La clave `"overdraft"` está **reservada** para el saldo companion gestionado por el sistema que registra el lado del pasivo. Intentar crear un saldo con esta clave devuelve un error. Los saldos también se distinguen por alcance vía `settings.balanceScope`. Los saldos **transactional** (por defecto) son gestionados por el usuario y participan en transacciones regulares. Los saldos **internal** son operados exclusivamente por el sistema — como el companion de overdraft — y no pueden ser objetivo de transacciones de usuario, ni modificados o eliminados a través de la API pública. Para detalles completos sobre modos de configuración, splits de operación, reembolso automático, eventos y casos de uso, ve [Overdraft de Saldo](/es/midaz/balance-overdraft). ## Historial de saldo *** Midaz proporciona **consultas point-in-time** para saldos, lo que te permite recuperar el estado exacto de un saldo en cualquier momento del pasado. Esto es esencial para auditoría, conciliación e informes históricos. ### Cómo funciona Cuando consultas el historial de saldo, Midaz reconstruye el estado del saldo tal como existía en la fecha y hora especificadas. La respuesta incluye todos los mismos campos que un saldo regular — excepto `allowSending` y `allowReceiving`. Estos campos reflejan permisos operacionales actuales en lugar del estado histórico, por lo que no se incluyen en las instantáneas point-in-time. **¿Por qué se excluyen los `permission flags` del historial?** `allowSending` y `allowReceiving` son configuraciones operacionales mutables — pueden modificarse en cualquier momento sin crear una entrada en el ledger. A diferencia de los importes del saldo (`available`, `onHold`), que cambian solo como resultado de transacciones registradas, los `permission flags` representan el estado operacional *actual* de un saldo, no un hecho sobre su pasado. Las auditorías y conciliaciones históricas se preocupan por los **importes** en un momento determinado. Si el envío o la recepción estaban habilitados en un instante dado no es relevante para fines de auditoría o conciliación, e incluir el estado mutable de permisos en instantáneas inmutables introduciría ambigüedad sin ningún valor. ### Casos de uso * **Auditoría regulatoria**: Demuestra el saldo exacto de una cuenta en un punto de control de cumplimiento específico. * **Conciliación**: Compara instantáneas de saldos entre sistemas en marcas de tiempo coincidentes. * **Resolución de disputas**: Recupera el estado preciso de la cuenta en el momento de una transacción disputada. * **Informes de fin de día**: Captura posiciones de saldo al cierre del mercado para operaciones de tesorería. El parámetro `date` es obligatorio y debe seguir el formato `yyyy-mm-dd hh:mm:ss` (p. ej., `2026-01-15 10:30:00`). Si no existen datos de saldo para la marca de tiempo especificada, se devuelve un error `404`. ### Consultar historial de saldo Puedes consultar el historial de un saldo individual o de todos los saldos de una cuenta: * [Recuperar historial de saldo](/es/reference/midaz/retrieve-balance-history) - Obtener el estado de un saldo específico en un momento determinado. * [Recuperar historial de saldo por cuenta](/es/reference/midaz/retrieve-balance-history-by-account) - Obtener el estado de todos los saldos de una cuenta en un momento determinado. ## Gestión de Saldos *** Puedes recuperar tus Saldos utilizando la API. Los saldos son de **solo lectura** y son gestionados automáticamente por el motor del Ledger de Midaz. * [Crear un Saldo](/es/reference/midaz/create-a-balance) - Crea un nuevo saldo para una cuenta definiendo una clave única. * [Listar Saldos](/es/reference/midaz/list-balances) - Recupera todos los saldos por organización y *Ledger*. * [Recuperar un Saldo](/es/reference/midaz/retrieve-a-balance) - Obtén el saldo de una cuenta específica por su ID único. * [Recuperar Saldos por Cuenta](/es/reference/midaz/retrieve-balances-by-account) - Obtén el saldo de una cuenta específica. * [Recuperar un Saldo por Alias de Cuenta](/es/reference/midaz/retrieve-a-balance-by-account-alias) - Obtén el saldo utilizando un alias de cuenta legible por humanos (p. ej., @user123). * [Recuperar un Saldo de una Cuenta Externa](/es/reference/midaz/retrieve-a-balance-of-an-external-account) - Recupera el saldo de una cuenta externa (p. ej., `@external/BRL`). * [Actualizar un Saldo](/es/reference/midaz/update-a-balance) - Ajusta manualmente un saldo para fines operativos o de prueba. * [Eliminar un Saldo](/es/reference/midaz/delete-a-balance) - Elimina una entrada de saldo del sistema. ¿Quieres rastrear **cómo** se formó un saldo? Utiliza la API de Operaciones para inspeccionar el historial del *Ledger* que impactó a esa cuenta. ## Próximos pasos *** * Utiliza la [API de Operaciones](/es/midaz/operations) para rastrear transacciones que involucren múltiples saldos. * Combina múltiples saldos con [Rutas Contables](/es/midaz/transaction-routing-entities) para crear flujos financieros flexibles y escalables.