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 el plugin 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).
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). |
| 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.
Gestionando Holders
Vía API
Usa la API del CRM para gestionar Holders programáticamente:
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
