Ledgers

Un Ledger mantiene un registro preciso de todas las Transacciones y Operaciones de una Organización. Un Ledger registra cada evento financiero: depósitos, retiros, transferencias y comisiones. Las Organizaciones pueden usar varios Ledgers para separar las operaciones financieras. Por ejemplo, un banco mantiene Ledgers separados para distintas líneas de negocio, regiones o requisitos regulatorios. Un único Ledger también puede gestionar todas las operaciones para una configuración más simple.

​

Estructura del Ledger

---

• Ledger > Organization: Cada Organización puede tener varios Ledgers, pero cada Ledger pertenece a una sola Organización.
  • Usa varios Ledgers solo cuando necesites separar datos u operaciones, por ejemplo, operaciones de tesorería interna frente a cuentas de clientes.

​

Cómo orquestar transacciones entre Ledgers

Cuando cada Ledger involucrado habilita crossLedger.enabled, envía una transacción direct o hold mediante la API v2. Cada tramo indica el organizationId y el ledgerId de su cuenta. Midaz divide la transferencia en una transacción balanceada por Ledger:

1. Débito desde el Ledger de origen: La cuenta en Ledger 1 envía el monto a la Cuenta externa del Ledger 1 (@external/<asset>).
2. Crédito al Ledger de destino: La Cuenta externa del Ledger 2 envía el monto a la cuenta de destino.

Las transacciones comparten un único groupId. En una transacción direct, se completan o fallan juntas.

​

Características clave

---

• Todas las Cuentas y Transacciones existen dentro de un Ledger.
• Cada Ledger mantiene un conjunto equilibrado de Cuentas.
• Puedes usar varios Ledgers para la segmentación, pero las transacciones entre ledgers necesitan un manejo explícito.

​

Varios Ledgers

---

Midaz permite crear varios Ledgers para cada organización. Por ejemplo, una empresa puede separar los registros financieros por país, departamento o función de negocio.

​

Ejemplo de caso de uso

Considera una empresa global con operaciones en varias 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, reglas fiscales y configuraciones de moneda específicos de cada región. Aun así, mantiene una supervisión unificada de todas las operaciones.

​

Cuándo crear un nuevo Ledger

Un Ledger es un límite estricto. Todo movimiento entre Ledgers pasa por la Cuenta externa de cada Ledger (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í. Usa esta heurística para elegir el nivel de separación adecuado: Si dos conjuntos de saldos transaccionan con frecuencia entre sí, mantenlos en el mismo Ledger. Sepáralos con Portafolios o Cuentas. Divide en varios Ledgers solo cuando el aislamiento valga el costo adicional de la orquestación.

​

Personalizar Ledgers

---

En Midaz, puedes adaptar la configuración de cada Ledger a tus necesidades. Los Activos pertenecen al ámbito de un Ledger, por lo que el mismo código es un registro independiente en cada Ledger, con su propio nombre, tipo, estado y metadatos. Ejemplo Para representar Bitcoin (BTC) en distintos Ledgers, crea el activo BTC de forma independiente en cada Ledger y define el nombre, el estado y los metadatos que necesite cada Ledger.

​

Beneficios de usar Ledgers en Midaz

---

• Organización clara: Mantén registros financieros claros y diferenciados para cada parte de tu negocio.
• Configuraciones personalizadas: Ajusta la configuración de activos, monedas u otros parámetros por Ledger según 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 se suma a una sola imagen operativa.

​

Configuración 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. El Ledger entonces 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 código.

​

Configuraciones disponibles

​

Cómo las configuraciones afectan las transacciones

Cuando habilitas validateRoutes para un Ledger:

1. Cada transacción a ese Ledger debe hacer referencia a 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.

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.

​

Administrar configuraciones mediante la API

Usa los endpoints de Ledger Settings para consultar y actualizar estas configuraciones:

• Consultar la configuración del Ledger: consulta la configuración actual de un Ledger.
• Actualizar la configuración del Ledger: cambia una o más configuraciones con una actualización parcial (combinación profunda).

​

Administrar Ledgers

---

Puedes administrar tus Ledgers a través de la API o de Lerian Console.

​

Consultar mediante la API

• Listar Ledgers - Consulta los detalles de todos los Ledgers.
• Consultar un Ledger - Obtén los detalles de un Ledger específico.
• Crear un Ledger - Registra un nuevo Ledger.
• Actualizar un Ledger - Edita los detalles de un Ledger existente.
• Eliminar un Ledger - Marca un Ledger como eliminado.

​

A través de Lerian Console

Puedes ver, crear, editar y eliminar Ledgers en la página Ledgers del Midaz Module de Lerian Console. Obtén más información en la guía Administrar Ledgers.