Pular para o conteúdo principal
Este guia mostra como criar e gerenciar Holders (clientes ou empresas) e vinculá-los a contas do ledger usando Aliases. Ao final deste guia, você terá um holder registrado no CRM e conectado a uma conta existente no seu ledger do Midaz.

​
Pré-requisitos

Antes de começar, certifique-se de que os seguintes requisitos foram atendidos:
  • 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 serviço CRM está em execução na porta 4003 (iniciado automaticamente com make up).
Nos exemplos abaixo, substitua os UUIDs de exemplo 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.
  • Aliases: 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 múltiplas contas em diferentes ledgers, mantendo informações de identidade e contato centralizadas.

​
Passo 1 — Criar um holder

Um Holder representa uma pessoa ou empresa no seu sistema. Você pode criar holders para indivíduos (NATURAL_PERSON) ou empresas (LEGAL_PERSON). Envie uma requisição POST com o tipo, nome, documento, informações de contato e endereço do holder. Para o schema completo de requisição e resposta, consulte Criar um holder. 
curl -X POST http://localhost:4003/v1/holders \
  -H "Content-Type: application/json" \
  -H "X-Organization-Id: <your-organization-id>" \
  -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:
curl -X POST http://localhost:4003/v1/holders \
  -H "Content-Type: application/json" \
  -H "X-Organization-Id: <your-organization-id>" \
  -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 retornado na resposta. Você vai usá-lo ao criar aliases.

​
Passo 2 — Vincular um holder a uma conta

Com o holder criado, vincule-o a uma conta do ledger criando um Alias. Um alias conecta um holder a uma conta específica dentro de um ledger, com detalhes bancários opcionais. Para o schema completo de requisição e resposta, consulte Criar uma conta alias. 
curl -X POST http://localhost:4003/v1/holders/<holder-id>/aliases \
  -H "Content-Type: application/json" \
  -H "X-Organization-Id: <your-organization-id>" \
  -d '{
    "ledgerId": "<your-ledger-id>",
    "accountId": "<your-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 aliases criados, você pode consultá-los, listá-los e atualizá-los.
OperaçãoEndpointReferência da API
Consultar um holderGET /v1/holders/<holder-id>Consultar um holder
Listar todos os holdersGET /v1/holders?limit=10&page=1Listar holders
Listar aliases de um holderGET /v1/aliases?holder_id=<holder-id>Listar contas alias
Consultar um alias específicoGET /v1/holders/<holder-id>/aliases/<alias-id>Consultar uma conta alias
Atualizar um holderPATCH /v1/holders/<holder-id>Atualizar um holder
curl -X PATCH http://localhost:4003/v1/holders/<holder-id> \
  -H "Content-Type: application/json" \
  -H "X-Organization-Id: <your-organization-id>" \
  -d '{
    "contact": {
      "primaryEmail": "jane.new-email@example.com",
      "mobilePhone": "+15559999999"
    },
    "metadata": {
      "segment": "vip",
      "source": "onboarding"
    }
  }'
Apenas os campos incluídos no corpo da requisição são atualizados. Todos os outros campos permanecem inalterados.

​
Passo 4 — Limpeza

Para remover recursos, exclua os aliases primeiro e depois os holders.
OperaçãoEndpointReferência da API
Excluir um aliasDELETE /v1/holders/<holder-id>/aliases/<alias-id>Excluir uma conta alias
Excluir um holderDELETE /v1/holders/<holder-id>Excluir um holder
Excluir um alias:
curl -X DELETE http://localhost:4003/v1/holders/<holder-id>/aliases/<alias-id> \
  -H "X-Organization-Id: <your-organization-id>"
Excluir um holder:
curl -X DELETE http://localhost:4003/v1/holders/<holder-id> \
  -H "X-Organization-Id: <your-organization-id>"

​
Resumo

Neste guia, você:
  1. Criou um Holder para registrar um indivíduo ou empresa no CRM.
  2. Criou um Alias para vincular o holder a uma conta do ledger.
  3. Consultou e atualizou dados do CRM.
  4. Removeu aliases 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.