Pular para o conteúdo principal
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, armazenando atributos relacionados à identidade, como nome, número de documento, detalhes de contato e endereços. Os Holders são gerenciados pelo CRM e não pertencem ao domínio transacional do ledger. Eles enriquecem as contas do ledger com dados relevantes para o negócio sem interferir na lógica, consistência ou desempenho do ledger. Cada Holder é de um dos dois tipos: Pessoa Física (Natural Person) ou Pessoa Jurídica (Legal Person).
Para um passo a passo sobre como criar e gerenciar holders, consulte Primeiros passos com o CRM.

​
Tipos de Holder

O tipo de holder determina quais campos estão disponíveis e como a entidade é tratada pela plataforma. Ele é definido na criação e não pode ser alterado posteriormente.

​
Pessoa Física (Natural Person)

Representa um cliente individual. Suporta atributos pessoais como nome, gênero, data de nascimento, estado civil, nacionalidade e informações familiares. Use este tipo para:
  • Titulares de contas bancárias individuais
  • Proprietários de carteiras pessoais
  • Autônomos ou microempreendedores individuais
Representa uma empresa ou organização. Suporta atributos empresariais como nome fantasia, tipo de atividade, data de fundação, porte da empresa e 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. Uma vez definido, ele não pode ser alterado — seria necessário criar um novo Holder com o tipo correto.

​
Campos do Holder

​
Campos principais

CampoTipoObrigatórioDescrição
iduuidGerado pelo sistemaIdentificador único do Holder.
typeenumSimNATURAL_PERSON ou LEGAL_PERSON.
namestringSimNome completo do indivíduo ou razão social da empresa.
documentstringSimNúmero do documento de identificação (ex.: CPF, CNPJ, passaporte).
externalIdstringNãoIdentificador opcional para mapear o Holder a um sistema externo.
metadataobjectNãoPares chave-valor para dados customizados e não sensíveis. Chaves limitadas a 100 caracteres e valores a 2000 caracteres.
createdAtdatetimeGerado pelo sistemaTimestamp de criação (RFC 3339).
updatedAtdatetimeGerado pelo sistemaTimestamp da última atualização (RFC 3339).
deletedAtdatetimeGerado pelo sistemaTimestamp 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:
CampoTipoObrigatórioDescrição
line1stringSimLinha principal do endereço (rua, número). Máx. 256 caracteres.
line2stringNãoLinha secundária do endereço (apartamento, sala). Máx. 256 caracteres.
zipCodestringSimCEP ou código postal. Máx. 20 caracteres.
citystringSimNome da cidade. Máx. 100 caracteres.
statestringSimEstado ou província. Máx. 100 caracteres.
countrystringSimCódigo do país ISO 3166-1 alpha-2 (ex.: BR, US).

​
Campos de contato

CampoTipoObrigatórioDescrição
primaryEmailstringNãoEndereço de e-mail principal.
secondaryEmailstringNãoEndereço de e-mail secundário.
mobilePhonestringNãoNúmero de celular com código do país (ex.: +5511999999999).
otherPhonestringNãoNúmero de telefone alternativo.

​
Campos de Pessoa Física

Disponíveis apenas quando type é NATURAL_PERSON.
CampoTipoObrigatórioDescrição
favoriteNamestringNãoNome preferido ou apelido.
socialNamestringNãoNome social (nome com o qual a pessoa se identifica).
genderstringNãoIdentidade de gênero.
birthDatestringNãoData de nascimento no formato AAAA-MM-DD.
civilStatusstringNãoEstado civil (ex.: Solteiro, Casado, Divorciado).
nationalitystringNãoNacionalidade (ex.: Brasileiro, Americano).
motherNamestringNãoNome completo da mãe.
fatherNamestringNãoNome completo do pai.
statusstringNãoStatus do ciclo de vida (ex.: Active, Inactive, Suspended, Closed).

​
Campos de Pessoa Jurídica

Disponíveis apenas quando type é LEGAL_PERSON.
CampoTipoObrigatórioDescrição
tradeNamestringNãoNome fantasia da empresa.
activitystringNãoAtividade principal da empresa.
typestringNãoEstrutura jurídica (ex.: LTDA, S.A.).
foundingDatestringNãoData de fundação da empresa no formato AAAA-MM-DD.
sizestringNãoClassificação do porte da empresa (ex.: Pequeno, Médio, Grande).
statusstringNãoStatus do ciclo de vida (ex.: Active, Inactive, Suspended, Closed).

​
Representante

O objeto representative dentro de legalPerson armazena os detalhes do representante legal da empresa:
CampoTipoObrigatórioDescrição
namestringNãoNome completo do representante legal.
documentstringNãoNúmero do documento do representante.
emailstringNãoEndereço de e-mail do representante.
rolestringNãoCargo dentro da empresa (ex.: CEO, CFO).

​
Segurança dos dados

Vários campos do Holder são criptografados em repouso usando criptografia AES, incluindo name, document e informações de contato. Isso garante que dados pessoais sensíveis estejam protegidos mesmo se o armazenamento subjacente for comprometido.
Nunca armazene informações sensíveis no objeto metadata. Os metadados não são criptografados e são armazenados 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:
Todas as requisições à API do CRM requerem o header X-Organization-Id. Se o Access Manager estiver habilitado, um header Authorization com um token Bearer também é necessário.

​
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 escrever código. Saiba mais no guia de Gerenciamento de Holders.

​
Próximos passos

Alias Accounts

Saiba como as Alias Accounts vinculam Holders a contas do ledger no Midaz.

Usando o CRM

Siga o guia passo a passo para registrar Holders e criar Alias Accounts.