> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Primeros pasos con CRM
> Sigue esta guía para registrar Holders en CRM y vincularlos a cuentas de ledger con Instruments a través de la API REST de Midaz.
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](/es/products/midaz/midaz-setup) 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](/es/products/midaz/midaz-getting-started).
* 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](/es/reference/products/midaz/v2/create-holder).
```bash theme={null}
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"
}
}'
```
Para registrar una empresa en lugar de una persona, establece el tipo en `LEGAL_PERSON`:
```bash theme={null}
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](/es/reference/products/midaz/v2/create-instrument).
```bash theme={null}
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](/es/reference/products/midaz/v2/get-holder-by-id) |
| Listar todos los holders | `GET /v2/organizations/{organization_id}/holders?limit=10&page=1` | [Listar holders](/es/reference/products/midaz/v2/list-holders) |
| Listar instruments de un holder | `GET /v2/organizations/{organization_id}/instruments?holder_id={holder_id}` | [Listar instruments](/es/reference/products/midaz/v2/list-instruments) |
| Recuperar un instrument específico | `GET /v2/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}` | [Recuperar un instrument](/es/reference/products/midaz/v2/get-instrument-by-id) |
| Actualizar un holder | `PATCH /v2/organizations/{organization_id}/holders/{holder_id}` | [Actualizar un holder](/es/reference/products/midaz/v2/update-holder) |
```bash theme={null}
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](/es/reference/products/midaz/v2/delete-instrument) |
| Eliminar un holder | `DELETE /v2/organizations/{organization_id}/holders/{holder_id}` | [Eliminar un holder](/es/reference/products/midaz/v2/delete-holder) |
Eliminar un instrument:
```bash theme={null}
curl -X DELETE http://localhost:3002/v2/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}
```
Eliminar un holder:
```bash theme={null}
curl -X DELETE http://localhost:3002/v2/organizations/{organization_id}/holders/{holder_id}
```
## Próximos pasos
***
Explora el filtrado avanzado, las consultas de metadatos y todos los endpoints disponibles.
Gestiona holders a través de una interfaz gráfica.