> ## 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.
# Primeiros passos com o CRM
> Siga este guia para registrar Titulares no CRM e vinculá-los a contas do ledger com Instrumentos por meio da API REST do Midaz.
Este guia mostra como criar e gerenciar **Titulares** — os clientes ou empresas por trás das suas contas.
Ele também vincula cada titular a uma conta do ledger com um **Instrumento**. Ao final, você tem um titular registrado no CRM e vinculado a uma conta do ledger.
## Pré-requisitos
***
Antes de começar, confirme que você atende aos seguintes requisitos:
* Você concluiu o guia [Configuração do Midaz](/pt/products/midaz/midaz-setup) e todos os serviços estão em execução.
* Pelo menos uma **Organização**, um **Ledger** e uma **Conta** já existem, conforme criados no guia [Primeiros passos com o Midaz](/pt/products/midaz/midaz-getting-started).
* O ledger Midaz disponibiliza os endpoints de titular e instrumento. No Midaz v4, o CRM faz parte do binário do ledger, então não precisa de um serviço ou porta separados.
Substitua os IDs de exemplo abaixo pelos IDs reais do seu ambiente.
## Componentes do CRM
***
O componente CRM (Customer Relationship Management) permite registrar as pessoas e empresas por trás das suas contas do ledger.
Ele gerencia duas entidades principais:
* **Titulares**: pessoas físicas (`NATURAL_PERSON`) ou empresas (`LEGAL_PERSON`) que possuem contas.
* **Instrumentos**: o vínculo entre um titular e uma conta específica do ledger, com dados bancários opcionais.
Esse modelo permite que um titular possua várias contas em diferentes ledgers. Ele mantém as informações de identidade e contato em um único lugar.
## Etapa 1: Crie um titular
***
Um **Titular** representa uma pessoa ou empresa no seu sistema. Crie titulares para pessoas físicas (`NATURAL_PERSON`) ou empresas (`LEGAL_PERSON`).
Envie uma requisição `POST` com o tipo, nome, documento, contato e endereço do titular. Para o esquema completo de requisição e resposta, consulte [Criar um titular](/pt/reference/products/midaz/v2/create-holder).
```bash theme={null}
curl -X POST http://localhost:3002/v2/organizations/{organization_id}/holders \
-H "Content-Type: application/json" \
-d '{
"type": "NATURAL_PERSON",
"name": "Jane Smith",
"document": "12345678900",
"contact": {
"primaryEmail": "jane.smith@example.com",
"mobilePhone": "+15551234567"
},
"addresses": {
"primary": {
"line1": "123 Main Street",
"line2": "Apt 4B",
"city": "New York",
"state": "NY",
"zipCode": "10001",
"country": "US",
"description": "Home address"
}
},
"naturalPerson": {
"favoriteName": "Jane",
"birthDate": "1990-05-15",
"nationality": "American"
},
"metadata": {
"segment": "premium",
"source": "onboarding"
}
}'
```
Para registrar uma empresa em vez de uma pessoa física, defina o tipo como `LEGAL_PERSON`:
```bash theme={null}
curl -X POST http://localhost:3002/v2/organizations/{organization_id}/holders \
-H "Content-Type: application/json" \
-d '{
"type": "LEGAL_PERSON",
"name": "Acme Corp Ltd",
"document": "12345678000199",
"contact": {
"primaryEmail": "finance@acmecorp.com",
"mobilePhone": "+15559876543"
},
"legalPerson": {
"tradeName": "Acme Corp",
"activity": "Financial services",
"type": "Limited Liability",
"foundingDate": "2015-03-20",
"size": "Medium",
"status": "Active",
"representative": {
"name": "Bob Johnson",
"document": "98765432100",
"email": "bob@acmecorp.com",
"role": "CFO"
}
}
}'
```
Salve o `holderId` da resposta. Você o usa ao criar instrumentos.
## Etapa 2: Vincule um titular a uma conta
***
Depois que o titular existe, vincule-o a uma conta do ledger com um **Instrumento**. Um instrumento conecta um titular a uma conta dentro de um ledger, com dados bancários opcionais.
Para o esquema completo de requisição e resposta, consulte [Criar um instrumento](/pt/reference/products/midaz/v2/create-instrument).
```bash theme={null}
curl -X POST http://localhost:3002/v2/organizations/{organization_id}/holders/{holder_id}/instruments \
-H "Content-Type: application/json" \
-d '{
"ledgerId": "{ledger_id}",
"accountId": "{account_id}",
"bankingDetails": {
"branch": "0001",
"account": "123450",
"type": "CACC",
"openingDate": "2025-01-15",
"countryCode": "US",
"bankId": "12345"
},
"metadata": {
"isPrimary": "true"
}
}'
```
## Etapa 3: Consulte e atualize seus dados
***
Depois que titulares e instrumentos existem, você pode recuperá-los, listá-los e atualizá-los.
| Operação | Endpoint | Referência da API |
| ----------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| Recuperar um titular | `GET /v2/organizations/{organization_id}/holders/{holder_id}` | [Recuperar um titular](/pt/reference/products/midaz/v2/get-holder-by-id) |
| Listar todos os titulares | `GET /v2/organizations/{organization_id}/holders?limit=10&page=1` | [Listar titulares](/pt/reference/products/midaz/v2/list-holders) |
| Listar instrumentos de um titular | `GET /v2/organizations/{organization_id}/instruments?holder_id={holder_id}` | [Listar instrumentos](/pt/reference/products/midaz/v2/list-instruments) |
| Recuperar um instrumento específico | `GET /v2/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}` | [Recuperar um instrumento](/pt/reference/products/midaz/v2/get-instrument-by-id) |
| Atualizar um titular | `PATCH /v2/organizations/{organization_id}/holders/{holder_id}` | [Atualizar um titular](/pt/reference/products/midaz/v2/update-holder) |
```bash theme={null}
curl -X PATCH http://localhost:3002/v2/organizations/{organization_id}/holders/{holder_id} \
-H "Content-Type: application/json" \
-d '{
"contact": {
"primaryEmail": "jane.new-email@example.com",
"mobilePhone": "+15559999999"
},
"metadata": {
"segment": "vip",
"source": "onboarding"
}
}'
```
A atualização altera apenas os campos enviados. Todos os outros campos permanecem inalterados.
## Etapa 4: Limpeza dos recursos
***
Para remover recursos, exclua primeiro os instrumentos e depois os titulares.
| Operação | Endpoint | Referência da API |
| ---------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Excluir um instrumento | `DELETE /v2/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}` | [Excluir um instrumento](/pt/reference/products/midaz/v2/delete-instrument) |
| Excluir um titular | `DELETE /v2/organizations/{organization_id}/holders/{holder_id}` | [Excluir um titular](/pt/reference/products/midaz/v2/delete-holder) |
Excluir um instrumento:
```bash theme={null}
curl -X DELETE http://localhost:3002/v2/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}
```
Excluir um titular:
```bash theme={null}
curl -X DELETE http://localhost:3002/v2/organizations/{organization_id}/holders/{holder_id}
```
## Próximos passos
***
Explore filtragem avançada, consultas de metadados e todos os endpoints disponíveis.
Gerencie titulares por meio de uma interface gráfica.