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).Documentation Index
Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
Use this file to discover all available pages before exploring further.
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
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 objetoaddresses 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). |
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 cuandotype 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 cuandotype 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 objetorepresentative 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. |
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.
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.