Primeiros passos com o CRM

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 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.
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.

Exemplo de titular pessoa física

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"
    }
  }'

Exemplo de titular pessoa jurídica

Para registrar uma empresa em vez de uma pessoa física, defina o tipo como LEGAL_PERSON:

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.

Exemplo de requisição

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
Listar todos os titulares	`GET /v2/organizations/{organization_id}/holders?limit=10&page=1`	Listar titulares
Listar instrumentos de um titular	`GET /v2/organizations/{organization_id}/instruments?holder_id={holder_id}`	Listar instrumentos
Recuperar um instrumento específico	`GET /v2/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}`	Recuperar um instrumento
Atualizar um titular	`PATCH /v2/organizations/{organization_id}/holders/{holder_id}`	Atualizar um titular

Exemplo de atualização de titular

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
Excluir um titular	`DELETE /v2/organizations/{organization_id}/holders/{holder_id}`	Excluir um titular

Exemplos de requisições

Excluir um instrumento:

curl -X DELETE http://localhost:3002/v2/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}

Excluir um titular:

curl -X DELETE http://localhost:3002/v2/organizations/{organization_id}/holders/{holder_id}

Próximos passos

Referência da API do CRM

Explore filtragem avançada, consultas de metadados e todos os endpoints disponíveis.

Usando o CRM com o Console do Midaz

Gerencie titulares por meio de uma interface gráfica.

Midaz Core

CRM

Fees

Primeiros passos com o CRM

Pré-requisitos

Componentes do CRM

Etapa 1: Crie um titular

Etapa 2: Vincule um titular a uma conta

Etapa 3: Consulte e atualize seus dados

Etapa 4: Limpeza dos recursos

Próximos passos

Referência da API do CRM

Usando o CRM com o Console do Midaz

​Pré-requisitos

​Componentes do CRM

​Etapa 1: Crie um titular

​Etapa 2: Vincule um titular a uma conta

​Etapa 3: Consulte e atualize seus dados

​Etapa 4: Limpeza dos recursos

​Próximos passos

Referência da API do CRM

Usando o CRM com o Console do Midaz

Pré-requisitos

Componentes do CRM

Etapa 1: Crie um titular

Etapa 2: Vincule um titular a uma conta

Etapa 3: Consulte e atualize seus dados

Etapa 4: Limpeza dos recursos

Próximos passos