> ## 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 varios saldos por cuenta para segmentar fondos en reservas de inversión, límites de crédito y fondos operativos sin cuentas adicionales. Un **saldo** representa el valor que tiene una cuenta específica 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. ## Varios saldos *** Una sola cuenta puede tener varios saldos. Una clave única identifica cada uno. Esto permite que las instituciones segmenten fondos sin crear varias cuentas para el mismo cliente. Las cuentas externas no pueden tener varios saldos. **Cada cuenta externa tiene exactamente un saldo.** Los casos de uso típicos incluyen: * Reservas de inversión * Límites de crédito * Fondos de colateral (bloqueados) * Fondos operativos del día a día Este enfoque (*Figura 1*) aumenta la flexibilidad. Mantiene intacto el modelo de partida doble (débito y crédito) para la consistencia contable, la trazabilidad y la transparencia. Cuenta con varios saldos Si una transacción no incluye un `balanceKey`, Midaz usa el saldo predeterminado de la cuenta. ### Clave del saldo Un campo `key` identifica cada saldo de forma única dentro de la cuenta. * **Longitud máxima**: 100 caracteres, sin espacios en blanco. * **Clave predeterminada**: `"default"`. Midaz crea el saldo predeterminado de forma automática 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 las transacciones**: si una transacción no especifica un `balanceKey`, Midaz usa 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 se documente por sí mismo. ### Indicadores de permiso Cada saldo tiene dos indicadores de permiso independientes que controlan si puede participar en transacciones: | Indicador | Tipo | Descripción | | ---------------- | ------- | ------------------------------------------------ | | `allowSending` | boolean | Si se pueden enviar fondos **desde** este saldo | | `allowReceiving` | boolean | Si se pueden recibir fondos **hacia** este saldo | Estos indicadores son **por saldo**. Se aplican a un solo saldo, no a toda la cuenta. Ambos usan `true` de forma predeterminada cuando no los defines. **Casos de uso comunes:** * **Congelar un saldo**: define `allowSending` y `allowReceiving` como `false` para impedir cualquier movimiento. * **Saldo de solo recepción**: define `allowSending` como `false` para bloquear las transferencias salientes y seguir aceptando entradas. * **Saldo de solo envío**: define `allowReceiving` como `false` para impedir que nuevos fondos entren a este saldo. Puedes definir ambos indicadores cuando creas un saldo. También puedes actualizarlos de forma independiente mediante el endpoint [Actualizar un saldo](/es/reference/products/midaz/v2/update-balance). Si una solicitud de actualización omite un indicador, su valor actual se mantiene sin cambios. Midaz lee los indicadores de permiso durante la validación de transacciones. Un PATCH que cambia solo `allowSending` o `allowReceiving` no reescribe una entrada existente en Valkey, así que no asumas que la siguiente transacción con acierto de caché reflejará el cambio de inmediato. Los cambios nunca alteran 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*: muestra el saldo en una app 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*: asegura que las operaciones diarias de tesorería mantengan un margen suficiente para las liquidaciones de FX. * **Saldo bloqueado (BRL)**: un saldo de cuenta reservado como colateral. * *Caso de uso*: impide el uso de los fondos hasta que el préstamo se cierre o el prestatario cumpla las condiciones. Un saldo bloqueado (colateral) restringe los fondos **en el nivel del saldo**. Midaz mantiene el valor en un saldo separado y lo combina con indicadores de permiso para mantener los fondos no disponibles. Esto es distinto de una [transacción de Bloqueo](/es/products/midaz/transactions#blocking-and-unblocking-funds), que registra un movimiento en el ledger con operaciones de tipo `BLOCK`. Una transacción de Bloqueo marca fondos por motivos como una retención de cumplimiento. Usa un saldo de colateral para una restricción operativa permanente. Usa una transacción de Bloqueo cuando necesites un asiento auditable en el ledger. ## Estructura del saldo *** * **Saldo > Cuenta**: cada saldo pertenece a una cuenta, que contiene y mueve valor. * **Saldo > Activo**: cada saldo usa un activo específico, como BRL o BTC. * **Saldo > Ledger**: los saldos existen dentro de un Ledger, que permite entornos con varios libros. * **Saldo > Clave**: cada saldo tiene una clave única dentro de la cuenta (por ejemplo, `default`, `credit`, `collateral`). *Figura 2* muestra un ejemplo de la estructura. Relaciones de la estructura del saldo Un saldo 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. * **Varios saldos por cuenta**: las cuentas pueden tener varios saldos, cada uno con sus propias reglas. * **Fuente única de verdad**: los saldos reflejan la suma neta de todas las operaciones de la cuenta. * **Consulta por contexto**: puedes listar saldos dentro de una organización y un ledger, obtenerlos por ID de cuenta o alias, y obtener el saldo de una cuenta externa por código de activo. Los endpoints de lista de saldos no filtran por un código de activo genérico ni por `balanceKey`. * **Admite cuentas externas**: puedes obtener saldos de cuentas internas o externas, como pools de liquidez o socios. ## Uso de saldos en transacciones *** Los siguientes endpoints de transacciones aceptan un campo `balanceKey` para especificar qué saldo usar: * [Crear una transacción con JSON](/es/reference/products/midaz/v1/create-transaction-json) * [Crear una transacción de entrada](/es/reference/products/midaz/v1/create-transaction-inflow) * [Crear una transacción de salida](/es/reference/products/midaz/v1/create-transaction-outflow) * [Crear una anotación de transacción](/es/reference/products/midaz/v1/create-transaction-annotation) Si una solicitud no incluye un `balanceKey`, Midaz usa el saldo predeterminado de la cuenta. ### Campos nuevos en las respuestas * `balanceKey` - aparece en transacciones y operaciones para mostrar qué saldo usó la transacción. * `key` - aparece en los saldos para identificar cada saldo de forma única. Usa siempre el `balanceKey` de forma consistente en las solicitudes y las respuestas. Esto evita discrepancias cuando las cuentas tienen varios saldos. ## Cambios en la clave de caché (Valkey) *** Los saldos en la caché (Valkey) incluyen el `balanceKey`. ### Formato anterior ```json theme={null} :: ``` ### Formato nuevo ```json theme={null} balance:{transactions}:::# ``` La clave lleva el prefijo `balance:{transactions}:`, y el `balance_key` se agrega al alias de la cuenta con un separador `#`. Un espacio de nombres de tenant puede anteponerse a la clave en implementaciones multi-tenant. Actualiza los lectores directos de Valkey para construir `balance:{transactions}:::#`, incluido `#default` para el saldo predeterminado. Las lecturas que usan el formato de clave anterior no encuentran la entrada de caché actual. ## Sobregiro *** Los saldos admiten el **sobregiro**, la capacidad de debitar un saldo más allá de sus fondos disponibles. Cuando habilitas el sobregiro, Midaz registra el déficit como `overdraftUsed`. Midaz también gestiona de forma automática la división de la operación y el pago. Esta función depende de dos campos: * **`direction`**: para un saldo predeterminado creado de forma automática, 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 del sobregiro con `allowOverdraft`, `overdraftLimitEnabled` y `overdraftLimit`. Midaz **reserva** la clave `"overdraft"` para el saldo complementario 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 **transaccionales** (el predeterminado) son gestionados por el usuario y participan en transacciones normales. El sistema opera los saldos **internos** de forma exclusiva, como el complementario de sobregiro. Las transacciones de usuario no pueden apuntar a ellos, modificarlos ni eliminarlos a través de la API pública. Para conocer todos los detalles sobre los modos de configuración, las divisiones de operación, el pago automático, los eventos y los casos de uso, consulta [Sobregiro de Saldo](/es/products/midaz/balance-overdraft). ## Historial de saldo *** Midaz ofrece **consultas por punto en el tiempo** para los saldos. Puedes obtener el estado de un saldo en una marca de tiempo pasada, en la fecha de creación del saldo o después de ella. Si no existe ninguna operación antes de esa marca de tiempo, Midaz devuelve el estado inicial en cero. Devuelve `404` cuando la marca de tiempo solicitada es anterior a la creación del saldo. Esto respalda las auditorías, la conciliación y los informes históricos. ### Cómo funciona Cuando consultas el historial de saldo, Midaz devuelve los campos históricos de identidad y monto. Omite `allowSending`, `allowReceiving`, `deletedAt` y `metadata`. La implementación actual tampoco reconstruye los valores históricos de `direction` ni `settings`, y devuelve `overdraftUsed` como cero. No lo trates como una respuesta de saldo regular completa menos los indicadores de permiso. **¿Por qué el historial excluye los indicadores de permiso?** `allowSending` y `allowReceiving` son configuraciones operativas mutables. Puedes alternarlas en cualquier momento sin un asiento en el ledger. Los montos del saldo (`available`, `onHold`) cambian solo a partir de transacciones registradas. Los indicadores de permiso representan el estado operativo *actual* de un saldo, no un hecho sobre su pasado. Las auditorías históricas y la conciliación se enfocan en los **montos** en un punto en el tiempo. Si el envío o la recepción funcionaban en un momento dado no importa para la auditoría ni la conciliación. Un estado de permiso mutable dentro de instantáneas inmutables agregaría ambigüedad sin aportar 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 saldo entre sistemas en marcas de tiempo coincidentes. * **Resolución de disputas**: obtén el estado exacto 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` (por ejemplo, `2026-01-15 10:30:00`). Midaz devuelve `404` cuando la marca de tiempo solicitada es anterior a la creación del saldo. ### Consulta del historial de saldo Puedes consultar el historial de un solo saldo o de todos los saldos de una cuenta: * [Obtener el historial de saldo](/es/reference/products/midaz/v2/get-balance-at-timestamp) - obtén el estado de un saldo específico en un punto determinado en el tiempo. * [Obtener el historial de saldo por cuenta](/es/reference/products/midaz/v2/get-account-balances-at-timestamp) - obtén el estado de todos los saldos de una cuenta en un punto determinado en el tiempo. ## Gestión de saldos *** Puedes obtener tus saldos a través de la API. El motor del ledger de Midaz calcula los montos de saldo a partir de las transacciones. No puedes definir `available` ni `onHold` directamente. Administras los registros de saldo (clave, indicadores de permiso y configuración) mediante los siguientes endpoints. * [Crear un saldo](/es/reference/products/midaz/v2/create-additional-balance) - crea un nuevo saldo para una cuenta mediante la definición de una clave única. * [Listar los saldos](/es/reference/products/midaz/v2/get-all-balances) - obtén todos los saldos por organización y ledger. * [Obtener un saldo](/es/reference/products/midaz/v2/get-balance-by-id) - obtén el saldo de una cuenta específica por su ID único. * [Obtener los saldos por cuenta](/es/reference/products/midaz/v2/get-all-balances-by-account-id) - obtén el saldo de una cuenta específica. * [Obtener un saldo por alias de cuenta](/es/reference/products/midaz/v2/get-balances-by-alias) - obtén el saldo con un alias de cuenta legible (por ejemplo, @user123). * [Obtener el saldo de una cuenta externa](/es/reference/products/midaz/v2/get-balances-external-by-code) - obtén el saldo de una cuenta externa (por ejemplo, `@external/BRL`). * [Actualizar un saldo](/es/reference/products/midaz/v2/update-balance) - actualiza los indicadores de permiso y la configuración de un saldo. * [Eliminar un saldo](/es/reference/products/midaz/v2/delete-balance) - elimina un registro de saldo del sistema. Para rastrear **cómo** se formó un saldo, usa la API de operaciones para inspeccionar el historial del ledger que afectó esa cuenta. ## Próximos pasos *** * Usa la [API de operaciones](/es/products/midaz/operations) para rastrear transacciones que involucren varios saldos. * Combina varios saldos con [rutas contables](/es/products/midaz/transaction-routing-entities) para crear flujos financieros flexibles y escalables.