> ## 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.
# Holders
> Modela a las personas u organizaciones detrás de las cuentas de Midaz como Holders, almacenando nombres, documentos, contactos y datos de cumplimiento como Persona Natural o Persona Jurídica.
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](/es/products/midaz/crm/crm-overview) 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](/es/products/midaz/crm/crm-getting-started).
## 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](/es/products/midaz/crm/crm-data-security).
## 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](/es/reference/products/midaz/v2/create-holder): registra un nuevo Holder en el sistema.
* [Listar Holders](/es/reference/products/midaz/v2/list-holders): visualiza todos los Holders con paginación y filtros.
* [Consultar un Holder](/es/reference/products/midaz/v2/get-holder-by-id): obtén los datos de un Holder específico.
* [Actualizar un Holder](/es/reference/products/midaz/v2/update-holder): edita los datos de un Holder existente.
* [Eliminar un Holder](/es/reference/products/midaz/v2/delete-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](/es/platform/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](/es/platform/console/about-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.**](/es/products/midaz/console/managing-crm-holders)
## Próximos pasos
***
Aprende cómo las cuentas alias vinculan Holders con cuentas del ledger de Midaz.
Sigue la guía paso a paso para registrar Holders y crear cuentas alias.