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.
- Reservas de inversión
- Límites de crédito
- Fondos de garantía (collateral) (bloqueados)
- Fondos operativos del día a día
Figura 1. Diagrama de múltiples saldos.
Si no se proporciona ninguna
balanceKey en una transacción, Midaz utiliza automáticamente el saldo por defecto de la cuenta.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.
Estructura del Saldo
- Saldo > Cuenta: Cada Saldo pertenece a una Cuenta, que posee y mueve valor.
- Saldo > Activo (Asset): Cada Saldo está asociado a un Activo específico, como BRL o BTC.
- Saldo > Libro Mayor (Ledger): Los Saldos existen dentro de un Libro Mayor, permitiendo entornos de múltiples libros.
- Saldo > Clave (Key): Cada Saldo tiene una clave única dentro de la cuenta (p. ej.,
default,credit,collateral).
Figura 2. Diagrama de relaciones de la estructura del Saldo.
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, libro mayor, 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
- Crear una Transacción de Entrada (Inflow)
- Crear una Transacción de Salida (Outflow)
- Crear una Anotación de Transacción
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) ahora incluyen la
balanceKey.
Formato anterior
Nuevo formato
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.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 — Crea un nuevo saldo para una cuenta definiendo una clave única.
- Listar Saldos — Recupera todos los saldos por organización y libro mayor.
- Recuperar un Saldo — Obtén el saldo de una cuenta específica por su ID único.
- Recuperar Saldos por Cuenta — Obtén el saldo de una cuenta específica.
- Recuperar un Saldo por Alias de Cuenta — Obtén el saldo utilizando un alias de cuenta legible por humanos (p. ej., @user123).
- Recuperar un Saldo de una Cuenta Externa — Recupera el saldo de una cuenta externa (p. ej.,
@external/BRL). - Actualizar un Saldo — Ajusta manualmente un saldo para fines operativos o de prueba.
- Eliminar un Saldo (obsoleto) — 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 libro mayor que impactó a esa cuenta.
Próximos pasos
- Utiliza la API de Operaciones para rastrear transacciones que involucren múltiples saldos.
- Combina múltiples saldos con Enrutamiento de Transacciones para crear flujos financieros flexibles y escalables.