Midaz para clientes con varias cuentas

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	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	Alias Account (CRM)	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.

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.

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 gobernado por reglas de producto”) y restricted_account — la cuenta bloqueada, donde las entradas son permitidas pero las salidas están condicionadas o bloqueadas.

Crea las tres cuentas

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

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.

Registra al cliente como un Holder

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 para la configuración del servicio y el schema completo.

curl -X POST http://localhost:4003/v1/holders \
  -H "Content-Type: application/json" \
  -H "X-Organization-Id: <your-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.

Vincula cada cuenta al Holder

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.

curl -X POST http://localhost:4003/v1/holders/<holder-id>/aliases \
  -H "Content-Type: application/json" \
  -H "X-Organization-Id: <your-organization-id>" \
  -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í — 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.

Evento externo

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

El middleware resuelve el identificador

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 en la cuenta correcta

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

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 y Alias Accounts

Centraliza la identidad y adjunta contexto bancario y regulatorio.

​Por qué esto importa

​La arquitectura de referencia

​Cómo Midaz mapea el modelo

​Requisitos previos

​Creando tres cuentas para un cliente

​La frontera transaccional

​Qué desbloquea esto

​Qué necesitas para empezar

​Próximos pasos

Cuentas

Tipos de Cuenta

Portfolios

CRM: Holders y Alias Accounts

Por qué esto importa

La arquitectura de referencia

Cómo Midaz mapea el modelo

Requisitos previos

Creando tres cuentas para un cliente

La frontera transaccional

Qué desbloquea esto

Qué necesitas para empezar

Próximos pasos