Primeros pasos con CRM

Esta guía muestra cómo crear y gestionar Holders, los clientes o empresas detrás de tus cuentas. También vincula cada holder a una cuenta de ledger con un Instrument. Al final, tendrás un holder registrado en CRM y vinculado a una cuenta de ledger.

Requisitos previos

Antes de empezar, confirma que cumples con los siguientes requisitos:

Completaste la guía de configuración de Midaz y todos los servicios están en ejecución.
Ya existen al menos una Organization, un Ledger y una Account, creados según la guía de Primeros pasos con Midaz.
El ledger de Midaz atiende los endpoints de holder e instrument. En Midaz v4, CRM forma parte del binario del ledger, por lo que no necesita un servicio ni un puerto separado.

Reemplaza los IDs de marcador de posición en los siguientes ejemplos con los IDs reales de tu entorno.

Componentes de CRM

El componente CRM (Customer Relationship Management) permite registrar a las personas y empresas detrás de tus cuentas de ledger. Gestiona dos entidades centrales:

Holders: personas (NATURAL_PERSON) o empresas (LEGAL_PERSON) que poseen cuentas.
Instruments: el vínculo entre un holder y una cuenta específica del ledger, con datos bancarios opcionales.

Este modelo permite que un holder posea muchas cuentas en distintos ledgers. Mantiene la identidad y la información de contacto en un solo lugar.

Paso 1: Crea un holder

Un Holder representa a una persona o empresa en tu sistema. Crea holders para personas (NATURAL_PERSON) o empresas (LEGAL_PERSON). Envía una solicitud POST con el tipo, nombre, documento, contacto y dirección del holder. Para ver el esquema completo de solicitud y respuesta, consulta Crear un holder.

Ejemplo de holder individual

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

Ejemplo de holder de empresa

Para registrar una empresa en lugar de una persona, establece el tipo en 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"
      }
    }
  }'

Guarda el holderId de la respuesta. Lo usas cuando creas instruments.

Paso 2: Vincula un holder a una cuenta

Una vez que el holder existe, vincúlalo a una cuenta de ledger con un Instrument. Un instrument conecta un holder con una cuenta dentro de un ledger, con datos bancarios opcionales. Para ver el esquema completo de solicitud y respuesta, consulta Crear un instrument.

Ejemplo de solicitud

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

Paso 3: Consulta y actualiza tus datos

Una vez que existen holders e instruments, puedes recuperarlos, listarlos y actualizarlos.

Operación	Endpoint	Referencia de API
Recuperar un holder	`GET /v2/organizations/{organization_id}/holders/{holder_id}`	Recuperar un holder
Listar todos los holders	`GET /v2/organizations/{organization_id}/holders?limit=10&page=1`	Listar holders
Listar instruments de un holder	`GET /v2/organizations/{organization_id}/instruments?holder_id={holder_id}`	Listar instruments
Recuperar un instrument específico	`GET /v2/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}`	Recuperar un instrument
Actualizar un holder	`PATCH /v2/organizations/{organization_id}/holders/{holder_id}`	Actualizar un holder

Ejemplo de actualización de holder

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

La actualización cambia solo los campos que envías. Todos los demás campos permanecen sin cambios.

Paso 4: Limpia los recursos

Para eliminar recursos, elimina primero los instruments y luego los holders.

Operación	Endpoint	Referencia de API
Eliminar un instrument	`DELETE /v2/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}`	Eliminar un instrument
Eliminar un holder	`DELETE /v2/organizations/{organization_id}/holders/{holder_id}`	Eliminar un holder

Ejemplos de solicitudes

Eliminar un instrument:

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

Eliminar un holder:

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

Próximos pasos

Referencia de API de CRM

Explora el filtrado avanzado, las consultas de metadatos y todos los endpoints disponibles.

Uso de CRM con Midaz Console

Gestiona holders a través de una interfaz gráfica.

Midaz Core

CRM

Fees

Primeros pasos con CRM

Requisitos previos

Componentes de CRM

Paso 1: Crea un holder

Paso 2: Vincula un holder a una cuenta

Paso 3: Consulta y actualiza tus datos

Paso 4: Limpia los recursos

Próximos pasos

Referencia de API de CRM

Uso de CRM con Midaz Console

​Requisitos previos

​Componentes de CRM

​Paso 1: Crea un holder

​Paso 2: Vincula un holder a una cuenta

​Paso 3: Consulta y actualiza tus datos

​Paso 4: Limpia los recursos

​Próximos pasos

Referencia de API de CRM

Uso de CRM con Midaz Console

Requisitos previos

Componentes de CRM

Paso 1: Crea un holder

Paso 2: Vincula un holder a una cuenta

Paso 3: Consulta y actualiza tus datos

Paso 4: Limpia los recursos

Próximos pasos