Estructura del Ledger
- Ledger > Organización: Cada Organización puede poseer múltiples Ledgers, pero cada Ledger pertenece a una sola Organización. Esto garantiza separación financiera y responsabilidad.
- Los múltiples Ledgers solo deben usarse cuando se requiera segregación de datos u operacional—por ejemplo, para operaciones de tesorería interna versus cuentas de clientes.
Cómo orquestar transacciones entre Ledgers
Para mover fondos entre dos Ledgers, necesitarás crear un flujo de trabajo orquestado que divida la transferencia en dos transacciones separadas:- Débito del Ledger de origen: Comienza transfiriendo la cantidad deseada desde una cuenta en el Ledger 1 a una Cuenta Externa. Esta cuenta actúa como puente y siempre está vinculada a un Activo específico.
- Crédito al Ledger de destino: Luego, crea una segunda transacción que mueva la misma cantidad desde la Cuenta Externa a la cuenta objetivo en el Ledger 2.
Puedes usar Flowker para automatizar esta orquestación e incluir validaciones, condiciones y lógica de reversión si es necesario.
Características clave
- Los Ledgers garantizan integridad financiera y transparencia operacional.
- Todas las Cuentas y Transacciones existen dentro de un Ledger, formando un sistema financiero completo.
- Cada Ledger mantiene un conjunto equilibrado de Cuentas.
- Se pueden usar múltiples Ledgers para segmentación, pero las transacciones entre Ledgers requieren manejo explícito.
Múltiples Ledgers
Midaz proporciona la capacidad de crear múltiples Ledgers para cada organización, ofreciendo mayor flexibilidad y control. Esta característica es particularmente beneficiosa para empresas con necesidades operacionales diversas, como separar registros financieros por país, departamento o función comercial específica.
Ejemplo de caso de uso
Considera una empresa global con negocios en múltiples regiones:- Ledger 1: Negocio en EE. UU.
- Ledger 2: Negocio en la UE
- Ledger 3: Negocio en APAC
Cuándo crear un nuevo Ledger
Un Ledger es una frontera rígida, no solo una etiqueta. Las cuentas en Ledgers distintos no pueden realizar transacciones directamente entre sí — todo movimiento entre Ledgers debe orquestarse a través de una Cuenta Externa (consulta Cómo orquestar transacciones entre Ledgers). Ese costo es el factor decisivo: crea un nuevo Ledger solo cuando los segmentos rara vez necesiten mover dinero entre sí. Utiliza esta heurística para elegir el nivel de separación adecuado:| Mecanismo | Qué separa | Úsalo cuando |
|---|---|---|
| Ledger | Un conjunto de libros completo y autónomo — con sus propias cuentas, saldos y configuración de activos | Necesitas aislamiento real: una entidad jurídica, país o régimen regulatorio separado, donde los saldos nunca deben mezclarse y los movimientos entre segmentos son raros. |
| Portfolio | Una agrupación de cuentas dentro de un Ledger | Quieres una vista consolidada de un cliente o unidad de negocio, pero las cuentas siguen realizando transacciones libremente con el resto del Ledger. |
| Cuenta / Tipo de Cuenta | Un saldo individual y sus reglas | Un único saldo necesita tener su propia verdad — su propio extracto, naturaleza o restricciones. |
Personalización de Ledgers
Una de las características destacadas de los Ledgers en Midaz es la capacidad de adaptar configuraciones según requisitos individuales. Por ejemplo, el mismo activo puede configurarse de manera diferente en Ledgers separados: Ejemplo Para representar Bitcoin (BTC) con configuraciones únicas en diferentes Ledgers:
- Ledger 1: BTC con 10 decimales.
- Ledger 2: BTC con 20 decimales.
Beneficios de usar Ledgers en Midaz
- Organización Mejorada: Mantén registros financieros claros y distintos adaptados a varios aspectos de tu negocio.
- Configuraciones Personalizadas: Ajusta configuraciones de activos, monedas u otros parámetros por Ledger para satisfacer necesidades localizadas o departamentales.
- Escalabilidad: Agrega o modifica fácilmente Ledgers a medida que tu organización crece o se diversifica.
- Transparencia: Obtén información completa sobre todas las actividades financieras, con cada Ledger contribuyendo a una imagen operacional cohesiva.
Configuraciones del ledger
Cada Ledger tiene configuraciones ajustables que controlan cómo se validan las transacciones. Por ejemplo, puedes exigir que cada transacción siga una ruta predefinida, o que los tipos de cuenta coincidan con tus reglas de negocio — de modo que el ledger rechace movimientos inválidos antes de que se registren. Estas configuraciones se pueden cambiar en cualquier momento a través de la API, sin necesidad de reiniciar el servicio ni realizar cambios en el código.
Configuraciones disponibles
Las siguientes configuraciones están disponibles:| Configuración | Valor por defecto | Descripción |
|---|---|---|
validateAccountType | false | Cuando está habilitada, valida que los tipos de cuenta en cada operación coincidan con las reglas definidas en las rutas de operación asociadas. |
validateRoutes | false | Cuando está habilitada, cada transacción debe incluir una ruta de transacción asociada. Cada operación también se valida contra las reglas de su ruta de operación. |
Cómo las configuraciones afectan las transacciones
CuandovalidateRoutes está habilitada para un Ledger:
- Cada transacción enviada a ese Ledger debe hacer referencia a una ruta de transacción válida.
- Cada operación dentro de la transacción se valida contra las reglas de la ruta de operación correspondiente.
- Las transacciones que no cumplan son rechazadas antes de registrarse — protegiendo la integridad de tu ledger.
validateAccountType está habilitada:
- La cuenta de cada operación se verifica contra las reglas de tipo de cuenta definidas en la ruta de operación.
- Si el tipo de cuenta no coincide con la regla esperada, la transacción se rechaza.
Gestión de configuraciones vía API
Usa los endpoints de Configuraciones del Ledger para recuperar y actualizar estas configuraciones:- Recuperar Configuraciones del Ledger — Ver las configuraciones actuales de un Ledger.
- Actualizar Configuraciones del Ledger — Cambiar una o más configuraciones usando una actualización parcial (deep merge).
Las actualizaciones de configuraciones surten efecto inmediatamente. Los cambios se aplican mediante deep merge — solo los campos que incluyas en la solicitud se modifican.
Gestión de Ledgers
Puedes gestionar tus Ledgers a través de API o mediante Lerian Console.
Ver API
- Listar Ledgers - Ver los detalles de todos los Ledgers.
- Recuperar un Ledger - Obtener detalles de un Ledger específico.
- Crear un Ledger - Registrar un nuevo Ledger.
- Actualizar un Ledger - Editar los detalles de un Ledger existente.
- Eliminar un Ledger - Marcar un Ledger como eliminado.
Cuando eliminas un Ledger, no se elimina permanentemente del sistema.En su lugar, se agrega una etiqueta de eliminación con una marca de tiempo, y el Ledger se vuelve inactivo e inutilizable, lo que ayuda a preservar los datos históricos para pistas de auditoría.