> ## 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](https://docs.lerian.studio/pt/products/midaz/midaz-setup.md) 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](https://docs.lerian.studio/pt/products/midaz/midaz-getting-started.md). * 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. > [!NOTE] > > 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](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-holder.md). > [accordion] Exemplo de titular pessoa física > > ```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" > } > }' > ``` > [accordion] Exemplo de titular pessoa jurídica > > 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" > } > } > }' > ``` > [!TIP] > > Salve o `id` 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](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-instrument.md). > [accordion] Exemplo de requisição > > ```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](https://docs.lerian.studio/pt/reference/products/midaz/v2/get-holder-by-id.md) | | Listar todos os titulares | `GET /v2/organizations/{organization_id}/holders?limit=10&page=1` | [Listar titulares](https://docs.lerian.studio/pt/reference/products/midaz/v2/list-holders.md) | | Listar instrumentos de um titular | `GET /v2/organizations/{organization_id}/instruments?holder_id={holder_id}` | [Listar instrumentos](https://docs.lerian.studio/pt/reference/products/midaz/v2/list-instruments.md) | | Recuperar um instrumento específico | `GET /v2/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}` | [Recuperar um instrumento](https://docs.lerian.studio/pt/reference/products/midaz/v2/get-instrument-by-id.md) | | Atualizar um titular | `PATCH /v2/organizations/{organization_id}/holders/{holder_id}` | [Atualizar um titular](https://docs.lerian.studio/pt/reference/products/midaz/v2/update-holder.md) | > [accordion] Exemplo de atualização de titular > > ```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" > } > }' > ``` ## Etapa 4: Limpeza dos recursos *** Para remover recursos, exclua primeiro os instrumentos e depois os titulares. O Midaz recusa a exclusão de um titular que ainda tem instrumentos ou contas que carregam o ID dele. | Operação | Endpoint | Referência da API | | - | - | - | | Excluir um instrumento | `DELETE /v2/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}` | [Excluir um instrumento](https://docs.lerian.studio/pt/reference/products/midaz/v2/delete-instrument.md) | | Excluir um titular | `DELETE /v2/organizations/{organization_id}/holders/{holder_id}` | [Excluir um titular](https://docs.lerian.studio/pt/reference/products/midaz/v2/delete-holder.md) | > [accordion] Exemplos de requisições > > 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 *** > [card] [Referência da API do CRM](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-holder.md) > > Explore filtragem avançada, consultas de metadados e todos os endpoints disponíveis. > [card] [Usando o CRM com o Console do Midaz](https://docs.lerian.studio/pt/products/midaz/crm/using-crm-with-midaz-console.md) > > Gerencie titulares por meio de uma interface gráfica. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.