> ## 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.

# Ledgers

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

Un **Ledger** actúa como la columna vertebral financiera de la Organización, manteniendo un registro preciso de todas las Transacciones y Operaciones. Cada evento financiero—depósitos, retiros, transferencias, comisiones—se rastrea dentro de un Ledger, garantizando trazabilidad y control completos.

Las Organizaciones pueden usar **múltiples Ledgers** para segregar operaciones financieras. Por ejemplo, un banco puede mantener Ledgers separados para diferentes líneas de negocio, geografías o requisitos regulatorios. Alternativamente, un solo Ledger puede manejar todas las operaciones para un enfoque simplificado.

## 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.

<Warning>
  Las Transacciones **no pueden** ocurrir directamente entre Ledgers sin orquestación. Si necesitas gestionar transacciones entre Ledgers, debes implementar flujos de trabajo apropiados para garantizar la consistencia.
</Warning>

### 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:

1. **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.
2. **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**.

Este proceso de dos pasos garantiza que cada Ledger procese una transacción válida e independiente, mientras que la Cuenta Externa mantiene la consistencia en todo el ecosistema.

<Note>
  Puedes usar [Flowker](/es/flowker/what-is-flowker) para automatizar esta orquestación e incluir validaciones, condiciones y lógica de reversión si es necesario.
</Note>

## 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

Al usar Ledgers separados, la empresa puede mantener registros de transacciones específicos de la región, consideraciones fiscales y configuraciones de moneda, mientras retiene 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 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](#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](/es/midaz/portfolios)**                                        | 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](/es/midaz/accounts) / [Tipo de Cuenta](/es/midaz/account-types)** | 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 necesitan realizar transacciones entre sí con frecuencia, mantenlos en el **mismo** Ledger y 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

***

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.

En este caso, simplemente crea el activo BTC de forma independiente en cada Ledger, aplicando la configuración necesaria.

Este enfoque permite un control granular sobre la gestión de activos, alineándose con necesidades operacionales o regulatorias específicas.

## 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. |

<Tip>
  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.
</Tip>

### Cómo las configuraciones afectan las transacciones

Cuando `validateRoutes` está habilitada para un Ledger:

1. Cada transacción enviada a ese Ledger **debe** hacer referencia a una ruta de transacción válida.
2. Cada operación dentro de la transacción se valida contra las reglas de la ruta de operación correspondiente.
3. Las transacciones que no cumplan son **rechazadas antes de registrarse** — protegiendo la integridad de tu ledger.

Cuando `validateAccountType` está habilitada:

1. La cuenta de cada operación se verifica contra las reglas de tipo de cuenta definidas en la ruta de operación.
2. Si el tipo de cuenta no coincide con la regla esperada, la transacción se rechaza.

<Warning>
  Habilitar la validación en un Ledger que ya procesa transacciones no afectará los registros existentes. La validación solo se aplica a **nuevas transacciones** enviadas después de habilitar la configuración.
</Warning>

### Gestión de configuraciones vía API

Usa los endpoints de Configuraciones del Ledger para recuperar y actualizar estas configuraciones:

* [Recuperar Configuraciones del Ledger](/es/reference/midaz/retrieve-ledger-settings) — Ver las configuraciones actuales de un Ledger.
* [Actualizar Configuraciones del Ledger](/es/reference/midaz/update-ledger-settings) — Cambiar una o más configuraciones usando una actualización parcial (deep merge).

<Note>
  Las actualizaciones de configuraciones surten efecto inmediatamente. Los cambios se aplican mediante deep merge — solo los campos que incluyas en la solicitud se modifican.
</Note>

## Gestión de Ledgers

***

Puedes gestionar tus Ledgers a través de API o mediante Lerian Console.

### Ver API

* [Listar Ledgers](/es/reference/midaz/list-ledgers) - Ver los detalles de todos los Ledgers.
* [Recuperar un Ledger](/es/reference/midaz/retrieve-a-ledger) - Obtener detalles de un Ledger específico.
* [Crear un Ledger](/es/reference/midaz/create-a-ledger) - Registrar un nuevo Ledger.
* [Actualizar un Ledger](/es/reference/midaz/update-a-ledger) - Editar los detalles de un Ledger existente.
* [Eliminar un Ledger](/es/reference/midaz/delete-a-ledger) - Marcar un Ledger como eliminado.

<Note>
  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.
</Note>

### Vía Lerian Console

Todas las acciones de gestión de Ledgers, incluidas ver, crear, editar y eliminar, se pueden realizar a través de Lerian Console.

[**Obtén más información en la guía de Gestión de Ledgers.**](/es/midaz/console/managing-ledgers-via-console)

<Tip>
  Si estás creando tu **primer Ledger** en Lerian Console, lo harás como parte del flujo de incorporación. Para obtener más información, consulta la guía de [incorporación del Módulo Midaz](/es/midaz/console/midaz-console-onboarding).
</Tip>