> ## 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

> Represente pessoas ou organizações por trás das Contas Midaz e armazene identidade, contato e atributos de conformidade no CRM integrado.

Um **Holder** é a entidade principal no CRM. Ele representa um indivíduo ou organização do mundo real por trás de uma conta do ledger no Midaz. Um Holder armazena atributos de identidade como o nome, o número de documento, os detalhes de contato e os endereços.

O [CRM](/pt/midaz/crm/crm-overview) gerencia os Holders. Os Holders não pertencem ao domínio transacional do ledger. Eles enriquecem as contas do ledger com dados de negócio. Eles não afetam a lógica, a consistência ou o desempenho do ledger.

Cada Holder é de um dos dois tipos: **Pessoa Física** (Natural Person) ou **Pessoa Jurídica** (Legal Person).

<Tip>
  Para criar e gerenciar holders passo a passo, consulte [Primeiros passos com o CRM](/pt/midaz/crm/crm-getting-started).
</Tip>

## Tipos de Holder

***

O tipo de holder controla quais campos estão disponíveis. Ele também define como a plataforma trata a entidade. Você escolhe o tipo na criação. Você **não pode alterá-lo depois**.

### Pessoa Física (Natural Person)

O tipo Pessoa Física representa um cliente individual. Ele suporta atributos pessoais como o nome, o gênero, a data de nascimento, o estado civil, a nacionalidade e as informações familiares.

Use este tipo para:

* Titulares de contas bancárias individuais
* Proprietários de carteiras pessoais
* Autônomos ou microempreendedores individuais

### Pessoa Jurídica (Legal Person)

O tipo Pessoa Jurídica representa uma empresa ou organização. Ele suporta atributos empresariais como o nome fantasia, o tipo de atividade, a data de fundação, o porte da empresa e os detalhes do representante legal.

Use este tipo para:

* Contas de tesouraria corporativa
* Parceiros de negócios e fornecedores
* Clientes institucionais

<Tip>
  Escolha o tipo de holder com cuidado na criação. Você não pode alterá-lo depois. Para usar um tipo diferente, crie um novo Holder.
</Tip>

## Campos do Holder

***

### Campos principais

| Campo          | Tipo       | Obrigatório         | Descrição                                                                                                                 |
| :------------- | :--------- | :------------------ | :------------------------------------------------------------------------------------------------------------------------ |
| **id**         | `uuid`     | Gerado pelo sistema | Identificador único do Holder.                                                                                            |
| **type**       | `enum`     | Sim                 | `NATURAL_PERSON` ou `LEGAL_PERSON`.                                                                                       |
| **name**       | `string`   | Sim                 | Nome completo do indivíduo ou razão social da empresa.                                                                    |
| **document**   | `string`   | Sim                 | Número do documento de identificação (ex.: CPF, CNPJ, passaporte).                                                        |
| **externalId** | `string`   | Não                 | Identificador opcional para mapear o Holder a um sistema externo.                                                         |
| **metadata**   | `object`   | Não                 | Pares chave-valor para dados customizados e não sensíveis. Chaves limitadas a 100 caracteres e valores a 2000 caracteres. |
| **createdAt**  | `datetime` | Gerado pelo sistema | Timestamp de criação (RFC 3339).                                                                                          |
| **updatedAt**  | `datetime` | Gerado pelo sistema | Timestamp da última atualização (RFC 3339).                                                                               |
| **deletedAt**  | `datetime` | Gerado pelo sistema | Timestamp da exclusão lógica, se aplicável (RFC 3339).                                                                    |

### Campos de endereço

O objeto `addresses` suporta até três endereços: `primary`, `additional1` e `additional2`. Cada endereço contém:

| Campo           | Tipo     | Obrigatório | Descrição                                                                                         |
| :-------------- | :------- | :---------- | :------------------------------------------------------------------------------------------------ |
| **line1**       | `string` | Sim         | Linha principal do endereço (rua, número). Máx. 256 caracteres.                                   |
| **line2**       | `string` | Não         | Linha secundária do endereço (apartamento, sala). Máx. 256 caracteres.                            |
| **zipCode**     | `string` | Sim         | CEP ou código postal. Máx. 20 caracteres.                                                         |
| **city**        | `string` | Sim         | Nome da cidade. Máx. 100 caracteres.                                                              |
| **state**       | `string` | Sim         | Estado ou província. Máx. 100 caracteres.                                                         |
| **country**     | `string` | Sim         | Código do país ISO 3166-1 alpha-2 (ex.: `BR`, `US`).                                              |
| **description** | `string` | Não         | Um rótulo descritivo para o endereço (por exemplo, Home, Office ou Billing). Máx. 100 caracteres. |

### Campos de contato

| Campo              | Tipo     | Obrigatório | Descrição                                                     |
| :----------------- | :------- | :---------- | :------------------------------------------------------------ |
| **primaryEmail**   | `string` | Não         | Endereço de e-mail principal.                                 |
| **secondaryEmail** | `string` | Não         | Endereço de e-mail secundário.                                |
| **mobilePhone**    | `string` | Não         | Número de celular com código do país (ex.: `+5511999999999`). |
| **otherPhone**     | `string` | Não         | Número de telefone alternativo.                               |

### Campos de Pessoa Física

Disponíveis apenas quando `type` é `NATURAL_PERSON`.

| Campo            | Tipo     | Obrigatório | Descrição                                                                   |
| :--------------- | :------- | :---------- | :-------------------------------------------------------------------------- |
| **favoriteName** | `string` | Não         | Nome preferido ou apelido.                                                  |
| **socialName**   | `string` | Não         | Nome social (nome com o qual a pessoa se identifica).                       |
| **gender**       | `string` | Não         | Identidade de gênero.                                                       |
| **birthDate**    | `string` | Não         | Data de nascimento no formato `AAAA-MM-DD`.                                 |
| **civilStatus**  | `string` | Não         | Estado civil (ex.: Solteiro, Casado, Divorciado).                           |
| **nationality**  | `string` | Não         | Nacionalidade (ex.: Brasileiro, Americano).                                 |
| **motherName**   | `string` | Não         | Nome completo da mãe.                                                       |
| **fatherName**   | `string` | Não         | Nome completo do pai.                                                       |
| **status**       | `string` | Não         | Status do ciclo de vida (ex.: `Active`, `Inactive`, `Suspended`, `Closed`). |

### Campos de Pessoa Jurídica

Disponíveis apenas quando `type` é `LEGAL_PERSON`.

| Campo            | Tipo     | Obrigatório | Descrição                                                                   |
| :--------------- | :------- | :---------- | :-------------------------------------------------------------------------- |
| **tradeName**    | `string` | Não         | Nome fantasia da empresa.                                                   |
| **activity**     | `string` | Não         | Atividade principal da empresa.                                             |
| **type**         | `string` | Não         | Estrutura jurídica (ex.: LTDA, S.A.).                                       |
| **foundingDate** | `string` | Não         | Data de fundação da empresa no formato `AAAA-MM-DD`.                        |
| **size**         | `string` | Não         | Classificação do porte da empresa (ex.: Pequeno, Médio, Grande).            |
| **status**       | `string` | Não         | Status do ciclo de vida (ex.: `Active`, `Inactive`, `Suspended`, `Closed`). |

#### Representante

O objeto `representative` dentro de `legalPerson` armazena os detalhes do representante legal da empresa:

| Campo        | Tipo     | Obrigatório | Descrição                                |
| :----------- | :------- | :---------- | :--------------------------------------- |
| **name**     | `string` | Não         | Nome completo do representante legal.    |
| **document** | `string` | Não         | Número do documento do representante.    |
| **email**    | `string` | Não         | Endereço de e-mail do representante.     |
| **role**     | `string` | Não         | Cargo dentro da empresa (ex.: CEO, CFO). |

## Segurança dos dados

***

O Midaz criptografa vários campos do Holder em repouso, incluindo `name`, `document` e os campos de contato. Isso protege os dados mesmo se alguém acessar o armazenamento.

<Warning>
  Nunca armazene informações sensíveis no objeto `metadata`. O Midaz não criptografa os metadados e os armazena em texto simples.
</Warning>

Para a lista completa de campos protegidos e estratégias de criptografia, consulte [Segurança de dados do CRM](/pt/midaz/crm/crm-data-security).

## Gerenciando Holders

***

### Via API

Use a API do CRM para gerenciar Holders programaticamente:

* [Criar um Holder](/pt/reference/midaz/crm/create-holder) — Registrar um novo Holder no sistema.
* [Listar Holders](/pt/reference/midaz/crm/list-holders) — Visualizar todos os Holders com paginação e filtros.
* [Consultar um Holder](/pt/reference/midaz/crm/retrieve-holder) — Obter os detalhes de um Holder específico.
* [Atualizar um Holder](/pt/reference/midaz/crm/update-holder) — Editar os dados de um Holder existente.
* [Excluir um Holder](/pt/reference/midaz/crm/delete-holder) — Excluir logicamente ou remover permanentemente um Holder.

<Note>
  Cada requisição à API do CRM inclui o ID da organização na rota da URL, por exemplo `/organizations/{organization_id}/holders`. Se você habilitar o [Access Manager](/pt/platform/access-manager/access-manager), adicione um header `Authorization` com um token Bearer.
</Note>

### Via Lerian Console

Você pode gerenciar Holders através da página **Holders** no Módulo Midaz do [Lerian Console](/pt/platform/console/about-lerian-console). O console oferece uma interface visual para criar, visualizar, editar e excluir Holders sem código.

[**Saiba mais no guia de Gerenciamento de Holders.**](/pt/midaz/console/managing-crm-holders)

## Próximos passos

***

<CardGroup cols={2}>
  <Card title="Alias Accounts" icon="link" href="/pt/midaz/crm/alias-accounts">
    Saiba como as Alias Accounts vinculam Holders a contas do ledger no Midaz.
  </Card>

  <Card title="Usando o CRM" icon="rocket" href="/pt/midaz/crm/crm-using-overview">
    Siga o guia passo a passo para registrar Holders e criar Alias Accounts.
  </Card>
</CardGroup>