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 plugin 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).
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
Pessoa Jurídica (Legal Person)
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
| 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). |
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
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.
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
