Holders

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

Para criar e gerenciar holders passo a passo, consulte Primeiros passos com o CRM.

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

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.

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.

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

Para a lista completa de campos protegidos e estratégias de criptografia, consulte Segurança de dados do CRM.

Gerenciando Holders

Via API

Use a API do CRM para gerenciar Holders programaticamente:

Criar um Holder — Registrar um novo Holder no sistema.
Listar Holders — Visualizar todos os Holders com paginação e filtros.
Consultar um Holder — Obter os detalhes de um Holder específico.
Atualizar um Holder — Editar os dados de um Holder existente.
Excluir um Holder — Excluir logicamente ou remover permanentemente um Holder.

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, adicione um header Authorization com um token Bearer.

Via Lerian Console

Você pode gerenciar Holders através da página Holders no Módulo Midaz do 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.

Midaz Core

CRM

Fees

Tipos de Holder

Pessoa Física (Natural Person)

Pessoa Jurídica (Legal Person)

Campos do Holder

Campos principais

Campos de endereço

Campos de contato

Campos de Pessoa Física

Campos de Pessoa Jurídica

Representante

Segurança dos dados

Gerenciando Holders

Via API

Via Lerian Console

Próximos passos

Alias Accounts

Usando o CRM

​Tipos de Holder

​Pessoa Física (Natural Person)

​Pessoa Jurídica (Legal Person)

​Campos do Holder

​Campos principais

​Campos de endereço

​Campos de contato

​Campos de Pessoa Física

​Campos de Pessoa Jurídica

​Representante

​Segurança dos dados

​Gerenciando Holders

​Via API

​Via Lerian Console

​Próximos passos

Alias Accounts

Usando o CRM

Tipos de Holder

Pessoa Física (Natural Person)

Pessoa Jurídica (Legal Person)

Campos do Holder

Campos principais

Campos de endereço

Campos de contato

Campos de Pessoa Física

Campos de Pessoa Jurídica

Representante

Segurança dos dados

Gerenciando Holders

Via API

Via Lerian Console

Próximos passos