> ## 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 múltiples cuentas > Modela varias cuentas de Midaz bajo un mismo cliente, con saldos, ledgers, extractos e identificadores externos segregados por cuenta. Un mismo cliente rara vez tiene un solo 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 común trata estos casos como etiquetas dentro de una sola cuenta y los distingue en el código de la aplicación. Eso funciona hasta que los saldos, los ledgers, los extractos o las reglas operativas deben divergir. En ese momento, una sola 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 de 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 los **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 beneficios, 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 propio rastro de conciliación. Para los **equipos de ingeniería**, cada dirección externa se resuelve a una cuenta específica antes de que Midaz registre una transacción. Los números de core banking y los identificadores de rieles de pago apuntan cada uno a un solo saldo. Nunca tienes que adivinar a qué saldo pertenece un evento entrante. No existe un almacén de saldos separado que mantener sincronizado con el Ledger. | Una cuenta con etiquetas | Muchas cuentas por cliente | | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | Los "tipos" de saldo viven en los metadatos o en el código de la aplicación | Cada saldo es su propia Cuenta con su propio ledger y su propio extracto | | Bloquear o restringir fondos requiere lógica personalizada | El Tipo de cuenta y las reglas de ruta aplican las restricciones en el Ledger | | Los extractos deben filtrarse y reensamblarse por saldo | Cada cuenta produce un extracto limpio e independiente | | Los identificadores externos apuntan todos al mismo saldo | Cada identificador externo se resuelve a una cuenta específica | | La conciliación mezcla movimientos sin relación | La conciliación está separada por cuenta por diseño | ## La arquitectura de referencia *** El modelo es **un propietario, N cuentas, N identificadores externos**: * **Un propietario**: el cliente, identificado por un documento (CPF, CNPJ, identificación fiscal). El propietario representa *quién* mantiene la relación. No lleva saldo ni decide el enrutamiento de las transacciones. * **N cuentas**: cada cuenta es una posición contable autónoma, 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 llegar a una cuenta específica. Cada identificador se resuelve exactamente a una cuenta. Una capa de middleware mantiene el mapa entre los identificadores externos y las cuentas. Resuelve cada identificador a la cuenta correcta *antes* de la llamada a Midaz. Midaz sigue siendo la fuente de verdad para las cuentas, los saldos y los asientos. Un cliente, muchas cuentas: arquitectura de referencia Cuando el saldo, el ledger, el extracto o la regla operativa difieren según el destino, dirige cada identificador a una cuenta distinta. Un identificador externo **no** es solo un apodo para un saldo compartido. ## Cómo Midaz mapea el modelo *** Cada parte de esta arquitectura se mapea a una entidad nativa de Midaz. No necesitas construir un almacén de saldos separado ni inventar una capa contable. | Concepto | Entidad de Midaz | Qué hace | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | | El propietario (cliente) | [**Holder**](/es/products/midaz/crm/holders) | Identidad detrás de las cuentas (`NATURAL_PERSON` o `LEGAL_PERSON`), indexada por `document`. No tiene saldo. | | Cada posición de saldo | [**Cuenta**](/es/products/midaz/accounts) | Fuente de verdad para el saldo, los asientos y el extracto. | | La naturaleza de cada saldo | [**Tipo de cuenta**](/es/products/midaz/account-types) | Clasifica una cuenta (principal, beneficio, bloqueada) y habilita la validación de rutas. | | Todas las cuentas de un cliente | [**Portafolio**](/es/products/midaz/portfolios) | Agrupa las cuentas de un cliente para ver la relación total. | | Dirección externa → cuenta | [**Alias de cuenta**](/es/products/midaz/accounts#account-aliases) + [**`entityId`**](/es/products/midaz/accounts#entity-id-external-system-reference) | El alias es cómo las transacciones dirigen una cuenta; `entityId` la vincula con el identificador de un sistema externo. | | Contexto bancario y regulatorio | [**Instrument (CRM)**](/es/products/midaz/crm/crm-getting-started) | Adjunta la sucursal, el número de cuenta y los campos regulatorios. Vincula un Holder con una cuenta específica. | Gran parte de lo que haría un "registro de alias" externo ya es nativo. El **alias** de cuenta es la dirección dentro del Ledger. **`entityId`** almacena el identificador de tu sistema externo. La tarea del middleware es acotada: traducir un identificador de riel externo al alias de cuenta correcto y luego registrar la transacción. ## Requisitos previos *** Este ejemplo asume un entorno de Midaz en ejecución con lo siguiente ya configurado: | Requisito | Detalles | | -------------------------------- | -------------------------------------------------------------------------------------------- | | **Midaz** (v3.x.x+) | Core Ledger con una Organización y un Ledger ya creados | | **Un activo registrado** | `BRL` registrado como el activo operativo en el Ledger | | **Validación de tipo de cuenta** | Habilitada por Ledger para que se aplique la naturaleza de cada cuenta (consulta el paso 1) | | **CRM** (opcional) | Parte del binario del ledger, úsalo para adjuntar identidad, contexto 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). ## Construir tres cuentas para un mismo cliente *** El cliente con el documento `12345678900` necesita tres cuentas. La cuenta **principal** está libre para movimientos ordinarios. La cuenta de **beneficio** sigue las reglas del producto. La cuenta **bloqueada** acepta entradas pero restringe las salidas. Activa la validación para que cada cuenta deba declarar un tipo registrado. Esto es lo que permite que el Ledger aplique la naturaleza de cada cuenta. ```json theme={null} PATCH /v1/organizations/{org_id}/ledgers/{ledger_id}/settings { "accounting": { "validateAccountType": true } } ``` La configuración surte efecto de inmediato. No necesitas volver a desplegar. Crea un Tipo de cuenta por cada naturaleza de saldo. El `keyValue` es lo que debe coincidir con 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 las reglas del producto) y `restricted_account`. El `restricted_account` es la cuenta **bloqueada**: acepta entradas, pero condiciona o bloquea las salidas. Cada cuenta se vincula al activo `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 llegar a esta cuenta. Es tu mapa entre Midaz y tu sistema de origen. Crea un Holder para el cliente. El mismo Holder es propietario de las tres cuentas y mantiene la identidad en un solo lugar. En Midaz v4, CRM es parte del binario del ledger, así que no necesita un servicio ni un puerto separados. El ID de la organización viaja en la ruta de la URL. Consulta [Primeros pasos con CRM](/es/products/midaz/crm/crm-getting-started) para ver el esquema completo. ```bash theme={null} curl -X POST http://localhost:3002/v2/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` que se devuelve. Lo usarás en el siguiente paso. Crea un Instrument por cada cuenta del ledger para adjuntar el contexto bancario y regulatorio. El Instrument permanece dentro del binario unificado del Ledger, mientras mantiene los detalles de cara al cliente fuera del modelo transaccional de cuentas y saldos. ```bash theme={null} curl -X POST http://localhost:3002/v2/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` (`0001/12345-1`) de la cuenta principal se descompone en el `branch` (`0001`) y el `account` (`12345`) que registras aquí. Esa dirección externa ahora se resuelve a una cuenta específica. Repite para las cuentas de beneficio y bloqueada, y apunta `accountId` a cada una. Ahora tienes un cliente, tres cuentas y tres direcciones externas distintas. Cada cuenta mantiene su propio saldo, extracto y reglas bajo un único Holder. | Propietario | Identificador externo | Cuenta de Midaz | Uso | Tratamiento | | ------------- | --------------------- | ------------------- | -------------------------- | -------------------------------------------------- | | `12345678900` | `0001/12345-1` | `@cust_..._main` | Cuenta principal | Libre para movimientos ordinarios | | `12345678900` | `0001/88888-2` | `@cust_..._benefit` | Cuenta de beneficio | Movimiento regido por las reglas del producto | | `12345678900` | `0002/77777-0` | `@cust_..._blocked` | Orden judicial / bloqueada | Entrada permitida, salida condicionada o bloqueada | ## El límite de la transacción *** Cuando llega un evento externo, la resolución ocurre *antes* de la llamada a Midaz. Cada capa se mantiene en su función, y eso preserva la claridad contable. Llega una transacción, una consulta o una liquidación con un identificador externo. El middleware busca el identificador externo y lo resuelve al alias de cuenta correcto de Midaz. También aplica la validación de estado (activa, bloqueada, cerrada). Midaz registra el asiento contra la cuenta resuelta y conserva el saldo y el ledger. El extracto y la conciliación se mantienen separados por cuenta. | Capa | Responsabilidad | No debe hacer | | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | **CRM / registro** | Mantener la vista comercial y de identidad del cliente, incluido el vínculo entre el documento y la relación. | Enrutamiento de transacciones, decisiones de destino o reglas de liquidación. | | **Middleware** | Resolver los identificadores externos a una cuenta de Midaz antes de la transacción, y aplicar la 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 la 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 la validación **antes** de la llamada a Midaz. Las decisiones de enrutamiento pertenecen al middleware. El Ledger sigue siendo la fuente de verdad para los saldos y los asientos. ## Qué habilita esto *** * **Segregación real**: cada saldo tiene su propio ledger y extracto. No puedes gastar por accidente un saldo bloqueado a través de la cuenta principal. * **Enrutamiento sin ambigüedad**: cada evento externo tiene una única cuenta de destino, bien definida. * **Identidad centralizada**: un Holder es propietario de muchas cuentas. Los datos de identidad y contacto viven en un solo lugar, mientras que los saldos se mantienen separados. * **Nativo, no agregado por fuera**: las cuentas, los tipos, los alias y el `entityId` son primitivas de la plataforma, así que no hay un almacén de saldos paralelo que conciliar contra el Ledger. ## Qué necesitas para empezar *** | Requisito | Detalles | | -------------------------------- | --------------------------------------------------------------------------------------------------------------- | | **Midaz** (v3.x.x+) | Organización, Ledger y un activo registrado | | **Validación de tipo de cuenta** | Habilitada por Ledger mediante la [API de configuración del Ledger](/es/products/midaz/ledgers#ledger-settings) | | **Tipos de cuenta** | Uno por cada naturaleza de saldo (principal, beneficio, bloqueada, …) | | **Cuentas** | Una por cada saldo, cada una con un `alias` y un `entityId` | | **CRM** (opcional) | Un Holder por cliente, más un Instrument por cada cuenta del ledger | ## Próximos pasos *** La unidad financiera principal: alias, `entityId` y cuentas externas. Clasifica las cuentas y aplica su naturaleza con la validación de rutas. Agrupa las cuentas de un cliente para ver la relación total. Centraliza la identidad y adjunta el contexto bancario y regulatorio.