Skip to main content
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 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, la agrupas bajo el cliente con un Portafolio, y la vinculas a la identidad mediante CRM. 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.

​
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/<asset-code>, 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/<asset-code>. 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.

​
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

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.