Titulares

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 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. Não afetam a lógica, a consistência nem o desempenho do ledger. Cada Titular é de um dos dois tipos: Pessoa Física (indivíduo) ou Pessoa Jurídica (empresa/organização).

Para criar e gerenciar titulares passo a passo, veja Primeiros passos com o CRM.

Tipos de titular

O tipo de titular controla quais campos ficam 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

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

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`	Sim	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`	Sim	CEP ou código postal. Máximo de 20 caracteres.
city	`string`	Sim	Nome da cidade. Máximo de 100 caracteres.
state	`string`	Sim	Código do estado ou província. Máximo de 100 caracteres.
country	`string`	Sim	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

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 `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.
status	`string`	Não	Status do ciclo de vida (por exemplo, `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.
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).
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.

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.

Gerenciando Titulares

Via API

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

Criar um Titular: registre um novo Titular no sistema.
Listar Titulares: veja todos os Titulares com paginação e filtros.
Recuperar um Titular: obtenha os detalhes de um Titular específico.
Atualizar um Titular: edite os dados de um Titular existente.
Excluir um Titular: faça a exclusão reversível ou remova um Titular permanentemente.

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, 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. O console permite criar, ver, editar e excluir Titulares sem código. Saiba mais no guia Gerenciando Titulares.

Midaz Core

CRM

Fees

Tipos de titular

Pessoa Física

Pessoa Jurídica

Campos do titular

Campos principais

Campos de endereço

Campos de contato

Campos de Pessoa Física

Campos de Pessoa Jurídica

Representante

Segurança de dados

Gerenciando Titulares

Via API

Via Lerian Console

Próximos passos

Contas Alias

Usando o CRM

​Tipos de titular

​Pessoa Física

​Pessoa Jurídica

​Campos do titular

​Campos principais

​Campos de endereço

​Campos de contato

​Campos de Pessoa Física

​Campos de Pessoa Jurídica

​Representante

​Segurança de dados

​Gerenciando Titulares

​Via API

​Via Lerian Console

​Próximos passos

Contas Alias

Usando o CRM

Tipos de titular

Pessoa Física

Pessoa Jurídica

Campos do titular

Campos principais

Campos de endereço

Campos de contato

Campos de Pessoa Física

Campos de Pessoa Jurídica

Representante

Segurança de dados

Gerenciando Titulares

Via API

Via Lerian Console

Próximos passos