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

# Titulares

> Modele as pessoas físicas ou organizações por trás das contas do Midaz como Titulares, guardando nomes, documentos, contatos e detalhes de compliance como Pessoa Física ou Pessoa Jurídica.

Um **Titular** é a entidade principal do CRM. Ele representa uma pessoa física ou organização do mundo real por trás de uma conta do ledger do Midaz. Um Titular guarda atributos de identidade como o nome, o número do documento, os dados de contato e os endereços.

O [CRM](https://docs.lerian.studio/pt/products/midaz/crm/crm-overview.md) gerencia os Titulares. Os Titulares não pertencem ao domínio transacional do ledger. Eles enriquecem as contas do ledger com dados de negócio.

Cada Titular é de um dos dois tipos: **Pessoa Física** (indivíduo) ou **Pessoa Jurídica** (empresa/organização).

> [!TIP]
>
> Para criar e gerenciar titulares passo a passo, veja [Primeiros passos com o CRM](https://docs.lerian.studio/pt/products/midaz/crm/crm-getting-started.md).

## Tipos de titular

***

Você escolhe o tipo na criação. Você não pode alterá-lo depois.

### Pessoa Física

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

Use este tipo para:

* Titulares individuais de conta bancária
* Donos de carteira pessoal
* Freelancers ou empresários individuais

### Pessoa Jurídica

O tipo Pessoa Jurídica representa uma empresa ou organização. Ele aceita atributos de negócio 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ócio e fornecedores
* Clientes institucionais

> [!TIP]
>
> Escolha o tipo de titular com cuidado na criação. Você não pode alterá-lo depois. Para usar um tipo diferente, crie um novo Titular.

## Campos do titular

***

### Campos principais

| Campo | Tipo | Obrigatório | Descrição |
| :- | :- | :- | :- |
| **id** | `uuid` | Gerado pelo sistema | Identificador único do Titular. |
| **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 (por exemplo, CPF, CNPJ, passaporte). |
| **externalId** | `string` | Não | Identificador opcional para mapear o Titular a um sistema externo. |
| **metadata** | `object` | Não | Pares chave-valor para dados personalizados e não sensíveis. As chaves ficam limitadas a 100 caracteres e os 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 reversível, se aplicável (RFC 3339). |

### Campos de endereço

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

| Campo | Tipo | Obrigatório | Descrição |
| :- | :- | :- | :- |
| **line1** | `string` | Não | Linha principal do endereço (rua, número). Máximo de 256 caracteres. |
| **line2** | `string` | Não | Linha secundária do endereço (apartamento, sala). Máximo de 256 caracteres. |
| **zipCode** | `string` | Não | CEP ou código postal. Máximo de 20 caracteres. |
| **city** | `string` | Não | Nome da cidade. Máximo de 100 caracteres. |
| **state** | `string` | Não | Código do estado ou província. Máximo de 100 caracteres. |
| **country** | `string` | Não | Código de país ISO 3166-1 alpha-2 (por exemplo, `US`, `BR`). |
| **description** | `string` | Não | Um rótulo descritivo para o endereço (por exemplo, Casa, Escritório ou Cobrança). Máximo de 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 (por exemplo, `+5511999999999`). |
| **otherPhone** | `string` | Não | Número de telefone alternativo. |

### Campos de Pessoa Física

| 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 `YYYY-MM-DD`. |
| **civilStatus** | `string` | Não | Estado civil (por exemplo, Solteiro, Casado, Divorciado). |
| **nationality** | `string` | Não | Nacionalidade (por exemplo, Brasileira, Americana). |
| **motherName** | `string` | Não | Nome completo da mãe. |
| **fatherName** | `string` | Não | Nome completo do pai. |
| **monthlyGrossIncome** | `object` | Não | Renda bruta mensal, com `value`, `currency` e `referenceDate`. Os três são obrigatórios dentro do objeto. |
| **status** | `string` | Não | Status do ciclo de vida (por exemplo, `Active`, `Inactive`, `Suspended`, `Closed`). |

### Campos de Pessoa Jurídica

| Campo | Tipo | Obrigatório | Descrição |
| :- | :- | :- | :- |
| **tradeName** | `string` | Não | Nome fantasia. |
| **activity** | `string` | Não | Atividade principal do negócio. |
| **type** | `string` | Não | Estrutura jurídica (por exemplo, LLC, Corporation). |
| **foundingDate** | `string` | Não | Data de fundação da empresa no formato `YYYY-MM-DD`. |
| **size** | `string` | Não | Classificação de porte da empresa (por exemplo, Pequena, Média, Grande). |
| **annualGrossRevenue** | `object` | Não | Faturamento bruto anual, com `value`, `currency` e `referenceDate`. Os três são obrigatórios dentro do objeto. |
| **totalAssets** | `object` | Não | Ativo total, com `value`, `currency` e `referenceDate`. Os três são obrigatórios dentro do objeto. |
| **status** | `string` | Não | Status do ciclo de vida (por exemplo, `Active`, `Inactive`, `Suspended`, `Closed`). |

#### Representante

O objeto `representative` dentro de `legalPerson` guarda 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 (por exemplo, CEO, CFO). |

## Segurança de dados

***

O Midaz criptografa vários campos do Titular em repouso, incluindo o `name`, o `document` e os campos de contato. Isso protege os dados mesmo que alguém obtenha acesso ao armazenamento.

> [!WARNING]
>
> Nunca guarde informações sensíveis no objeto `metadata`. O Midaz não criptografa metadados e os guarda em texto simples.

Para a lista completa de campos protegidos e estratégias de criptografia, veja [Segurança de dados do CRM](https://docs.lerian.studio/pt/products/midaz/crm/crm-data-security.md).

## Gerenciando Titulares

***

### Via API

Use a API do CRM para gerenciar Titulares de forma programática:

* [Criar um Titular](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-holder.md): registre um novo Titular no sistema.
* [Listar Titulares](https://docs.lerian.studio/pt/reference/products/midaz/v2/list-holders.md): veja todos os Titulares com paginação e filtros.
* [Recuperar um Titular](https://docs.lerian.studio/pt/reference/products/midaz/v2/get-holder-by-id.md): obtenha os detalhes de um Titular específico.
* [Atualizar um Titular](https://docs.lerian.studio/pt/reference/products/midaz/v2/update-holder.md): edite os dados de um Titular existente.
* [Excluir um Titular](https://docs.lerian.studio/pt/reference/products/midaz/v2/delete-holder.md): faça a exclusão reversível ou remova um Titular permanentemente. O Midaz recusa enquanto o Titular ainda tem Instrumentos ou contas que carregam o ID dele.

> [!NOTE]
>
> Toda requisição à API do CRM inclui o ID da organização no caminho da URL, por exemplo `/organizations/{organization_id}/holders`. Se você habilitar o [Access Manager](https://docs.lerian.studio/pt/platform/access-manager.md), adicione um cabeçalho `Authorization` com um token Bearer.

### Via Lerian Console

Você pode gerenciar Titulares pela página **Titulares** no Módulo Midaz do [Lerian Console](https://docs.lerian.studio/pt/platform/console/about-lerian-console.md). O console permite criar, ver, editar e excluir Titulares sem código.

[**Saiba mais no guia Gerenciando Titulares.**](https://docs.lerian.studio/pt/products/midaz/console/managing-crm-holders)

## Próximos passos

***

> [card] [Instrumentos](https://docs.lerian.studio/pt/products/midaz/crm/alias-accounts.md)
>
> Aprenda como os Instrumentos vinculam Titulares a contas do ledger do Midaz.

> [card] [Usando o CRM](https://docs.lerian.studio/pt/products/midaz/crm/crm-using-overview.md)
>
> Siga o guia passo a passo para cadastrar Titulares e criar Instrumentos.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.