Holders

Un Holder es la entidad principal en CRM. Representa a un individuo u organización del mundo real detrás de una cuenta del Ledger en Midaz, almacenando atributos relacionados con la identidad como nombre, número de documento, datos de contacto y direcciones. Los Holders son gestionados por CRM y no pertenecen al dominio transaccional del ledger. Enriquecen las cuentas del ledger con datos relevantes para el negocio sin interferir con la lógica, consistencia o rendimiento del ledger. Cada Holder es de uno de dos tipos: Persona Natural (Natural Person) o Persona Jurídica (Legal Person).

Para un recorrido paso a paso sobre cómo crear y gestionar holders, consulte Primeros pasos con CRM.

Tipos de Holder

El tipo de holder determina qué campos están disponibles y cómo se trata la entidad en la plataforma. Se define al momento de la creación y no puede cambiarse posteriormente.

Persona Natural (Natural Person)

Representa a un cliente individual. Soporta atributos personales como nombre, género, fecha de nacimiento, estado civil, nacionalidad e información familiar. Usa este tipo para:

Titulares de cuentas bancarias individuales
Propietarios de billeteras personales
Trabajadores independientes o autónomos

Persona Jurídica (Legal Person)

Representa a una empresa u organización. Soporta atributos empresariales como nombre comercial, tipo de actividad, fecha de fundación, tamaño de la empresa y detalles del representante legal. Usa este tipo para:

Cuentas de tesorería corporativa
Socios comerciales y proveedores
Clientes institucionales

Elige el tipo de holder con cuidado al momento de la creación. Una vez definido, no puede cambiarse — sería necesario crear un nuevo Holder con el tipo correcto.

Campos del Holder

Campos principales

Campo	Tipo	Requerido	Descripción
id	`uuid`	Generado por el sistema	Identificador único del Holder.
type	`enum`	Sí	`NATURAL_PERSON` o `LEGAL_PERSON`.
name	`string`	Sí	Nombre completo del individuo o razón social de la empresa.
document	`string`	Sí	Número del documento de identificación (ej.: CPF, CNPJ, pasaporte).
externalId	`string`	No	Identificador opcional para mapear el Holder a un sistema externo.
metadata	`object`	No	Pares clave-valor para datos personalizados y no sensibles. Claves limitadas a 100 caracteres y valores a 2000 caracteres.
createdAt	`datetime`	Generado por el sistema	Timestamp de creación (RFC 3339).
updatedAt	`datetime`	Generado por el sistema	Timestamp de última actualización (RFC 3339).
deletedAt	`datetime`	Generado por el sistema	Timestamp de eliminación lógica, si aplica (RFC 3339).

Campos de dirección

El objeto addresses soporta hasta tres direcciones: primary, additional1 y additional2. Cada dirección contiene:

Campo	Tipo	Requerido	Descripción
line1	`string`	Sí	Línea principal de dirección (calle, número). Máx. 256 caracteres.
line2	`string`	No	Línea secundaria de dirección (apartamento, oficina). Máx. 256 caracteres.
zipCode	`string`	Sí	Código postal. Máx. 20 caracteres.
city	`string`	Sí	Nombre de la ciudad. Máx. 100 caracteres.
state	`string`	Sí	Estado o provincia. Máx. 100 caracteres.
country	`string`	Sí	Código de país ISO 3166-1 alpha-2 (ej.: `US`, `BR`).
description	`string`	No	Una etiqueta descriptiva para la dirección (por ejemplo, Home, Office o Billing). Máx. 100 caracteres.

Campos de contacto

Campo	Tipo	Requerido	Descripción
primaryEmail	`string`	No	Dirección de correo electrónico principal.
secondaryEmail	`string`	No	Dirección de correo electrónico secundaria.
mobilePhone	`string`	No	Número de teléfono móvil con código de país (ej.: `+5511999999999`).
otherPhone	`string`	No	Número de teléfono alternativo.

Campos de Persona Natural

Disponibles solo cuando type es NATURAL_PERSON.

Campo	Tipo	Requerido	Descripción
favoriteName	`string`	No	Nombre preferido o apodo.
socialName	`string`	No	Nombre social (nombre con el que la persona se identifica).
gender	`string`	No	Identidad de género.
birthDate	`string`	No	Fecha de nacimiento en formato `AAAA-MM-DD`.
civilStatus	`string`	No	Estado civil (ej.: Soltero, Casado, Divorciado).
nationality	`string`	No	Nacionalidad (ej.: Brasileño, Estadounidense).
motherName	`string`	No	Nombre completo de la madre.
fatherName	`string`	No	Nombre completo del padre.
status	`string`	No	Estado del ciclo de vida (ej.: `Active`, `Inactive`, `Suspended`, `Closed`).

Campos de Persona Jurídica

Disponibles solo cuando type es LEGAL_PERSON.

Campo	Tipo	Requerido	Descripción
tradeName	`string`	No	Nombre comercial de la empresa.
activity	`string`	No	Actividad principal de la empresa.
type	`string`	No	Estructura legal (ej.: SRL, S.A.).
foundingDate	`string`	No	Fecha de fundación de la empresa en formato `AAAA-MM-DD`.
size	`string`	No	Clasificación del tamaño de la empresa (ej.: Pequeña, Mediana, Grande).
status	`string`	No	Estado del ciclo de vida (ej.: `Active`, `Inactive`, `Suspended`, `Closed`).

Representante

El objeto representative dentro de legalPerson almacena los detalles del representante legal de la empresa:

Campo	Tipo	Requerido	Descripción
name	`string`	No	Nombre completo del representante legal.
document	`string`	No	Número de documento del representante.
email	`string`	No	Dirección de correo electrónico del representante.
role	`string`	No	Cargo dentro de la empresa (ej.: CEO, CFO).

Seguridad de los datos

Varios campos del Holder están cifrados en reposo usando cifrado AES, incluyendo name, document e información de contacto. Esto garantiza que los datos personales sensibles estén protegidos incluso si el almacenamiento subyacente se ve comprometido.

Nunca almacenes información sensible en el objeto metadata. Los metadatos no están cifrados y se almacenan en texto plano.

Para la lista completa de campos protegidos y estrategias de cifrado, consulta Seguridad de datos del CRM.

Gestionando Holders

Vía API

Usa la API del CRM para gestionar Holders programáticamente:

Crear un Holder — Registrar un nuevo Holder en el sistema.
Listar Holders — Ver todos los Holders con paginación y filtros.
Consultar un Holder — Obtener los detalles de un Holder específico.
Actualizar un Holder — Editar los datos de un Holder existente.
Eliminar un Holder — Eliminar lógicamente o remover permanentemente un Holder.

Todas las solicitudes a la API del CRM requieren el header X-Organization-Id. Si Access Manager está habilitado, también se requiere un header Authorization con un token Bearer.

Vía Lerian Console

Puedes gestionar Holders a través de la página Holders en el Módulo Midaz de Lerian Console. La consola ofrece una interfaz visual para crear, ver, editar y eliminar Holders sin escribir código. Aprende más en la guía de Gestión de Holders.

Próximos pasos

Alias Accounts

Aprende cómo las Alias Accounts vinculan Holders a cuentas del Ledger en Midaz.

Usando CRM

Sigue la guía paso a paso para registrar Holders y crear Alias Accounts.

Midaz Core

CRM

Fees

Tipos de Holder

Persona Natural (Natural Person)

Persona Jurídica (Legal Person)

Campos del Holder

Campos principales

Campos de dirección

Campos de contacto

Campos de Persona Natural

Campos de Persona Jurídica

Representante

Seguridad de los datos

Gestionando Holders

Vía API

Vía Lerian Console

Próximos pasos

Alias Accounts

Usando CRM

​Tipos de Holder

​Persona Natural (Natural Person)

​Persona Jurídica (Legal Person)

​Campos del Holder

​Campos principales

​Campos de dirección

​Campos de contacto

​Campos de Persona Natural

​Campos de Persona Jurídica

​Representante

​Seguridad de los datos

​Gestionando Holders

​Vía API

​Vía Lerian Console

​Próximos pasos

Alias Accounts

Usando CRM

Tipos de Holder

Persona Natural (Natural Person)

Persona Jurídica (Legal Person)

Campos del Holder

Campos principales

Campos de dirección

Campos de contacto

Campos de Persona Natural

Campos de Persona Jurídica

Representante

Seguridad de los datos

Gestionando Holders

Vía API

Vía Lerian Console

Próximos pasos