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 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 tu estructura necesite.

​

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 para representar grupos de clientes, líneas de productos o unidades de negocio.
• Cuenta > Activo: Cada Cuenta se vincula a un único Activo. El Activo define el tipo de valor que la Cuenta mantiene, 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 según 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 único cliente suele tener más de un saldo. Midaz modela cada saldo como su propia Cuenta, no como 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 o 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 sigues por su cuenta.

Cuando el saldo, el ledger, el extracto o la regla difiere, cada uno se convierte en su propia Cuenta. La clasificas por un Tipo de Cuenta, la agrupas bajo el cliente con un Portfolio y la vinculas a la identidad mediante el CRM. Una 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, muchas cuentas, con ejemplos paso a paso — consulta Midaz para clientes con varias cuentas.

​

Cuenta Externa (External Account)

---

Las Cuentas Externas en Midaz representan cuentas fuera de la estructura de tu organización. Rastrean dinero que entra o sale de tu ledger, normalmente hacia y desde usuarios, socios o proveedores financieros.

Las cuentas externas tienen estas características:

• Mantienen el saldo de 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 persistido Available se mantiene en cero y Midaz registra el uso en OverdraftUsed.
• El Ledger crea una Cuenta externa canónica automáticamente cuando creas un Activo.
• La Cuenta externa canónica sigue un patrón de nomenclatura claro: @external/<asset-code>, como @external/BRL.

En la práctica, estas cuentas actúan como el puente entre tu sistema y el mundo exterior. Registran entradas y salidas en el límite del ledger.

No intentes eliminar ni cambiar 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/<asset-code>. El código de activo en ese alias actúa como clave de búsqueda. Puedes recuperar esta Cuenta canónica y sus saldos con 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 para la Cuenta externa canónica. Anteponen @external/ al código que proporcionas y luego realizan una búsqueda basada en alias. El resultado es idéntico al de una consulta por ese alias completo.

​

Entity ID (referencia de sistema externo)

El campo entityId existe en cualquier cuenta, no solo en las cuentas externas. Vincula la cuenta a 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: usas el alias en 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: defínelo cuando creas la cuenta o cuando la actualizas. 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

{
  "name": "User Checking Account",
  "assetCode": "BRL",
  "alias": "@user/checking_123",
  "entityId": "EXT-ACC-12345",
  "type": "checking"
}

​

ID de Cuenta Principal (Parent Account ID)

---

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 (Account aliases)

---

Un alias reemplaza un ID de cuenta complejo por una etiqueta legible. Esto hace que las cuentas sean más fáciles de identificar.

• Por ejemplo: en lugar del ID 3172933b-50d2-4b17-96aa-9b378d6a6eac, puedes usar @username_1.

​

Usar el Alias de Cuenta en 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. Cada cuenta tiene entonces un alias único.

​

Gestión de Cuentas

---

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

​

Vía API

• Crear una Cuenta — Abre una nueva Cuenta vinculada a un Activo.
• Listar Cuentas — Consulta todas las Cuentas en tu espacio de trabajo.
• Recuperar una Cuenta — Obtén detalles de una Cuenta específica.
• Recuperar una Cuenta por Alias — Obtén detalles de una Cuenta específica por su alias.
• Recuperar una Cuenta Externa — Obtén detalles de una Cuenta Externa específica por su código de activo.
• Actualizar una Cuenta — Edita los metadatos o la configuración de una Cuenta existente.
• Eliminar una Cuenta — Elimina una Cuenta específica.

Transfiere cualquier saldo restante a otra cuenta antes de eliminar una cuenta. Midaz no elimina una cuenta ni una subcuenta que aún mantiene un saldo.

​

Vía Lerian Console

Puedes ver, crear, editar y eliminar Cuentas en la página de Cuentas. Esta página está en el módulo Midaz de Lerian Console.

Obtén más información en la guía de Gestión de Cuentas.