> ## 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.

# Migrando desde CRM standalone

> Guía completa para migrar del deployment standalone plugin-crm al componente CRM integrado en Midaz, con pasos, mapeos de datos y validaciones por etapa.

A partir de **Midaz v3.5.0** y **Helm Chart v5.x**, el CRM ya no se despliega como un plugin standalone. Ahora está integrado directamente en el monorepo y Helm chart de Midaz como un componente embebido.

Esta guía explica cómo migrar desde el deployment standalone `plugin-crm` al CRM integrado.

<Info>
  Si estás iniciando un **nuevo deployment de Midaz** (v5.x+), no necesitas esta guía. Simplemente habilita el CRM en tus valores de Helm como se describe en [Deploy de Midaz usando Helm](/es/platform/helm/midaz/midaz-installation). El CRM integrado es ahora el único modelo de deployment soportado.
</Info>

## Qué cambió

***

El plugin CRM era originalmente mantenido como un **codebase separado** con su propio ciclo de release y desplegado independientemente a través de un Helm chart dedicado (`plugin-crm`) en el namespace `midaz-plugins`.

A partir de **Midaz v3.5.0-beta.12** (diciembre 2025), el CRM fue incorporado al monorepo de Midaz en `components/crm/`. Su deployment fue entonces consolidado en el Helm chart principal de Midaz a partir de **v5.x**.

### Comparación de arquitectura

| Aspecto            | Standalone (v4.x y anterior)        | Integrado (v5.x+)                               |
| :----------------- | :---------------------------------- | :---------------------------------------------- |
| **Código fuente**  | Repositorio separado                | `components/crm/` en el monorepo de Midaz       |
| **Helm chart**     | `plugin-crm` (chart dedicado)       | Parte del chart `midaz`                         |
| **Namespace**      | `midaz-plugins`                     | `midaz`                                         |
| **Versionamiento** | Ciclo de release independiente      | Sigue la versión del Midaz core                 |
| **MongoDB**        | Configuración de conexión propia    | MongoDB compartido con otros servicios de Midaz |
| **Instalación**    | `helm install plugin-crm oci://...` | `crm.enabled: true` en los values de Midaz      |
| **Puerto**         | 4003                                | 4003 (sin cambio)                               |

### Cambios en la API

La API del CRM permanece **totalmente retrocompatible**. Todos los endpoints disponibles en la versión standalone continúan funcionando de la misma forma en el deployment integrado.

| Recurso              | Endpoints                                                 | Estado                           |
| :------------------- | :-------------------------------------------------------- | :------------------------------- |
| **Holders**          | POST, GET (lista), GET (por ID), PATCH, DELETE            | Sin cambio                       |
| **Aliases**          | POST, GET (lista por holder), GET (por ID), PATCH, DELETE | Sin cambio                       |
| **Aliases (global)** | GET `/v1/aliases` (lista entre todos los holders)         | Sin cambio                       |
| **Related Parties**  | DELETE                                                    | Agregado en la versión integrada |

<Tip>
  El endpoint `GET /v1/aliases` permite listar aliases de todos los holders con filtros avanzados. Los filtros incluyen `holder_id`, `account_id`, `ledger_id`, `document`, datos bancarios, campos regulatorios y atributos de related parties.

  Este endpoint complementa los endpoints con alcance de holder bajo `/v1/holders/{holder_id}/aliases`.
</Tip>

<Note>
  El endpoint `DELETE /v1/holders/{holder_id}/aliases/{alias_id}/related-parties/{related_party_id}` fue introducido con el CRM integrado.

  Si anteriormente necesitabas eliminar related parties individualmente, esta operación ahora es soportada directamente. En versiones anteriores, era necesario actualizar el payload del alias sin la related party.
</Note>

### Qué permanece igual

* **Contrato de la API**: Todos los endpoints existentes, schemas de request y response y comportamientos permanecen sin cambios.
* **Base de datos**: MongoDB sigue siendo el backend de almacenamiento.
* **Autenticación**: La integración con Access Manager funciona de la misma forma (`PLUGIN_AUTH_ENABLED`, `PLUGIN_AUTH_HOST`).
* **Claves de encriptación**: `LCRYPTO_HASH_SECRET_KEY` y `LCRYPTO_ENCRYPT_SECRET_KEY` siguen siendo obligatorias.
* **Puerto por defecto**: El CRM continúa ejecutándose en el puerto 4003.

## Checklist pre-migración

***

Antes de iniciar la migración, confirma lo siguiente:

<Steps>
  <Step>
    **Identifica tu versión standalone actual**

    <CodeGroup>
      ```bash Shell theme={null}
      helm list -n midaz-plugins
      ```
    </CodeGroup>

    Registra la versión del chart `plugin-crm` y la versión de la aplicación.
  </Step>

  <Step>
    **Haz backup de tus valores Helm actuales**

    <CodeGroup>
      ```bash Shell theme={null}
      helm get values plugin-crm -n midaz-plugins > plugin-crm-values-backup.yaml
      ```
    </CodeGroup>
  </Step>

  <Step>
    **Haz backup de tus datos MongoDB**

    <CodeGroup>
      ```bash Shell theme={null}
      # Encuentra el pod de MongoDB en el namespace midaz-plugins
      kubectl get pods -n midaz-plugins -l app=mongodb

      # Exporta la base de datos del CRM
      kubectl exec -n midaz-plugins <mongodb-pod> -- \
        mongodump --db crm --archive=/tmp/crm-backup.archive

      # Copia el backup localmente
      kubectl cp midaz-plugins/<mongodb-pod>:/tmp/crm-backup.archive ./crm-backup.archive
      ```
    </CodeGroup>
  </Step>

  <Step>
    **Verifica que tu chart de Midaz sea v5.x o superior**

    <CodeGroup>
      ```bash Shell theme={null}
      helm list -n midaz
      ```
    </CodeGroup>

    Si estás en v4.x o anterior, actualiza Midaz primero usando la guía [Actualizando Helm](/es/platform/helm/midaz/midaz-upgrade-guide).
  </Step>

  <Step>
    **Programa una ventana de mantenimiento**

    El CRM estará temporalmente indisponible durante la migración. Planifica una breve ventana de indisponibilidad.
  </Step>
</Steps>

## Pasos de migración

***

### Paso 1 — Habilita el CRM en el chart de Midaz

Agrega la configuración del CRM a tus valores Helm de Midaz:

<CodeGroup>
  ```yaml values.yaml theme={null}
  crm:
    enabled: true
    configmap:
      MONGO_HOST: "midaz-mongodb.midaz.svc.cluster.local."
      MONGO_NAME: "crm"
      MONGO_USER: "midaz"
      MONGO_PORT: "27017"
    secrets:
      MONGO_PASSWORD: "<tu-contraseña-mongodb>"
      LCRYPTO_HASH_SECRET_KEY: "<tu-clave-hash-existente>"
      LCRYPTO_ENCRYPT_SECRET_KEY: "<tu-clave-encrypt-existente>"
  ```
</CodeGroup>

<Warning>
  Usa las **mismas claves de encriptación** (`LCRYPTO_HASH_SECRET_KEY` y `LCRYPTO_ENCRYPT_SECRET_KEY`) usadas en el deployment standalone. Claves diferentes harán que los datos encriptados existentes sean ilegibles.
</Warning>

Si usas external secrets:

<CodeGroup>
  ```yaml values.yaml theme={null}
  crm:
    enabled: true
    useExistingSecret: true
    existingSecretName: "crm-secrets"
  ```
</CodeGroup>

### Paso 2 — Migra tus datos MongoDB

Si tu CRM standalone usaba su propia instancia MongoDB, restaura los datos en el MongoDB gestionado por Midaz.

<CodeGroup>
  ```bash Shell theme={null}
  # Copia el backup al pod de MongoDB de Midaz
  kubectl cp ./crm-backup.archive midaz/<midaz-mongodb-pod>:/tmp/crm-backup.archive

  # Restaura la base de datos del CRM
  kubectl exec -n midaz <midaz-mongodb-pod> -- \
    mongorestore --archive=/tmp/crm-backup.archive --db crm --drop
  ```
</CodeGroup>

<Tip>
  Si el CRM standalone y el integrado ya usan la **misma instancia MongoDB**, puedes saltar este paso. Solo confirma que `MONGO_HOST` y `MONGO_NAME` coincidan.
</Tip>

### Paso 3 — Deploy del CRM integrado

<CodeGroup>
  ```bash Shell theme={null}
  helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
    --version 5.x.x \
    -n midaz \
    -f your-values.yaml
  ```
</CodeGroup>

### Paso 4 — Verifica que el CRM integrado está ejecutándose

<CodeGroup>
  ```bash Shell theme={null}
  # Verifica el estado del pod
  kubectl get pods -n midaz -l app=crm

  # Verifica los logs
  kubectl logs -n midaz deployment/midaz-crm

  # Prueba el endpoint de health (ejecuta port-forward en una terminal separada)
  kubectl port-forward -n midaz svc/midaz-crm 4003:4003 &
  curl http://localhost:4003/health
  ```
</CodeGroup>

### Paso 5 — Valida tus datos

Ejecuta una validación rápida para confirmar que tus datos fueron migrados correctamente.

<CodeGroup>
  ```bash Shell theme={null}
  # Lista holders a través del CRM integrado
  curl -H "X-Organization-Id: <tu-org-id>" \
    http://localhost:4003/v1/holders

  # Verifica un holder específico
  curl -H "X-Organization-Id: <tu-org-id>" \
    http://localhost:4003/v1/holders/<holder-id-conocido>
  ```
</CodeGroup>

Compara los resultados con el deployment standalone.

### Paso 6 — Actualiza DNS e ingress

Actualiza tus registros DNS o reglas de ingress para apuntar al servicio CRM en el namespace `midaz`.

<CodeGroup>
  ```yaml ingress-example.yaml theme={null}
  # El nombre del servicio CRM cambia respecto al chart standalone
  # Anterior: plugin-crm.midaz-plugins.svc.cluster.local
  # Nuevo: midaz-crm.midaz.svc.cluster.local
  ```
</CodeGroup>

### Paso 7 — Elimina el CRM standalone

Después de confirmar que todo funciona como se espera, elimina el deployment standalone.

<CodeGroup>
  ```bash Shell theme={null}
  helm uninstall plugin-crm -n midaz-plugins
  ```
</CodeGroup>

<Danger>
  Solo desinstala el CRM standalone **después de validar el deployment integrado**. Esta operación elimina el deployment standalone y sus recursos.
</Danger>

Si el namespace `midaz-plugins` ya no es necesario, puedes opcionalmente eliminarlo.

<CodeGroup>
  ```bash Shell theme={null}
  kubectl delete namespace midaz-plugins
  ```
</CodeGroup>

## Permisos del Access Manager

***

Los permisos del Access Manager permanecen sin cambios después de la migración.

El nombre de la aplicación continúa siendo `plugin-crm`, y los permisos se aplican a los recursos `holders` y `aliases`.

| Permiso                             | Descripción         | Recursos         | Métodos Permitidos       |
| :---------------------------------- | :------------------ | :--------------- | :----------------------- |
| `plugin-crm-editor-permission`      | Acceso total        | holders, aliases | post, get, patch, delete |
| `plugin-crm-contributor-permission` | Lectura y escritura | holders, aliases | post, get, patch         |
| `plugin-crm-viewer-permission`      | Solo lectura        | holders, aliases | get                      |

No se requieren actualizaciones en tu configuración del Access Manager.

## Procedimiento de rollback

***

Si necesitas revertir al CRM standalone:

<Steps>
  <Step>
    Deshabilita el CRM en el chart de Midaz:

    <CodeGroup>
      ```yaml values.yaml theme={null}
      crm:
        enabled: false
      ```
    </CodeGroup>
  </Step>

  <Step>
    Re-despliega el chart de Midaz:

    <CodeGroup>
      ```bash Shell theme={null}
      helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
        --version 5.x.x -n midaz -f your-values.yaml
      ```
    </CodeGroup>
  </Step>

  <Step>
    Re-instala el `plugin-crm` standalone:

    <CodeGroup>
      ```bash Shell theme={null}
      helm install plugin-crm oci://registry-1.docker.io/lerianstudio/plugin-crm \
        --version <tu-version-anterior> \
        -n midaz-plugins \
        -f plugin-crm-values-backup.yaml
      ```
    </CodeGroup>
  </Step>

  <Step>
    Restaura el DNS o ingress para apuntar de vuelta al servicio standalone.
  </Step>
</Steps>

## Solución de problemas

***

**Pod del CRM falla al iniciar con errores de encriptación**

* Confirma que `LCRYPTO_HASH_SECRET_KEY` y `LCRYPTO_ENCRYPT_SECRET_KEY` correspondan exactamente a los valores usados en el deployment standalone.

**Datos aparecen vacíos después de la migración**

* Verifica que `MONGO_HOST` y `MONGO_NAME` apunten a la instancia y base de datos MongoDB correctas.
* Si ejecutaste `mongorestore`, confirma que la restauración se completó exitosamente.

**Access Manager rechaza solicitudes**

* El nombre de la aplicación en Access Manager debe seguir siendo `plugin-crm`. No se requiere ningún cambio.

**Conflicto de puerto en 4003**

* Ejecutar el CRM standalone y el integrado simultáneamente creará un conflicto en el puerto 4003.

Si necesitas ejecutar ambos durante pruebas, cambia temporalmente el puerto en los values de Midaz:

<CodeGroup>
  ```yaml values.yaml theme={null}
  crm:
    configmap:
      SERVER_PORT: "4013"
  ```
</CodeGroup>

## Próximos pasos

***

<CardGroup cols={2}>
  <Card title="Visión General del CRM" icon="circle-info" href="/es/midaz/crm/crm-overview">
    Conoce las funcionalidades y principios de diseño del CRM.
  </Card>

  <Card title="Usando el CRM" icon="rocket" href="/es/midaz/crm/crm-using-overview">
    Comienza a trabajar con holders y alias accounts.
  </Card>

  <Card title="Actualizando Helm" icon="arrow-up" href="/es/platform/helm/midaz/midaz-upgrade-guide">
    Guía completa de actualización de Helm cubriendo todas las rutas de migración.
  </Card>

  <Card title="Deploy de Midaz usando Helm" icon="dharmachakra" href="/es/platform/helm/midaz/midaz-installation">
    Referencia completa de deployment para Midaz v5.x.
  </Card>
</CardGroup>