Saltar al contenido principal
Esta guía muestra cómo crear y gestionar Holders (clientes o empresas) y vincularlos a cuentas del ledger usando Aliases. Al final de esta guía, tendrá un holder registrado en el CRM y conectado a una cuenta existente en su ledger de Midaz.

​
Prerrequisitos

Antes de comenzar, asegúrese de que se cumplan los siguientes requisitos:
  • Ha completado 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 servicio CRM está en ejecución en el puerto 4003 (iniciado automáticamente con make up).
En los ejemplos a continuación, reemplace los UUIDs de ejemplo con los IDs reales de su entorno.

​
Componentes del CRM

El componente CRM (Customer Relationship Management) le permite registrar las personas y empresas detrás de las cuentas de su ledger. Gestiona dos entidades principales:
  • Holders: Individuos (NATURAL_PERSON) o empresas (LEGAL_PERSON) que poseen cuentas.
  • Aliases: 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 múltiples cuentas en diferentes ledgers, manteniendo la información de identidad y contacto centralizada.

​
Paso 1 — Crear un holder

Un Holder representa una persona o empresa en su sistema. Puede crear holders para individuos (NATURAL_PERSON) o empresas (LEGAL_PERSON). Envíe una solicitud POST con el tipo, nombre, documento, información de contacto y dirección del holder. Para el schema completo de solicitud y respuesta, consulte Crear un 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 una empresa en lugar de un individuo, establezca el 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"
      }
    }
  }'
Guarde el holderId devuelto en la respuesta. Lo usará al crear aliases.

​
Paso 2 — Vincular un holder a una cuenta

Con el holder creado, vincúlelo a una cuenta del ledger creando un Alias. Un alias conecta un holder a una cuenta específica dentro de un ledger, con detalles bancarios opcionales. Para el schema completo de solicitud y respuesta, consulte Crear una cuenta 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"
    }
  }'

​
Paso 3 — Consultar y actualizar sus datos

Con holders y aliases creados, puede consultarlos, listarlos y actualizarlos.
OperaciónEndpointReferencia de API
Consultar un holderGET /v1/holders/<holder-id>Consultar un holder
Listar todos los holdersGET /v1/holders?limit=10&page=1Listar holders
Listar aliases de un holderGET /v1/aliases?holder_id=<holder-id>Listar cuentas alias
Consultar un alias específicoGET /v1/holders/<holder-id>/aliases/<alias-id>Consultar una cuenta alias
Actualizar un holderPATCH /v1/holders/<holder-id>Actualizar un 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"
    }
  }'
Solo los campos incluidos en el cuerpo de la solicitud se actualizan. Todos los demás campos permanecen sin cambios.

​
Paso 4 — Limpieza

Para eliminar recursos, elimine los aliases primero y luego los holders.
OperaciónEndpointReferencia de API
Eliminar un aliasDELETE /v1/holders/<holder-id>/aliases/<alias-id>Eliminar una cuenta alias
Eliminar un holderDELETE /v1/holders/<holder-id>Eliminar un holder
Eliminar un alias:
curl -X DELETE http://localhost:4003/v1/holders/<holder-id>/aliases/<alias-id> \
  -H "X-Organization-Id: <your-organization-id>"
Eliminar un holder:
curl -X DELETE http://localhost:4003/v1/holders/<holder-id> \
  -H "X-Organization-Id: <your-organization-id>"

​
Resumen

En esta guía, usted:
  1. Creó un Holder para registrar un individuo o empresa en el CRM.
  2. Creó un Alias para vincular el holder a una cuenta del ledger.
  3. Consultó y actualizó datos del CRM.
  4. Eliminó aliases y holders cuando ya no eran necesarios.

​
Próximos pasos

Referencia de API del CRM

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

Usando CRM con Midaz Console

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