> ## 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 la columna vertebral financiera de cada Organización, para registrar Transacciones y Operaciones y habilitar transferencias orquestadas entre ledgers mediante puentes.

Un **Ledger** es la columna vertebral financiera de la Organización. Mantiene un registro preciso de todas las Transacciones y Operaciones. 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.

<Warning>
  Las Transacciones **no pueden** moverse directamente entre Ledgers. Para mover fondos entre Ledgers, orquesta la transferencia mediante un workflow que mantenga ambos lados consistentes.
</Warning>

<h3 id="how-to-orchestrate-cross-ledger-transactions">
  Cómo orquestar transacciones entre Ledgers
</h3>

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

1. **Débito desde el Ledger de origen:** Transfiere el monto de una cuenta en **Ledger 1** a una **Cuenta externa**. Esta cuenta conecta 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 **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.

<Note>
  Puedes usar [Flowker](/es/products/flowker/what-is-flowker) para automatizar esta orquestación. Flowker puede agregar validaciones, condiciones y lógica de rollback si las necesitas.
</Note>

## 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**, no solo una etiqueta. Las Cuentas en Ledgers distintos no pueden transaccionar directamente. Debes orquestar todo movimiento entre Ledgers a través de una Cuenta externa (consulta [Cómo orquestar transacciones entre Ledgers](#how-to-orchestrate-cross-ledger-transactions)). 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:

| Mechanism                                                                                      | What it separates                                                                                          | Reach for it when                                                                                                                                                                     |
| ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ledger**                                                                                     | Un conjunto de libros completo e independiente: con sus propias cuentas, saldos y configuración de activos | Necesitas un aislamiento real: una entidad legal, país o régimen regulatorio distintos, donde los saldos nunca deben mezclarse y los movimientos entre segmentos son poco frecuentes. |
| **[Portafolio](/es/products/midaz/portfolios)**                                                | Una agrupación de cuentas *dentro* de un Ledger                                                            | Quieres una vista consolidada de un cliente o una unidad de negocio, pero las cuentas siguen transaccionando libremente con el resto del Ledger.                                      |
| **[Cuenta](/es/products/midaz/accounts) / [Tipo de cuenta](/es/products/midaz/account-types)** | Un saldo individual y sus reglas                                                                           | Un saldo específico necesita su propia verdad: su propio estado de cuenta, naturaleza o restricciones.                                                                                |

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.

<Note>
  Los montos en Midaz son decimales de precisión arbitraria. No existe una configuración de decimales por activo ni por Ledger. No configuras una escala cuando creas un activo.
</Note>

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

<h2 id="ledger-settings">
  Configuración del Ledger
</h2>

***

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

| Setting               | Default | Description                                                                                                                                                                |
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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.        |

<Tip>
  Empieza con ambas configuraciones deshabilitadas mientras configuras tus rutas de operación y rutas de transacción. Cuando termines de configurar el enrutamiento, habilita la validación para hacer cumplir tus reglas de negocio.
</Tip>

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

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

### Administrar configuraciones mediante la API

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

* [Consultar la configuración del Ledger](/es/reference/products/midaz/v2/get-ledger-settings): consulta la configuración actual de un Ledger.
* [Actualizar la configuración del Ledger](/es/reference/products/midaz/v2/update-ledger-settings): cambia una o más configuraciones con una actualización parcial (combinación profunda).

<Note>
  Las actualizaciones de configuración surten efecto de inmediato. Midaz aplica los cambios con una combinación profunda y modifica solo los campos que incluyes en la solicitud.
</Note>

## Administrar Ledgers

***

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

### Consultar mediante la API

* [Listar Ledgers](/es/reference/products/midaz/v2/list-ledgers) - Consulta los detalles de todos los Ledgers.
* [Consultar un Ledger](/es/reference/products/midaz/v2/get-ledger-by-id) - Obtén los detalles de un Ledger específico.
* [Crear un Ledger](/es/reference/products/midaz/v2/create-ledger) - Registra un nuevo Ledger.
* [Actualizar un Ledger](/es/reference/products/midaz/v2/update-ledger) - Edita los detalles de un Ledger existente.
* [Eliminar un Ledger](/es/reference/products/midaz/v2/delete-ledger) - Marca un Ledger como eliminado.

<Note>
  Cuando eliminas un Ledger, Midaz no lo elimina de forma permanente.

  En su lugar, Midaz define una marca de tiempo `deletedAt`. Luego, Midaz excluye el Ledger de cada lectura, y ya no puedes usarlo. Su `status.code` no cambia. Esto conserva los datos históricos para los registros de auditoría.
</Note>

### 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.**](/es/products/midaz/console/managing-ledgers-via-console)

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