Ledgers

Usa los Ledgers como columna vertebral financiera de tu Organización, rastreando cada Transacción con trazabilidad y segregación completas.

Un Ledger es la columna vertebral financiera de la Organización. Mantiene un registro preciso de todas las Transacciones y Operaciones. Un Ledger rastrea cada evento financiero: depósitos, retiros, transferencias y comisiones. Esto te da trazabilidad y control completos.

Las Organizaciones pueden usar múltiples Ledgers para segregar operaciones financieras. Por ejemplo, un banco mantiene Ledgers separados para diferentes líneas de negocio, regiones o requisitos regulatorios. Un solo Ledger también puede manejar todas las operaciones para una configuración más simple.

​

Estructura del Ledger

---

• Ledger > Organización: Cada Organización puede poseer múltiples Ledgers, pero cada Ledger pertenece a una sola Organización. Esto te da separación financiera y responsabilidad.
  • Usa múltiples Ledgers solo cuando necesites segregar datos u operaciones — por ejemplo, operaciones de tesorería interna versus cuentas de clientes.

Las Transacciones no pueden moverse directamente entre Ledgers. Para mover fondos entre Ledgers, orquesta la transferencia a través de un flujo de trabajo que mantenga ambos lados consistentes.

​

Cómo orquestar transacciones entre Ledgers

Para mover fondos entre dos Ledgers, crea un flujo de trabajo orquestado. El flujo de trabajo divide la transferencia en dos transacciones separadas:

1. Débito del Ledger de origen: Transfiere el monto desde una cuenta en el Ledger 1 a una Cuenta Externa. Esta cuenta hace de puente entre los dos Ledgers y siempre pertenece a un Activo.
2. Crédito al Ledger de destino: Crea una segunda transacción. Mueve el mismo monto desde la Cuenta Externa a la cuenta de destino en el Ledger 2.

En este proceso de dos pasos, cada Ledger procesa una transacción válida e independiente. La Cuenta Externa mantiene ambos lados consistentes.

Puedes usar Flowker para automatizar esta orquestación. Flowker puede añadir validaciones, condiciones y lógica de reversión si las necesitas.

​

Características clave

---

• Los Ledgers garantizan integridad financiera y transparencia operacional.
• Todas las Cuentas y Transacciones existen dentro de un Ledger y forman un sistema financiero completo.
• Cada Ledger mantiene un conjunto equilibrado de Cuentas.
• Puedes usar múltiples Ledgers para segmentación, pero las transacciones entre Ledgers necesitan manejo explícito.

​

Múltiples Ledgers

---

Midaz te permite crear múltiples Ledgers para cada organización, con más flexibilidad y control. Esto ayuda a empresas con necesidades operacionales diversas. Por ejemplo, pueden separar registros financieros por país, departamento o función de negocio.

​

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

Con Ledgers separados, la empresa mantiene registros de transacciones específicos por región, reglas fiscales y configuraciones de moneda. Aún conserva una supervisión unificada de todas las operaciones.

​

Cuándo crear un nuevo Ledger

Un Ledger es una frontera rígida, no solo una etiqueta. Las cuentas en Ledgers distintos no pueden transaccionar directamente. Debes orquestar cada movimiento entre Ledgers a través de una Cuenta Externa (consulta Cómo orquestar transacciones entre Ledgers). Este costo determina la decisión. Crea un nuevo Ledger solo cuando los segmentos rara vez mueven 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.

En resumen: si dos conjuntos de saldos transaccionan entre sí con frecuencia, mantenlos en el mismo Ledger. Sepáralos con Portfolios o Cuentas. Divide en múltiples Ledgers solo cuando el aislamiento justifique el overhead de orquestación.

​

Personalización de Ledgers

---

En Midaz, puedes adaptar la configuración de cada Ledger a tus requisitos. Los activos pertenecen a un Ledger, por lo que el mismo código es un registro independiente en cada Ledger, con su propio nombre, tipo, estado y metadata.

Ejemplo Para representar Bitcoin (BTC) en varios Ledgers, crea el activo BTC de forma independiente en cada Ledger y define el nombre, el estado y la metadata que cada Ledger necesite.

En Midaz los montos son decimales de precisión arbitraria. No existe una configuración de decimales por activo ni por Ledger — no defines una escala al crear un activo.

Este enfoque te da control granular sobre la gestión de activos para tus necesidades operacionales o regulatorias.

​

Beneficios de usar Ledgers en Midaz

---

• Organización clara: Mantén registros financieros claros y distintos para cada parte de tu negocio.
• Configuraciones personalizadas: Ajusta configuraciones de activos, monedas u otros parámetros por Ledger para necesidades locales o departamentales.
• Escalabilidad: Agrega o cambia Ledgers a medida que tu organización crece o se diversifica.
• Transparencia: Obtén una vista completa de todas las actividades financieras. Cada Ledger aporta a una sola imagen operacional.

​

Configuraciones del ledger

---

Cada Ledger tiene configuraciones ajustables que controlan cómo valida las transacciones. Por ejemplo, puedes exigir que cada transacción siga una ruta predefinida. También puedes exigir que los tipos de cuenta coincidan con tus reglas de negocio. Entonces el Ledger rechaza los movimientos inválidos antes de registrarlos.

Puedes cambiar estas configuraciones en cualquier momento a través de la API. No necesitas reiniciar el servicio ni cambiar el código.

​

Configuraciones disponibles

Las siguientes configuraciones están disponibles:

Configuración	Valor por defecto	Descripción
validateAccountType	false	Cuando está habilitada, cada cuenta nueva debe usar un tipo de cuenta registrado para el Ledger. El Ledger rechaza la creación de la cuenta si el tipo no está registrado.
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.

Comienza con ambas configuraciones deshabilitadas mientras configuras tus rutas de operación y rutas de transacción. Una vez que tu configuración de enrutamiento esté completa, habilita la validación para aplicar tus reglas de negocio.

​

Cómo las configuraciones afectan las transacciones

Cuando habilitas validateRoutes para un Ledger:

1. Cada transacción a ese Ledger debe referenciar una ruta de transacción válida.
2. El Ledger valida cada operación contra las reglas de la ruta de operación correspondiente.
3. El Ledger rechaza cualquier transacción no conforme antes de registrar el movimiento. Esto protege la integridad de tu ledger.

Cuando habilitas validateAccountType:

1. El Ledger verifica cada cuenta nueva contra sus tipos de cuenta registrados.
2. Si el tipo de cuenta no está registrado, el Ledger rechaza la creación de la cuenta.

Si habilitas la validación en un Ledger que ya procesa transacciones, los registros existentes no cambian. La validación se aplica solo a nuevas transacciones que envíes después de habilitar la configuración.

​

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 con una actualización parcial (deep merge).

Las actualizaciones de configuraciones surten efecto inmediatamente. Midaz aplica los cambios con un deep merge y modifica solo los campos que incluyas en la solicitud.

​

Gestión de Ledgers

---

Puedes gestionar tus Ledgers a través de la API o 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, Midaz no lo elimina permanentemente.

En su lugar, Midaz establece una marca de tiempo deletedAt. A partir de ese momento el Ledger queda excluido de todas las lecturas y ya no se puede usar. Su status.code no cambia. Esto preserva los datos históricos para pistas de auditoría.

​

Vía Lerian Console

Puedes ver, crear, editar y eliminar Ledgers en la página de Ledgers del Módulo Midaz de Lerian Console.

Obtén más información en la guía de Gestión de Ledgers.

Si creas tu primer Ledger en Lerian Console, lo haces como parte del flujo de incorporación. Para obtener más información, consulta la guía de incorporación del Módulo Midaz.