> ## 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 que una cuenta específica mantiene en Midaz. Refleja el resultado de todas las operaciones — débitos y créditos — a lo largo del tiempo. Cada saldo pertenece a un activo, como BRL, USD o BTC. ## Múltiples saldos *** Una única cuenta puede mantener varios saldos. Una clave única identifica a cada uno. 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 mantiene exactamente un saldo.** Los casos de uso típicos incluyen: * Reservas de inversión * Límites de crédito * Fondos de garantía (bloqueados) * Fondos operativos del día a día Este enfoque (*Figura 1*) aumenta la flexibilidad. Mantiene intacto el modelo de doble entrada — débito y crédito — para la consistencia contable, la trazabilidad y la transparencia. Cuenta con múltiples saldos Si una transacción no proporciona una `balanceKey`, Midaz utiliza el saldo por defecto de la cuenta. ### Balance key Un campo `key` identifica de forma única a cada saldo dentro de la cuenta. * **Longitud máxima**: 100 caracteres, sin espacios en blanco. * **Clave por defecto**: `"default"`. Midaz crea el saldo por defecto automáticamente cuando se crea la cuenta. * **Unicidad**: Cada clave debe ser única por cuenta. Una solicitud para crear un saldo con una clave que ya existe en la cuenta devuelve un error. * **En transacciones**: Si una transacción no especifica una `balanceKey`, Midaz utiliza el saldo con la clave `"default"`. Defines la `key` en el momento de la creación y no puedes cambiarla después. 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 flags son **por saldo** — se aplican a un saldo, no a la cuenta en su conjunto. Ambos tienen el valor `true` por defecto cuando no los defines. **Casos de uso comunes:** * **Congelar un saldo**: Establece `allowSending` y `allowReceiving` en `false` para impedir cualquier movimiento. * **Saldo solo para recepción**: Establece `allowSending` en `false` para bloquear transferencias salientes y seguir aceptando entradas. * **Saldo solo para envío**: Establece `allowReceiving` en `false` para impedir que nuevos fondos entren en este saldo. Puedes establecer ambos flags cuando creas un saldo. También puedes actualizarlos de forma independiente mediante el endpoint [Actualizar un Saldo](/es/reference/midaz/update-a-balance). Si una solicitud de actualización omite un flag, su valor actual se mantiene sin cambios. Midaz lee los permission flags durante la validación de la transacción. Un PATCH que cambia solo `allowSending` o `allowReceiving` no reescribe una entrada existente de Valkey, por lo que no se debe asumir que la siguiente transacción con caché observará el cambio. Los cambios nunca alteran operaciones ya procesadas. ## Ejemplos de uso *** * **Billetera de Usuario (BRL)**: Una billetera digital que muestra un saldo disponible de R\$500. * *Caso de uso*: Muestra el saldo en una aplicación de banca móvil y valida los fondos antes de un pago. * **Cuenta de Liquidación (USD)**: Una cuenta de proveedor de liquidez con un saldo en USD de \$120,000. * *Caso de uso*: Asegúrate de 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. * *Caso de uso*: Impide el uso de los fondos hasta que un préstamo se cierre o el prestatario cumpla las condiciones. Un saldo bloqueado (de garantía) restringe fondos a **nivel de saldo**. Midaz mantiene el valor en un saldo separado y lo combina con los permission flags para mantener los fondos no disponibles. 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`. Una transacción de bloqueo marca 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 mantiene y mueve valor. * **Saldo > Activo**: Cada Saldo utiliza un Activo específico, como BRL o BTC. * **Saldo > *Ledger***: Los Saldos existen dentro de un *Ledger*, lo que permite entornos de múltiples libros. * **Saldo > Clave**: Cada Saldo tiene una clave única dentro de la cuenta (p. ej., `default`, `credit`, `collateral`). La *Figura 2* muestra un ejemplo de la estructura. Relaciones de la estructura de saldos 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**: Midaz actualiza los saldos con cada operación confirmada. * **Múltiples saldos por cuenta**: Las cuentas pueden mantener 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**: Puedes listar saldos dentro de una organización y un Ledger, recuperarlos por ID o alias de cuenta y recuperar el saldo de una Cuenta Externa por código de activo. Los endpoints de listado de saldos no filtran por un código de activo genérico ni por `balanceKey`. * **Compatible con cuentas externas**: Puedes recuperar saldos para cuentas internas o externas, como *liquidity pools* o socios. ## Uso de saldos en transacciones *** Los siguientes *endpoints* de transacción aceptan un campo `balanceKey` 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 una solicitud no proporciona una `balanceKey`, Midaz utiliza el saldo por defecto de la cuenta. ### Nuevos campos en las respuestas * `balanceKey` - Aparece en transacciones y operaciones para mostrar qué saldo utilizó la transacción. * `key` - Aparece en los saldos para identificar cada saldo de forma única. Utiliza siempre la `balanceKey` de forma coherente en las solicitudes y respuestas. Esto evita desajustes cuando las cuentas mantienen múltiples saldos. ## Cambios en la clave de caché (Valkey) *** Los saldos en la caché (Valkey) incluyen la `balanceKey`. ### Formato anterior ```json theme={null} :: ``` ### Nuevo formato ```json theme={null} balance:{transactions}:::# ``` La clave lleva el prefijo `balance:{transactions}:`, y la `balance_key` se añade al alias de la cuenta con un separador `#`. Un espacio de nombres de tenant puede prefijar la clave adicionalmente en despliegues multi-tenant. Actualiza los lectores directos de Valkey para construir `balance:{transactions}:::#`, incluido `#default` para el saldo por defecto. Las lecturas que usan el formato de clave anterior no encuentran la entrada actual de caché. ## Overdraft *** Los saldos soportan **overdraft** — la capacidad de debitar un saldo más allá de sus fondos disponibles. Cuando habilitas el overdraft, Midaz rastrea el déficit como `overdraftUsed`. Midaz también maneja el split de la operación y el reembolso automáticamente. Dos campos soportan esta funcionalidad: * **`direction`** — Para un saldo por defecto creado automáticamente, la dirección es `credit` para cuentas no externas y `debit` para Cuentas Externas. Los saldos adicionales pueden definir la dirección en la creación; no puede cambiar después. * **`settings`** — Controla el comportamiento de overdraft: `allowOverdraft`, `overdraftLimitEnabled` y `overdraftLimit`. Midaz **reserva** la clave `"overdraft"` para el saldo companion gestionado por el sistema que registra el lado del pasivo. Una solicitud para crear un saldo con esta clave devuelve un error. `settings.balanceScope` también distingue los saldos por alcance. Los saldos **transactional** (el valor por defecto) son gestionados por el usuario y participan en transacciones regulares. El sistema opera los saldos **internal** de forma exclusiva — como el companion de overdraft. Las transacciones de usuario no pueden tener como objetivo, modificar ni eliminar estos saldos a través de la API pública. Para obtener 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. Puedes recuperar el estado de un saldo en una marca de tiempo pasada igual o posterior a su creación. Si no existe ninguna operación anterior a esa marca, Midaz devuelve el estado inicial en cero; devuelve `404` cuando la marca solicitada es anterior a la creación del saldo. Esto sirve para auditoría, conciliación e informes históricos. ### Cómo funciona El endpoint de historial devuelve campos históricos de identidad e importes. Omite `allowSending`, `allowReceiving`, `deletedAt` y `metadata`; la implementación actual tampoco reconstruye `direction` ni `settings` históricos y devuelve `overdraftUsed` como cero. No lo describas como una respuesta completa de saldo regular menos los permission flags. **¿Por qué el historial excluye los permission flags?** `allowSending` y `allowReceiving` son configuraciones operacionales mutables. Puedes cambiarlas en cualquier momento sin una entrada en el ledger. Los importes del saldo (`available`, `onHold`) cambian solo a partir 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 ocupan de los **importes** en un momento determinado. Si el envío o la recepción funcionaban en un instante dado no importa para la auditoría o la conciliación. El estado mutable de permisos en instantáneas inmutables añadirí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 las posiciones de saldo al cierre del mercado para operaciones de tesorería. El parámetro `date` es obligatorio. Debe seguir el formato `yyyy-mm-dd hh:mm:ss` (p. ej., `2026-01-15 10:30:00`). Midaz devuelve `404` cuando la marca solicitada es anterior a la creación del saldo. ### 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) - Obtén 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) - Obtén el estado de todos los saldos de una cuenta en un momento determinado. ## Gestión de Saldos *** Puedes recuperar tus saldos a través de la API. El motor del Ledger de Midaz calcula los importes de saldo a partir de las transacciones — no puedes establecer `available` u `onHold` directamente. Gestionas los registros de saldo — clave, permission flags y settings — a través de los endpoints siguientes. * [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 con 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) - Actualiza los permission flags y los settings de un saldo. * [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 afectó 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.