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

# Cuentas

> Usa las Cuentas como unidad financiera central de un Ledger Midaz, registrando débitos, créditos y saldos vinculados a un Activo específico.

Una Cuenta es la unidad financiera central dentro de un *Ledger* de Midaz. Cada Cuenta está vinculada a un **Activo** (como una moneda o un instrumento financiero) y rastrea todos los débitos, créditos y saldos para ese Activo.

En términos bancarios, una Cuenta representa un producto financiero, como una cuenta corriente, una cuenta de ahorro o una cuenta de préstamo.

<Tip>
    Midaz te permite crear tantas cuentas como exija tu estructura. Sin límites, sin restricciones; solo la flexibilidad que necesitas.
</Tip>

## Estructura de la Cuenta

***

* **Cuenta > \_Ledger**: Las Cuentas se crean *dentro* de un *Ledger*, que rastrea y consolida todos los saldos y operaciones.
* **Cuenta > Portafolio**: Las Cuentas se pueden agrupar en [**Portafolios**](/es/midaz/portfolios) para representar grupos de clientes, líneas de productos o unidades de negocio.
* **Cuenta > Activo**: Cada Cuenta está vinculada a un **único Activo**, que define el tipo de valor que posee, como BRL, USD, BTC o puntos de fidelidad.
* **Cuenta > Tipo de Cuenta**: Con la validación de Tipo de Cuenta **habilitada**, cada Cuenta debe categorizarse por un Tipo de Cuenta que se puede crear de acuerdo con necesidades específicas del usuario o clasificación de negocio.

## Características clave

***

* Cada cuenta está vinculada exactamente a un tipo de activo.
* Las cuentas se identifican de forma única dentro de un *Ledger*.
* Todas las transacciones implican débitos y créditos entre cuentas.

## Varias cuentas por cliente

***

Un único cliente suele tener más de un saldo — y Midaz modela cada uno como su propia Cuenta, en lugar de etiquetas sobre un saldo compartido. La regla que orienta: **crea una cuenta separada siempre que un saldo necesite tener su propia verdad.**

El mismo cliente puede tener saldos que se comportan de forma diferente:

* **Naturaleza diferente** — un saldo principal, un saldo de beneficio, un saldo promocional.
* **Reglas operativas diferentes** — una cuenta judicial o bloqueada que acepta entradas pero restringe salidas.
* **Extracto y conciliación separados** — una subcuenta de producto o pocket que debe ser seguida por cuenta propia.

Cuando el saldo, el ledger, el extracto o la regla difiere, cada uno se convierte en su propia Cuenta — clasificada por un [Tipo de Cuenta](/es/midaz/account-types), agrupada bajo el cliente vía un [Portfolio](/es/midaz/portfolios) y vinculada a la identidad mediante el [CRM](/es/midaz/crm/crm-overview). Modelar esto como una cuenta con etiquetas funciona hasta que los saldos necesitan divergir; las cuentas separadas mantienen cada una precisa desde el inicio.

<Tip>
  Para la arquitectura de referencia completa — un cliente, muchas cuentas, con ejemplos paso a paso — consulta [Midaz para clientes con varias cuentas](/es/midaz/midaz-for-multi-account-customers).
</Tip>

## Cuenta Externa (*External Account*)

***

Las Cuentas Externas en Midaz representan cuentas fuera de la estructura de tu organización. Se utilizan para rastrear dinero que está entrando o saliendo, generalmente vinculado a usuarios, socios o proveedores financieros fuera de tu *Ledger* interno.

Pero son más que simples marcadores de posición. Las Cuentas Externas:

* **Gestionan saldos temporales** durante operaciones que involucran a partes externas.
* **Son las únicas cuentas a las que se les permite ir a negativo**, lo que indica que los fondos están en tránsito.
* **Se crean automáticamente por el *Ledger*** cada vez que se crea un Activo.
* **Siguen un patrón de nomenclatura claro**: `@external/<código-activo>`, como `@external/BRL`.

En la práctica, estas cuentas actúan como puentes entre tu sistema y el mundo exterior, manejando entradas (*inflows*), salidas (*outflows*) y todo lo demás con claridad y control.

<Danger>
    Para mantener el *Ledger* preciso y fiable, **las cuentas externas no se pueden eliminar ni modificar**.
</Danger>

### Códigos de cuenta externa

Cada cuenta externa sigue el patrón de nomenclatura `@external/<código-activo>`. El código de activo en el alias actúa como clave de búsqueda de la cuenta externa — puedes recuperar la cuenta y sus saldos usando endpoints de conveniencia que aceptan solo el código de activo:

* `GET .../accounts/external/{code}` — Recupera la cuenta externa para un código de activo (por ejemplo, `BRL` resuelve a `@external/BRL`).
* `GET .../accounts/external/{code}/balances` — Recupera los saldos de esa cuenta externa.

Estos endpoints son atajos — anteponen `@external/` al código que proporciones y realizan una búsqueda basada en alias. El resultado es idéntico al de consultar por el alias completo.

### Entity ID (referencia de sistema externo)

El campo `entityId` de cualquier cuenta (no solo de las cuentas externas) te permite vincularla con un registro en un sistema externo — como una plataforma de core bancario, un CRM o un sistema de partner.

* **No es lo mismo que alias**: los alias se usan en transacciones y deben ser únicos dentro de un ledger. `entityId` es puramente informativo — una referencia para tu integración, no utilizada internamente por Midaz.
* **Opcional**: defínelo al crear la cuenta o mediante actualización. Máximo 256 caracteres.
* **Caso de uso**: cuando tu sistema ya tiene un identificador de cuenta (por ejemplo, `EXT-ACC-12345`), guárdalo en `entityId` para poder mapear entre Midaz y tu fuente de verdad.

<CodeGroup>
  ```json JSON theme={null}
  {
    "name": "User Checking Account",
    "assetCode": "BRL",
    "alias": "@user/checking_123",
    "entityId": "EXT-ACC-12345",
    "type": "checking"
  }
  ```
</CodeGroup>

## ID de Cuenta Principal (*Parent Account ID*)

***

El **ID de Cuenta Principal** vincula dos cuentas dentro de Midaz, lo que te da la flexibilidad de definir la relación basándose en tu lógica de negocio.

Ya sea que lo uses para representar una estructura tradicional de padre-hijo o algo completamente distinto, la elección es tuya. Midaz proporciona la base; tú decides cómo construir sobre ella.

## Alias de Cuenta (*Account aliases*)

***

Los alias facilitan la identificación de cuentas al reemplazar IDs complejos con etiquetas legibles y fáciles de usar.

* **Por ejemplo**: En lugar de hacer referencia a una cuenta como `3172933b-50d2-4b17-96aa-9b378d6a6eac`, simplemente puedes usar `@username_1`.

### Usar el Alias de Cuenta en Transacciones

Al crear una transacción, utiliza siempre el **alias de cuenta** en el campo `account`, no el ID de cuenta.

Asignar un alias al crear una cuenta es **opcional**. Si lo omites, no hay problema: el sistema utilizará automáticamente el ID de cuenta como alias. De cualquier manera, cada cuenta termina con un alias único.

Así que cuando sea el momento de hacer referencia a una cuenta en una transacción, simplemente usa el alias. Limpio, coherente y listo para usar.

## Gestión de Cuentas

***

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

### Vía API

* [Crear una Cuenta](/es/reference/midaz/create-an-account) — Abre una nueva Cuenta vinculada a un Activo.
* [Listar Cuentas](/es/reference/midaz/list-accounts) — Consulta todas las Cuentas en tu espacio de trabajo.
* [Recuperar una Cuenta](/es/reference/midaz/retrieve-an-account) — Obtén detalles de una Cuenta específica.
* [Recuperar una Cuenta por Alias](/es/reference/midaz/retrieve-an-account-by-alias) — Obtén detalles de una Cuenta específica por su alias.
* [Recuperar una Cuenta Externa](/es/reference/midaz/retrieve-an-external-account) — Obtén detalles de una Cuenta Externa específica por su código de activo.
* [Actualizar una Cuenta](/es/reference/midaz/update-an-account) — Edita los metadatos o la configuración de una Cuenta existente.
* [Eliminar una Cuenta](/es/reference/midaz/delete-an-account) — Elimina una Cuenta específica.

<Warning>
    No puedes desactivar una cuenta con un saldo restante. Primero, transfiere el monto a otra cuenta antes de desactivarla.
</Warning>

### Vía Lerian Console

Todas las acciones de gestión de Cuentas, incluyendo visualización, creación, edición y eliminación, se pueden realizar a través de Lerian Console.

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