Midaz para clientes con múltiples cuentas

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

Cada saldo como su propia cuenta

Para los equipos de producto y operaciones, cada saldo se convierte en su propia cuenta. El Ledger aplica entonces reglas de segregación, como una salida bloqueada o un gasto exclusivo de beneficios. 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 — Arquitectura de referencia: un cliente, muchas cuentas.

Cuando el saldo, el ledger, el extracto o la regla operativa difieren según el destino, dirige cada identificador a una cuenta distinta. No trates un identificador externo como 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	Identidad detrás de las cuentas (`NATURAL_PERSON` o `LEGAL_PERSON`), indexada por `document`. Es propietario de cada cuenta mediante su `holderId`. No tiene saldo.
Cada posición de saldo	Cuenta	Fuente de verdad para el saldo, los asientos y el extracto.
La naturaleza de cada saldo	Tipo de cuenta	Clasifica una cuenta (principal, beneficio, bloqueada) y habilita la validación de rutas.
Todas las cuentas de un cliente	Portafolio	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 dirigen una cuenta; `entityId` la vincula con el identificador de un sistema externo.
Contexto bancario y regulatorio	Instrument (CRM)	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 (v4.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 las cuentas nuevas usen un tipo registrado (consulta el paso 1)
CRM	Parte del binario del ledger. Úsalo para adjuntar identidad, contexto bancario y regulatorio

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.

Habilitar la validación de tipo de cuenta

Activa la validación para que las cuentas nuevas deban declarar un tipo registrado.

PATCH /v2/organizations/{org_id}/ledgers/{ledger_id}/settings

{
  "accounting": {
    "validateAccountType": true
  }
}

La configuración surte efecto de inmediato. No necesitas volver a desplegar.

Registrar los tipos de cuenta

Crea un Tipo de cuenta por cada naturaleza de saldo. El keyValue es lo que debe coincidir con el campo type de cada cuenta.

POST /v2/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. El tipo por sí solo no restringe nada. Con la validación de rutas activa, las rutas de transacción pueden condicionar sus salidas. Para bloquearlas, define allowSending como false en su saldo.

Registrar al cliente como Holder

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

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 id que se devuelve. Es el holderId de los siguientes pasos.

Crear las tres cuentas

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). El holderId hace que el Holder sea el propietario de la cuenta. No puedes cambiar el propietario después.

POST /v2/organizations/{org_id}/ledgers/{ledger_id}/accounts

{
  "name": "Main account - 12345678900",
  "assetCode": "BRL",
  "alias": "@cust_12345678900_main",
  "entityId": "0001/12345-1",
  "holderId": "<holder-id>",
  "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. Usa el mismo holderId para ambas.

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.

Vincular cada cuenta con el Holder

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.

curl -X POST http://localhost:3002/v2/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"
    }
  }'

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.

Evento externo

Llega una transacción, una consulta o una liquidación con un identificador externo.

El middleware resuelve el identificador

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

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.

Resultados de muchas cuentas por cliente

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: 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 (v4.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
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	Un Holder por cliente, más un Instrument opcional por cada cuenta del ledger

Próximos pasos

Cuentas

La unidad financiera principal: alias, entityId y cuentas externas.

Tipos de cuenta

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

Portafolios

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

CRM: Holders e Instruments

Centraliza la identidad y adjunta el contexto bancario y regulatorio.

Midaz Core

CRM

Fees

Midaz para clientes con múltiples cuentas

Cada saldo como su propia cuenta

La arquitectura de referencia

Cómo Midaz mapea el modelo

Requisitos previos

Construir tres cuentas para un mismo cliente

El límite de la transacción

Resultados de muchas cuentas por cliente

Qué necesitas para empezar

Próximos pasos

Cuentas

Tipos de cuenta

Portafolios

CRM: Holders e Instruments

​Cada saldo como su propia cuenta

​La arquitectura de referencia

​Cómo Midaz mapea el modelo

​Requisitos previos

​Construir tres cuentas para un mismo cliente

​El límite de la transacción

​Resultados de muchas cuentas por cliente

​Qué necesitas para empezar

​Próximos pasos

Cuentas

Tipos de cuenta

Portafolios

CRM: Holders e Instruments

Cada saldo como su propia cuenta

La arquitectura de referencia

Cómo Midaz mapea el modelo

Requisitos previos

Construir tres cuentas para un mismo cliente

El límite de la transacción

Resultados de muchas cuentas por cliente

Qué necesitas para empezar

Próximos pasos