> ## 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 bloqueada, una subcuenta de producto o un saldo promocional. Cada saldo tiene sus propias reglas, su propio extracto y sus propias necesidades de conciliación. El atajo habitual trata todo como etiquetas de una única cuenta y lo resuelve en el código de la aplicación. Eso funciona hasta que saldos, ledgers, extractos o reglas operativas deben divergir. En ese punto, 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 con muchas cuentas Midaz**. Mapea cada parte del modelo a una entidad nativa de la plataforma. Luego recorre un ejemplo: tres cuentas para el mismo documento de cliente. ## Por qué esto importa *** Para **equipos de producto y operaciones**, cada saldo se convierte en su propia cuenta. El Ledger aplica entonces cada regla de segregación — una salida bloqueada, un gasto exclusivo de beneficio, un saldo promocional con vencimiento. La regla vive en el Ledger, no 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**, cada dirección externa resuelve a una cuenta específica antes de que Midaz registre una transacción. Los números de core banking y los identificadores de riel de pago apuntan cada uno a un saldo. Nunca adivinas a qué saldo pertenece un evento entrante. No 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. Resuelve cada identificador a la cuenta correcta *antes* de la llamada a Midaz. Midaz sigue siendo la fuente de verdad para cuentas, saldos y asientos. Un cliente, muchas cuentas — arquitectura de referencia Cuando el saldo, el ledger, el extracto o la regla operativa difiere según el destino, apunta cada identificador a una cuenta distinta. Un identificador externo **no** es solo un apodo de un saldo compartido. ## Cómo Midaz mapea el modelo *** Cada parte de esta arquitectura mapea a una entidad nativa de Midaz. No construyes un repositorio de saldos separado ni inventas 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 | [**Instrument (CRM)**](/es/midaz/crm/crm-getting-started) | Adjunta sucursal, número de cuenta y campos regulatorios. Vincula 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. El **`entityId`** almacena el identificador de tu sistema externo. El trabajo del middleware es acotado — 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) | Parte del binario del ledger — úsalo para adjuntar contexto de identidad, bancario y regulatorio | Midaz representa los valores 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. La cuenta **principal** es libre para movimiento ordinario. La cuenta de **beneficio** sigue reglas de producto. La cuenta **bloqueada** 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 bajo reglas de producto) y `restricted_account`. La `restricted_account` es la cuenta **bloqueada**: acepta entradas pero condiciona o bloquea las salidas. Cada cuenta se vincula al asset `BRL` y declara su `type`. 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` y `type` `benefit_account`. Crea la cuenta bloqueada con `alias` `@cust_12345678900_blocked`, `entityId` `0002/77777-0` y `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 es dueño de las tres cuentas y mantiene la identidad en un solo lugar. En Midaz v4, el CRM forma parte del binario del ledger, por lo que no necesita un servicio ni un puerto aparte. El ID de organización viaja en la ruta de la URL — consulta [Primeros pasos con el CRM](/es/midaz/crm/crm-getting-started) para el schema completo. ```bash theme={null} curl -X POST http://localhost:3002/v1/organizations/{org_id}/holders \ -H "Content-Type: application/json" \ -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 un Instrument por cuenta del ledger para adjuntar contexto bancario y regulatorio. El Instrument habilita las funcionalidades basadas en CRM y mantiene los detalles orientados al cliente fuera del Ledger. ```bash theme={null} curl -X POST http://localhost:3002/v1/organizations/{org_id}/holders/{holder_id}/instruments \ -H "Content-Type: application/json" \ -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í. Esa dirección externa ahora resuelve a una cuenta específica. Repite para las cuentas de beneficio y bloqueada, y apunta el `accountId` a cada una. El resultado: un cliente, tres cuentas, tres direcciones externas distintas. Cada cuenta mantiene su propio saldo, extracto y reglas bajo 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 la llamada a Midaz. Cada capa se mantiene en su rol, y eso preserva la claridad contable. Una transacción, consulta o liquidación llega con un identificador externo. El middleware busca el identificador externo y lo resuelve al alias de cuenta Midaz correcto. También aplica validación de estado (activo, bloqueado, cerrado). Midaz registra el asiento en la cuenta resuelta y preserva 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 la llamada 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. No puedes gastar un saldo bloqueado 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 un Instrument 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.