Primeiros passos com o CRM

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

Exemplo de holder individual

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

Exemplo de holder empresa

Para registrar uma empresa em vez de um indivíduo, defina o tipo como LEGAL_PERSON:

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.

Exemplo de requisição

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
Listar todos os holders	`GET /v1/organizations/{organization_id}/holders?limit=10&page=1`	Listar holders
Listar instruments de um holder	`GET /v1/organizations/{organization_id}/instruments?holder_id={holder_id}`	Listar instruments
Consultar um instrument específico	`GET /v1/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}`	Consultar um instrument
Atualizar um holder	`PATCH /v1/organizations/{organization_id}/holders/{holder_id}`	Atualizar um holder

Exemplo de atualização de holder

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

Exemplos de requisição

Excluir um instrument:

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

Excluir um holder:

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

Resumo

Neste guia, você:

Criou um Holder para registrar um indivíduo ou empresa no CRM.
Criou um Instrument para vincular o holder a uma conta do ledger.
Consultou e atualizou dados do CRM.
Removeu instruments e holders quando não eram mais necessários.

Próximos passos

Referência da API do CRM

Explore filtros avançados, consultas por metadados e todos os endpoints disponíveis.

Usando o CRM com o Midaz Console

Gerencie holders por meio de uma interface gráfica.

Midaz Core

CRM

Fees

Primeiros passos com o CRM

Pré-requisitos

Componentes do CRM

Passo 1 — Criar um holder

Passo 2 — Vincular um holder a uma conta

Passo 3 — Consultar e atualizar seus dados

Passo 4 — Limpeza

Resumo

Próximos passos

Referência da API do CRM

Usando o CRM com o Midaz Console

​Pré-requisitos

​Componentes do CRM

​Passo 1 — Criar um holder

​Passo 2 — Vincular um holder a uma conta

​Passo 3 — Consultar e atualizar seus dados

​Passo 4 — Limpeza

​Resumo

​Próximos passos

Referência da API do CRM

Usando o CRM com o Midaz Console

Pré-requisitos

Componentes do CRM

Passo 1 — Criar um holder

Passo 2 — Vincular um holder a uma conta

Passo 3 — Consultar e atualizar seus dados

Passo 4 — Limpeza

Resumo

Próximos passos