> ## 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 el CRM y vincularlos a cuentas del ledger con Instruments mediante 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 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](/es/midaz/midaz-setup) 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](/es/midaz/midaz-getting-started).
* 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](/es/reference/midaz/create-a-holder).
```bash theme={null}
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"
}
}'
```
Para registrar una empresa en lugar de un individuo, establece el tipo como `LEGAL_PERSON`:
```bash theme={null}
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](/es/reference/midaz/create-an-instrument).
```bash theme={null}
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](/es/reference/midaz/retrieve-a-holder) |
| Listar todos los holders | `GET /v1/organizations/{organization_id}/holders?limit=10&page=1` | [Listar holders](/es/reference/midaz/list-holders) |
| Listar instruments de un holder | `GET /v1/organizations/{organization_id}/instruments?holder_id={holder_id}` | [Listar instruments](/es/reference/midaz/list-instruments) |
| Consultar un instrument específico | `GET /v1/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}` | [Consultar un instrument](/es/reference/midaz/retrieve-an-instrument) |
| Actualizar un holder | `PATCH /v1/organizations/{organization_id}/holders/{holder_id}` | [Actualizar un holder](/es/reference/midaz/update-a-holder) |
```bash theme={null}
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](/es/reference/midaz/delete-an-instrument) |
| Eliminar un holder | `DELETE /v1/organizations/{organization_id}/holders/{holder_id}` | [Eliminar un holder](/es/reference/midaz/delete-a-holder) |
Eliminar un instrument:
```bash theme={null}
curl -X DELETE http://localhost:3002/v1/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}
```
Eliminar un holder:
```bash theme={null}
curl -X DELETE http://localhost:3002/v1/organizations/{organization_id}/holders/{holder_id}
```
## Resumen
***
En esta guía:
1. Creaste un **Holder** para registrar un individuo o empresa en el CRM.
2. Creaste un **Instrument** para vincular el holder a una cuenta del ledger.
3. Consultaste y actualizaste datos del CRM.
4. Eliminaste instruments y holders cuando ya no eran necesarios.
## Próximos pasos
***
Explora filtros avanzados, consultas por metadatos y todos los endpoints disponibles.
Gestiona holders a través de una interfaz gráfica.