Holders

Un Holder es la entidad principal en CRM. Representa a una persona u organización del mundo real detrás de una cuenta del ledger de Midaz. Un Holder almacena atributos de identidad como el nombre, el número de documento, los datos de contacto y las direcciones. CRM gestiona los Holders. Los Holders no pertenecen al dominio transaccional del ledger. Enriquecen las cuentas del ledger con datos de negocio. No afectan la lógica, la consistencia ni el rendimiento del ledger. Cada Holder es de uno de dos tipos: Persona Natural (individuo) o Persona Jurídica (empresa/organización).

Para crear y gestionar holders paso a paso, consulta Primeros pasos con CRM.

Tipos de Holder

El tipo de holder controla qué campos están disponibles. También define cómo trata la plataforma a la entidad. Eliges el tipo al crearlo. No puedes cambiarlo después.

Persona Natural

El tipo Persona Natural representa a un cliente individual. Admite atributos personales como el nombre, el género, la fecha de nacimiento, el estado civil, la nacionalidad y los datos familiares. Usa este tipo para:

Titulares individuales de cuentas bancarias
Propietarios de billeteras personales
Freelancers o propietarios únicos

Persona Jurídica

El tipo Persona Jurídica representa a una empresa u organización. Admite atributos de negocio como el nombre comercial, el tipo de actividad, la fecha de fundación, el tamaño de la empresa y los datos 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 crearlo. No puedes cambiarlo después. Para usar un tipo diferente, crea un nuevo Holder.

Campos del Holder

Campos principales

Campo	Tipo	Obligatorio	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 de la persona o razón social de la empresa.
document	`string`	Sí	Número de documento de identificación (por ejemplo, CPF, CNPJ, pasaporte).
externalId	`string`	No	Identificador opcional para vincular el Holder con un sistema externo.
metadata	`object`	No	Pares clave-valor para datos personalizados y no sensibles. Las claves están limitadas a 100 caracteres y los valores a 2000 caracteres.
createdAt	`datetime`	Generado por el sistema	Marca de tiempo de creación (RFC 3339).
updatedAt	`datetime`	Generado por el sistema	Marca de tiempo de la última actualización (RFC 3339).
deletedAt	`datetime`	Generado por el sistema	Marca de tiempo del borrado lógico, si aplica (RFC 3339).

Campos de dirección

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

Campo	Tipo	Obligatorio	Descripción
line1	`string`	Sí	Línea principal de la dirección (calle, número). Máximo 256 caracteres.
line2	`string`	No	Línea secundaria de la dirección (apartamento, suite). Máximo 256 caracteres.
zipCode	`string`	Sí	Código postal. Máximo 20 caracteres.
city	`string`	Sí	Nombre de la ciudad. Máximo 100 caracteres.
state	`string`	Sí	Código de estado o provincia. Máximo 100 caracteres.
country	`string`	Sí	Código de país ISO 3166-1 alfa-2 (por ejemplo, `US`, `BR`).
description	`string`	No	Una etiqueta descriptiva para la dirección (por ejemplo, Casa, Oficina o Facturación). Máximo 100 caracteres.

Campos de contacto

Campo	Tipo	Obligatorio	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 (por ejemplo, `+5511999999999`).
otherPhone	`string`	No	Número de teléfono alternativo.

Campos de Persona Natural

Disponibles solo cuando type es NATURAL_PERSON.

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

Campos de Persona Jurídica

Disponibles solo cuando type es LEGAL_PERSON.

Campo	Tipo	Obligatorio	Descripción
tradeName	`string`	No	Nombre comercial.
activity	`string`	No	Actividad de negocio principal.
type	`string`	No	Estructura legal (por ejemplo, LLC, Corporation).
foundingDate	`string`	No	Fecha de fundación de la empresa en formato `YYYY-MM-DD`.
size	`string`	No	Clasificación por tamaño de empresa (por ejemplo, Pequeña, Mediana, Grande).
status	`string`	No	Estado del ciclo de vida (por ejemplo, `Active`, `Inactive`, `Suspended`, `Closed`).

Representante

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

Campo	Tipo	Obligatorio	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 (por ejemplo, CEO, CFO).

Seguridad de los datos

Midaz cifra varios campos del Holder en reposo, incluyendo name, document y los campos de contacto. Esto protege los datos incluso si alguien obtiene acceso al almacenamiento.

Nunca almacenes información sensible en el objeto metadata. Midaz no cifra los metadatos y los almacena en texto plano.

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

Gestión de Holders

A través de la API

Usa la API de CRM para gestionar Holders de forma programática:

Crear un Holder: registra un nuevo Holder en el sistema.
Listar Holders: visualiza todos los Holders con paginación y filtros.
Consultar un Holder: obtén los datos de un Holder específico.
Actualizar un Holder: edita los datos de un Holder existente.
Eliminar un Holder: elimina un Holder mediante un borrado lógico o de forma permanente.

Cada solicitud a la API de CRM incluye el ID de la organización en la ruta de la URL, por ejemplo /organizations/{organization_id}/holders. Si habilitas Access Manager, agrega un encabezado Authorization con un token Bearer.

A través de Lerian Console

Puedes gestionar Holders desde la página Holders del Módulo Midaz en Lerian Console. La Console te permite crear, ver, editar y eliminar Holders sin escribir código. Obtén más información en la guía de gestión de Holders.

Próximos pasos

Cuentas alias

Aprende cómo las cuentas alias vinculan Holders con cuentas del ledger de Midaz.

Usar CRM

Sigue la guía paso a paso para registrar Holders y crear cuentas alias.

Midaz Core

CRM

Fees

Tipos de Holder

Persona Natural

Persona Jurídica

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

Gestión de Holders

A través de la API

A través de Lerian Console

Próximos pasos

Cuentas alias

Usar CRM

​Tipos de Holder

​Persona Natural

​Persona Jurídica

​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

​Gestión de Holders

​A través de la API

​A través de Lerian Console

​Próximos pasos

Cuentas alias

Usar CRM

Tipos de Holder

Persona Natural

Persona Jurídica

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

Gestión de Holders

A través de la API

A través de Lerian Console

Próximos pasos