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.

Arquitectura de referencia: un cliente, muchas cuentas.

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	Identidad detrás de las cuentas (NATURAL_PERSON o LEGAL_PERSON), indexada por document. No carga saldo.
Cada posición de saldo	Cuenta	Fuente de verdad para saldo, asientos y extracto.
La naturaleza de cada saldo	Tipo de Cuenta	Clasifica una cuenta (principal, beneficio, bloqueada) y habilita la validación de ruta.
Todas las cuentas de un cliente	Portfolio	Agrupa las cuentas de un cliente para ver la relación total.
Dirección externa → cuenta	Alias de cuenta + entityId	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)	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.

1. Habilita la validación de Tipo de Cuenta

   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.

   PATCH /v1/organizations/{org_id}/ledgers/{ledger_id}/settings
   
   {
     "accounting": {
       "validateAccountType": true
     }
   }
   

   Las configuraciones surten efecto de inmediato — sin necesidad de redeploy.

2. Registra los Tipos de Cuenta

   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.

   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.

3. Crea las tres cuentas

   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).

   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.

4. Registra al cliente como un Holder

   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 para el schema completo.

   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": "[e-mail]"
       }
     }'
   

   Guarda el holderId retornado — lo usarás en el próximo paso.

5. Vincula cada cuenta al Holder

   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.

   curl -X POST http://localhost:3002/v1/organizations/{org_id}/holders/{holder_id}/instruments \
     -H "Content-Type: application/json" \
     -d '{
       "ledgerId": "<your-ledger-id>",
       "accountId": "<main-account-id>",
       "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.

1. Evento externo

   Una transacción, consulta o liquidación llega con un identificador externo.

2. El middleware resuelve el identificador

   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).

3. Midaz registra en la cuenta correcta

   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
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

---

Cuentas

La unidad financiera central — aliases, entityId y cuentas externas.

Tipos de Cuenta

Clasifica cuentas y aplica su naturaleza con la validación de ruta.

Portfolios

Agrupa las cuentas de un cliente para ver la relación total.

CRM: Holders e Instruments

Centraliza la identidad y adjunta contexto bancario y regulatorio.