> ## 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 Holders no CRM e vinculá-los a contas do ledger com Instruments por meio da API REST do Midaz.
Este guia mostra como criar e gerenciar **Holders** — os clientes ou empresas por trás das suas contas.
Ele também vincula cada holder a uma conta do ledger com um **Instrument**. Ao final, você terá um holder registrado no CRM e vinculado a uma conta do ledger.
## Pré-requisitos
***
Antes de começar, certifique-se de cumprir os seguintes requisitos:
* Você concluiu o guia de [configuração do Midaz](/pt/midaz/midaz-setup) e todos os serviços estão em execução.
* Pelo menos uma **Organization**, **Ledger** e **Account** já existem, conforme criados no guia [Primeiros passos com o Midaz](/pt/midaz/midaz-getting-started).
* O ledger do Midaz serve os endpoints de holder e instrument. No Midaz v4, o CRM faz parte do binário do ledger, portanto não precisa de um serviço nem de uma porta separada.
Substitua os IDs de exemplo nos exemplos 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 contas do seu ledger.
Ele gerencia duas entidades principais:
* **Holders**: Indivíduos (`NATURAL_PERSON`) ou empresas (`LEGAL_PERSON`) que possuem contas.
* **Instruments**: O vínculo entre um holder e uma conta específica do ledger, com detalhes bancários opcionais.
Esse modelo permite que um único holder possua muitas contas em diferentes ledgers. Ele mantém as informações de identidade e contato em um só lugar.
## Passo 1 — Criar um holder
***
Um **Holder** representa uma pessoa ou empresa no seu sistema. Crie holders para indivíduos (`NATURAL_PERSON`) ou empresas (`LEGAL_PERSON`).
Envie uma requisição `POST` com o tipo, nome, documento, contato e endereço do holder. Para o schema completo de requisição e resposta, consulte [Criar um holder](/pt/reference/midaz/create-a-holder).
```bash theme={null}
curl -X POST http://localhost:3002/v1/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 um indivíduo, defina o tipo como `LEGAL_PERSON`:
```bash theme={null}
curl -X POST http://localhost:3002/v1/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 quando cria instruments.
## Passo 2 — Vincular um holder a uma conta
***
Com o holder criado, vincule-o a uma conta do ledger com um **Instrument**. Um instrument conecta um holder a uma conta dentro de um ledger, com detalhes bancários opcionais.
Para o schema completo de requisição e resposta, consulte [Criar um instrument](/pt/reference/midaz/create-an-instrument).
```bash theme={null}
curl -X POST http://localhost:3002/v1/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"
}
}'
```
## Passo 3 — Consultar e atualizar seus dados
***
Com holders e instruments criados, você pode consultá-los, listá-los e atualizá-los.
| Operação | Endpoint | Referência da API |
| ---------------------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| Consultar um holder | `GET /v1/organizations/{organization_id}/holders/{holder_id}` | [Consultar um holder](/pt/reference/midaz/retrieve-a-holder) |
| Listar todos os holders | `GET /v1/organizations/{organization_id}/holders?limit=10&page=1` | [Listar holders](/pt/reference/midaz/list-holders) |
| Listar instruments de um holder | `GET /v1/organizations/{organization_id}/instruments?holder_id={holder_id}` | [Listar instruments](/pt/reference/midaz/list-instruments) |
| Consultar um instrument específico | `GET /v1/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}` | [Consultar um instrument](/pt/reference/midaz/retrieve-an-instrument) |
| Atualizar um holder | `PATCH /v1/organizations/{organization_id}/holders/{holder_id}` | [Atualizar um holder](/pt/reference/midaz/update-a-holder) |
```bash theme={null}
curl -X PATCH http://localhost:3002/v1/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 que você envia. Todos os outros campos permanecem inalterados.
## Passo 4 — Limpeza
***
Para remover recursos, exclua os instruments primeiro e depois os holders.
| Operação | Endpoint | Referência da API |
| --------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| Excluir um instrument | `DELETE /v1/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}` | [Excluir um instrument](/pt/reference/midaz/delete-an-instrument) |
| Excluir um holder | `DELETE /v1/organizations/{organization_id}/holders/{holder_id}` | [Excluir um holder](/pt/reference/midaz/delete-a-holder) |
Excluir um instrument:
```bash theme={null}
curl -X DELETE http://localhost:3002/v1/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}
```
Excluir um holder:
```bash theme={null}
curl -X DELETE http://localhost:3002/v1/organizations/{organization_id}/holders/{holder_id}
```
## Resumo
***
Neste guia, você:
1. Criou um **Holder** para registrar um indivíduo ou empresa no CRM.
2. Criou um **Instrument** para vincular o holder a uma conta do ledger.
3. Consultou e atualizou dados do CRM.
4. Removeu instruments e holders quando não eram mais necessários.
## Próximos passos
***
Explore filtros avançados, consultas por metadados e todos os endpoints disponíveis.
Gerencie holders por meio de uma interface gráfica.