> ## 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. # Midaz para clientes con varias cuentas > Modela múltiples cuentas Midaz bajo un único cliente — con saldos, ledgers, extractos e identificadores externos segregados por cuenta. Un único cliente rara vez tiene un único saldo. La misma persona puede tener una cuenta principal, una cuenta de beneficio, una cuenta judicial o bloqueada, una subcuenta de producto o un saldo promocional — cada uno con sus propias reglas, su propio extracto y sus propias necesidades de conciliación. El atajo habitual es tratar todo como etiquetas de una única cuenta y resolverlo en el código de la aplicación. Eso funciona hasta el día en que saldos, ledgers, extractos o reglas operativas necesitan divergir — y entonces una única cuenta ya no puede decir la verdad sobre dónde está el dinero. Esta página muestra la arquitectura de referencia para **un cliente que es dueño de muchas cuentas Midaz**, cómo las entidades nativas de la plataforma mapean ese modelo, y un ejemplo paso a paso de cómo crear tres cuentas para el mismo documento de cliente. ## Por qué esto importa *** Para **equipos de producto y operaciones**, modelar cada saldo como su propia cuenta significa que cada regla de segregación — una salida bloqueada, un gasto exclusivo de beneficio, un saldo promocional con vencimiento — es aplicada por el Ledger, y no enterrada en la lógica de la aplicación. Cada cuenta lleva su propio extracto y su propia traza de conciliación. Para **equipos de ingeniería**, las direcciones externas del cliente (números de core banking, identificadores de riel de pago) resuelven a una cuenta específica antes de que se registre la transacción. No hay que adivinar a qué saldo pertenece un evento entrante, ni hay un repositorio de saldos separado que mantener sincronizado con el Ledger. | Una cuenta con etiquetas | Muchas cuentas por cliente | | --------------------------------------------------------------- | ------------------------------------------------------------------------- | | Los "tipos" de saldo viven en metadata o en el código de la app | Cada saldo es su propia Cuenta, con su propio ledger y extracto | | Bloquear o restringir fondos requiere lógica personalizada | Las reglas de Tipo de Cuenta y de ruta aplican restricciones en el Ledger | | Los extractos deben filtrarse y rearmarse por saldo | Cada cuenta produce un extracto limpio e independiente | | Los identificadores externos apuntan todos al mismo saldo | Cada identificador externo resuelve a una cuenta específica | | La conciliación mezcla movimientos sin relación entre sí | La conciliación queda separada por cuenta, por diseño | ## La arquitectura de referencia *** El modelo es **un dueño, N cuentas, N identificadores externos**: * **Un dueño** — el cliente, identificado por un documento (CPF, CNPJ, tax ID). El dueño representa *quién* tiene la relación. No carga saldo y no decide el enrutamiento transaccional. * **N cuentas** — cada cuenta es una posición contable autosuficiente, con su propio saldo, ledger, extracto y reglas. * **N identificadores externos** — las direcciones que otros sistemas (una plataforma de core banking, un riel de pago) usan para alcanzar una cuenta específica. Cada identificador resuelve a exactamente una cuenta. Una capa de middleware mantiene el mapa entre identificadores externos y cuentas, y resuelve cada identificador a la cuenta correcta *antes* de llamar a Midaz. Midaz sigue siendo la fuente de verdad para cuentas, saldos y asientos. Un cliente, muchas cuentas — arquitectura de referencia Cada identificador externo **no** es solo un apodo de un saldo compartido. Cuando el saldo, el ledger, el extracto o la regla operativa difiere según el destino, cada identificador debe apuntar a una cuenta distinta. ## Cómo Midaz mapea el modelo *** Cada parte de esta arquitectura mapea a una entidad nativa de Midaz — no necesitas construir un repositorio de saldos separado ni inventar una capa contable. | Concepto | Entidad Midaz | Qué hace | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | | El dueño (cliente) | [**Holder**](/es/midaz/crm/holders) | Identidad detrás de las cuentas (`NATURAL_PERSON` o `LEGAL_PERSON`), indexada por `document`. No carga saldo. | | Cada posición de saldo | [**Cuenta**](/es/midaz/accounts) | Fuente de verdad para saldo, asientos y extracto. | | La naturaleza de cada saldo | [**Tipo de Cuenta**](/es/midaz/account-types) | Clasifica una cuenta (principal, beneficio, bloqueada) y habilita la validación de ruta. | | Todas las cuentas de un cliente | [**Portfolio**](/es/midaz/portfolios) | Agrupa las cuentas de un cliente para ver la relación total. | | Dirección externa → cuenta | [**Alias de cuenta**](/es/midaz/accounts#account-aliases) + [**`entityId`**](/es/midaz/accounts#entity-id-external-system-reference) | El alias es cómo las transacciones direccionan una cuenta; el `entityId` la vincula al identificador de un sistema externo. | | Contexto bancario y regulatorio | [**Alias Account (CRM)**](/es/midaz/crm/alias-accounts) | Adjunta sucursal, número de cuenta y campos regulatorios, vinculando un Holder a una cuenta específica. | Buena parte de lo que haría un "alias registry" externo ya es nativo: el **alias** de la cuenta es la dirección dentro del Ledger, y el **`entityId`** almacena el identificador de tu sistema externo. El trabajo del middleware es más acotado de lo que parece a primera vista — traducir un identificador de riel externo al alias de cuenta correcto y, entonces, registrar. ## Requisitos previos *** Este ejemplo asume un entorno Midaz en ejecución con lo siguiente ya configurado: | Requisito | Detalles | | -------------------------------- | ---------------------------------------------------------------------------------------------- | | **Midaz** (v3.x.x+) | Ledger central con una Organization y un Ledger ya creados | | **Un asset registrado** | `BRL` registrado como el asset operativo en el Ledger | | **Validación de Tipo de Cuenta** | Habilitada por Ledger, para que la naturaleza de cada cuenta sea aplicada (consulta el Paso 1) | | **CRM** (opcional) | En ejecución, si deseas adjuntar contexto de identidad, bancario y regulatorio | Los valores en Midaz se representan en la unidad más pequeña de la moneda. Para BRL, `15000` significa R\$ 150,00 (centavos). ## Creando tres cuentas para un cliente *** El cliente con documento `12345678900` necesita tres cuentas: una cuenta **principal** para movimiento ordinario, una cuenta de **beneficio** gobernada por reglas de producto, y una cuenta **bloqueada** que acepta entradas pero restringe salidas. Activa la validación para que toda cuenta deba declarar un tipo registrado. Esto es lo que le permite al Ledger aplicar la naturaleza de cada cuenta. ```json theme={null} PATCH /v1/organizations/{org_id}/ledgers/{ledger_id}/settings { "accounting": { "validateAccountType": true } } ``` Las configuraciones surten efecto de inmediato — sin necesidad de redeploy. Crea un Tipo de Cuenta por naturaleza de saldo. El `keyValue` es el valor con el que debe coincidir el campo `type` de cada cuenta. ```json theme={null} POST /v1/organizations/{org_id}/ledgers/{ledger_id}/account-types { "name": "Main Account", "description": "Ordinary account, free for regular movement", "keyValue": "main_account" } ``` Repite para `benefit_account` ("Movimiento gobernado por reglas de producto") y `restricted_account` — la cuenta **bloqueada**, donde las entradas son permitidas pero las salidas están condicionadas o bloqueadas. Cada cuenta está vinculada al asset `BRL`, declara su `type` y lleva un `alias` (su dirección dentro del Ledger) y un `entityId` (su identificador en tu sistema externo). ```json theme={null} POST /v1/organizations/{org_id}/ledgers/{ledger_id}/accounts { "name": "Main account — 12345678900", "assetCode": "BRL", "alias": "@cust_12345678900_main", "entityId": "0001/12345-1", "type": "main_account" } ``` Crea la cuenta de beneficio con `alias` `@cust_12345678900_benefit`, `entityId` `0001/88888-2`, `type` `benefit_account`; y la cuenta bloqueada con `alias` `@cust_12345678900_blocked`, `entityId` `0002/77777-0`, `type` `restricted_account`. El `entityId` es donde almacenas la dirección externa que otros sistemas usan para alcanzar esta cuenta — tu mapa entre Midaz y tu sistema de origen. Crea un Holder para el cliente. El mismo Holder será dueño de las tres cuentas, manteniendo la identidad centralizada. El CRM corre como un servicio separado, y toda solicitud requiere el header `X-Organization-Id`. Consulta [Primeros pasos con el CRM](/es/midaz/crm/crm-getting-started) para la configuración del servicio y el schema completo. ```bash theme={null} curl -X POST http://localhost:4003/v1/holders \ -H "Content-Type: application/json" \ -H "X-Organization-Id: " \ -d '{ "type": "NATURAL_PERSON", "name": "Jane Smith", "document": "12345678900", "contact": { "primaryEmail": "jane.smith@example.com" } }' ``` Guarda el `holderId` retornado — lo usarás en el próximo paso. Crea una Alias Account por cuenta del ledger para adjuntar contexto bancario y regulatorio. Esto es lo que habilita las funcionalidades basadas en CRM y mantiene los detalles orientados al cliente separados del Ledger. ```bash theme={null} curl -X POST http://localhost:4003/v1/holders//aliases \ -H "Content-Type: application/json" \ -H "X-Organization-Id: " \ -d '{ "ledgerId": "", "accountId": "", "bankingDetails": { "branch": "0001", "account": "12345", "type": "CACC", "countryCode": "BR" }, "metadata": { "purpose": "main" } }' ``` Observa cómo el `entityId` de la cuenta principal (`0001/12345-1`) se descompone en la `branch` (`0001`) y la `account` (`12345`) que registras aquí — es la dirección externa resolviendo a una cuenta específica. Repite para las cuentas de beneficio y bloqueada, apuntando el `accountId` a cada una. El resultado: un cliente, tres cuentas, tres direcciones externas distintas — cada una con su propio saldo, extracto y reglas, todas pertenecientes a un único Holder. | Dueño | Identificador externo | Cuenta Midaz | Uso | Tratamiento | | ------------- | --------------------- | ------------------- | -------------------- | -------------------------------------------------- | | `12345678900` | `0001/12345-1` | `@cust_..._main` | Cuenta principal | Libre para movimiento ordinario | | `12345678900` | `0001/88888-2` | `@cust_..._benefit` | Cuenta de beneficio | Movimiento gobernado por reglas de producto | | `12345678900` | `0002/77777-0` | `@cust_..._blocked` | Judicial / bloqueada | Entrada permitida, salida condicionada o bloqueada | ## La frontera transaccional *** Cuando llega un evento externo, la resolución ocurre *antes* de que se llame a Midaz. Mantener cada capa en su rol es lo que preserva la claridad contable. Una transacción, consulta o liquidación llega cargando un identificador externo. El middleware busca el identificador externo y lo resuelve al alias de cuenta Midaz correcto, aplicando validación de estado (activo, bloqueado, cerrado). Midaz registra el asiento en la cuenta resuelta, preservando saldo y ledger. El extracto y la conciliación permanecen separados por cuenta. | Capa | Responsabilidad | No debe hacer | | ------------------ | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | **CRM / registro** | Mantener la visión comercial y de identidad del cliente, incluyendo el vínculo entre documento y relación. | Enrutamiento transaccional, decisiones de cuenta destino o reglas de liquidación. | | **Middleware** | Resolver identificadores externos a una cuenta Midaz antes de la transacción, y aplicar validación de estado. | Inventar saldos, duplicar la contabilidad o depender del CRM en tiempo real para el enrutamiento. | | **Midaz** | Registrar cuentas, saldos, asientos, ledgers y extractos como fuente de verdad financiera. | Conocer detalles del riel externo más allá de los identificadores necesarios para la integración. | Un identificador de una cuenta bloqueada o cerrada debe fallar en la validación **antes** de que se llame a Midaz. Las decisiones de enrutamiento pertenecen al middleware; el Ledger permanece como la fuente de verdad para saldos y asientos. ## Qué desbloquea esto *** * **Segregación real** — cada saldo tiene su propio ledger y extracto, por lo que un saldo bloqueado nunca puede ser gastado a través de la cuenta principal por accidente. * **Enrutamiento inequívoco** — todo evento externo tiene una única cuenta de destino bien definida. * **Identidad centralizada** — un único Holder es dueño de muchas cuentas; la identidad y los datos de contacto viven en un solo lugar, mientras los saldos permanecen separados. * **Nativo, no improvisado** — cuentas, tipos, aliases y `entityId` son primitivos de la plataforma, por lo que no hay un repositorio de saldos paralelo que conciliar contra el Ledger. ## Qué necesitas para empezar *** | Requisito | Detalles | | -------------------------------- | --------------------------------------------------------------------------------------------------- | | **Midaz** (v3.x.x+) | Organization, Ledger y un asset registrado | | **Validación de Tipo de Cuenta** | Habilitada por Ledger vía la [API de Configuraciones del Ledger](/es/midaz/ledgers#ledger-settings) | | **Tipos de Cuenta** | Uno por naturaleza de saldo (principal, beneficio, bloqueada, …) | | **Cuentas** | Una por saldo, cada una con un `alias` y un `entityId` | | **CRM** (opcional) | Un Holder por cliente, más una Alias Account por cuenta del ledger | ## Próximos pasos *** La unidad financiera central — aliases, `entityId` y cuentas externas. Clasifica cuentas y aplica su naturaleza con la validación de ruta. Agrupa las cuentas de un cliente para ver la relación total. Centraliza la identidad y adjunta contexto bancario y regulatorio.