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 del ledger con un Instrument. Al final, tendrás un holder registrado en el CRM y vinculado a una cuenta del ledger.

Prerrequisitos

Antes de comenzar, asegúrate de cumplir los siguientes requisitos:

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

Reemplaza los IDs de ejemplo en los ejemplos siguientes por los IDs reales de tu entorno.

Componentes del CRM

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

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

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

Paso 1 — Crear un holder

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

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

Ejemplo de holder empresa

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

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

Paso 2 — Vincular un holder a una cuenta

Con el holder creado, vincúlalo a una cuenta del ledger con un Instrument. Un instrument conecta un holder a una cuenta dentro de un ledger, con detalles bancarios opcionales. Para el schema completo de solicitud y respuesta, consulta Crear un instrument.

Ejemplo de solicitud

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

Paso 3 — Consultar y actualizar tus datos

Con holders e instruments creados, puedes consultarlos, listarlos y actualizarlos.

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

Ejemplo de actualización 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"
    }
  }'

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

Paso 4 — Limpieza

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

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

Ejemplos de solicitud

Eliminar un instrument:

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

Eliminar un holder:

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

Resumen

En esta guía:

Creaste un Holder para registrar un individuo o empresa en el CRM.
Creaste un Instrument para vincular el holder a una cuenta del ledger.
Consultaste y actualizaste datos del CRM.
Eliminaste instruments y holders cuando ya no eran necesarios.

Próximos pasos

Referencia de API del CRM

Explora filtros avanzados, consultas por metadatos y todos los endpoints disponibles.

Usando CRM con Midaz Console

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

Midaz Core

CRM

Fees

Primeros pasos con CRM

Prerrequisitos

Componentes del CRM

Paso 1 — Crear un holder

Paso 2 — Vincular un holder a una cuenta

Paso 3 — Consultar y actualizar tus datos

Paso 4 — Limpieza

Resumen

Próximos pasos

Referencia de API del CRM

Usando CRM con Midaz Console

​Prerrequisitos

​Componentes del CRM

​Paso 1 — Crear un holder

​Paso 2 — Vincular un holder a una cuenta

​Paso 3 — Consultar y actualizar tus datos

​Paso 4 — Limpieza

​Resumen

​Próximos pasos

Referencia de API del CRM

Usando CRM con Midaz Console

Prerrequisitos

Componentes del CRM

Paso 1 — Crear un holder

Paso 2 — Vincular un holder a una cuenta

Paso 3 — Consultar y actualizar tus datos

Paso 4 — Limpieza

Resumen

Próximos pasos