> ## 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 la unidad financiera central de un Ledger de Midaz, vinculada a un solo Activo, que registra cada débito, crédito y saldo de un cliente o producto. Una cuenta es la unidad financiera central de un Ledger de Midaz. Cada cuenta se vincula a un Activo y registra cada débito, crédito y saldo de ese Activo. En términos bancarios, una cuenta es un producto financiero, como una cuenta corriente, una cuenta de ahorro o una cuenta de préstamo. Midaz no limita cuántas cuentas creas. Crea tantas como necesite tu estructura. ## Estructura de la cuenta *** * **Cuenta > Ledger**: creas una cuenta dentro de un Ledger. El Ledger rastrea y consolida todos los saldos y operaciones. * **Cuenta > Portafolio**: puedes agrupar cuentas en [**Portafolios**](/es/products/midaz/portfolios) para representar grupos de clientes, líneas de producto o unidades de negocio. * **Cuenta > Activo**: cada cuenta se vincula a un **único Activo**. El Activo define el tipo de valor que contiene la cuenta, como BRL, USD, BTC o puntos de fidelidad. * **Cuenta > Tipo de cuenta**: cuando habilitas la validación de Tipo de cuenta, cada cuenta no externa debe usar un Tipo de cuenta registrado. Registras los Tipos de cuenta para tu clasificación de negocio. ## Características clave *** * Cada cuenta se vincula exactamente a un tipo de Activo. * Cada cuenta tiene un identificador único dentro de un Ledger. * Cada transacción registra débitos y créditos entre cuentas. ## Varias cuentas por cliente *** Un mismo cliente suele mantener más de un saldo. Midaz modela cada saldo como su propia cuenta, no como etiquetas sobre una cuenta compartida. Crea una cuenta separada cuando un saldo necesite su propia fuente de verdad. El mismo cliente puede mantener saldos que se comportan de forma distinta: * **Naturaleza distinta**: un saldo principal, un saldo de beneficios o un saldo promocional. * **Reglas operativas distintas**: una cuenta bloqueada u ordenada judicialmente que acepta entradas pero restringe salidas. * **Estado de cuenta y conciliación separados**: una subcuenta de producto o un bolsillo que rastreas de forma independiente. Cuando el saldo, el ledger, el estado de cuenta o la regla difieren, cada uno se convierte en su propia cuenta. La clasificas con un [Tipo de cuenta](/es/products/midaz/account-types), la agrupas bajo el cliente con un [Portafolio](/es/products/midaz/portfolios), y la vinculas a la identidad mediante [CRM](/es/products/midaz/crm/crm-overview). Una sola cuenta con etiquetas funciona hasta que los saldos divergen. Las cuentas separadas mantienen cada saldo preciso desde el inicio. Para la arquitectura de referencia completa (un cliente, varias cuentas, con ejemplos paso a paso), consulta [Midaz para clientes con varias cuentas](/es/products/midaz/midaz-for-multi-account-customers). ## Cuenta externa *** Las cuentas externas en Midaz representan cuentas fuera de la estructura de tu organización. Rastrean el dinero que entra o sale de tu ledger, por lo general hacia y desde usuarios, socios o proveedores financieros. Las cuentas externas tienen estas características: * **Mantienen el saldo de la contraparte** del dinero que entra o sale de tu ledger. * **Pueden representar una posición externa negativa.** Cuando una cuenta externa usa sobregiro, su posición derivada puede ser negativa. El saldo `Available` persistido se mantiene en cero y Midaz rastrea el uso en `OverdraftUsed`. * **El Ledger crea una cuenta externa canónica de forma automática** cuando creas un Activo. * **La cuenta externa canónica sigue un patrón de nomenclatura claro**: `@external/`, como `@external/BRL`. Estas cuentas registran entradas y salidas en el límite del ledger. **No intentes eliminar ni modificar una cuenta externa.** Midaz bloquea estas operaciones para mantener el Ledger preciso y trazable. ### Códigos de cuenta externa La cuenta externa canónica creada con un Activo sigue el patrón de nomenclatura `@external/`. El código de activo en ese alias actúa como clave de búsqueda. Puedes obtener esta cuenta canónica y sus saldos con endpoints de conveniencia que aceptan solo el código de activo: * `GET .../accounts/external/{code}`: obtiene la cuenta externa de un código de activo (por ejemplo, `BRL` se resuelve como `@external/BRL`). * `GET .../accounts/external/{code}/balances`: obtiene los saldos de esa cuenta externa. Estos endpoints son atajos para la cuenta externa canónica. Anteponen `@external/` al código que proporcionas y luego hacen una búsqueda basada en el alias. El resultado es idéntico a una consulta por ese alias completo.

ID de entidad (referencia de sistema externo)

El campo `entityId` existe en cualquier cuenta, no solo en las cuentas externas. Vincula la cuenta con un registro en un sistema externo, como una plataforma de core bancario, un CRM o un sistema de socio. * **No es lo mismo que el alias**: usas el alias en las transacciones, y debe ser único dentro de un ledger. El `entityId` es solo una referencia para tu integración, y Midaz no lo usa para mover valor. * **Opcional**: lo defines al crear la cuenta o al actualizarla. La longitud máxima es de 256 caracteres. * **Caso de uso**: cuando tu sistema ya tiene un identificador de cuenta, como `EXT-ACC-12345`, guárdalo en `entityId`. Así puedes mapear entre Midaz y tu fuente de verdad. ```json JSON theme={null} { "name": "User Checking Account", "assetCode": "BRL", "alias": "@user/checking_123", "entityId": "EXT-ACC-12345", "type": "checking" } ``` ## ID de cuenta principal *** El **ID de cuenta principal** vincula dos cuentas dentro de Midaz. Defines la relación según tu lógica de negocio. Puedes usarlo para una estructura tradicional de padre-hijo o para otra relación que tu negocio necesite.

Alias de cuenta

*** Un alias reemplaza un ID de cuenta complejo con una etiqueta legible. Esto facilita identificar las cuentas. * **Por ejemplo**: en lugar del ID `3172933b-50d2-4b17-96aa-9b378d6a6eac`, puedes usar `@username_1`. ### Usa el alias de cuenta en las transacciones Cuando creas una transacción, usa siempre el **alias de cuenta** en el campo `account`. No uses el ID de cuenta. Un alias es **opcional** cuando creas una cuenta no externa. Si lo omites, Midaz usa el ID de cuenta como alias. Una cuenta externa creada por el usuario requiere un alias. Así, cada cuenta tiene un alias único. ## Administrar las cuentas *** Puedes administrar tus cuentas mediante la API o la Lerian Console. ### Mediante la API * [Crear una cuenta](/es/reference/products/midaz/v2/create-account): abre una nueva cuenta vinculada a un Activo. * [Listar las cuentas](/es/reference/products/midaz/v2/list-accounts): consulta todas las cuentas de tu espacio de trabajo. * [Obtener una cuenta](/es/reference/products/midaz/v2/get-account-by-id): obtén los detalles de una cuenta específica. * [Obtener una cuenta por alias](/es/reference/products/midaz/v2/get-account-by-alias): obtén los detalles de una cuenta específica por su alias. * [Obtener una cuenta externa](/es/reference/products/midaz/v2/get-account-external-by-code): obtén los detalles de una cuenta externa específica por su código de activo. * [Actualizar una cuenta](/es/reference/products/midaz/v2/update-account): edita los metadatos o la configuración de una cuenta existente. * [Eliminar una cuenta](/es/reference/products/midaz/v2/delete-account): elimina una cuenta específica. **Transfiere cualquier saldo restante a otra cuenta antes de eliminar una cuenta.** Midaz no elimina una cuenta o subcuenta que todavía mantiene un saldo. ### Mediante la Lerian Console Puedes ver, crear, editar y eliminar cuentas en la página Cuentas. Esta página está en el módulo Midaz de la Lerian Console. [**Conoce más en la guía Administrar cuentas.**](/es/products/midaz/console/managing-accounts)