Migrando desde CRM standalone

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.

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. El CRM integrado es ahora el único modelo de deployment soportado.

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

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.

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.

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:

Identifica tu versión standalone actual

helm list -n midaz-plugins

Registra la versión del chart plugin-crm y la versión de la aplicación.

Haz backup de tus valores Helm actuales

helm get values plugin-crm -n midaz-plugins > plugin-crm-values-backup.yaml

Haz backup de tus datos MongoDB

# 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

Verifica que tu chart de Midaz sea v5.x o superior

helm list -n midaz

Si estás en v4.x o anterior, actualiza Midaz primero usando la guía Actualizando Helm.

Programa una ventana de mantenimientoEl CRM estará temporalmente indisponible durante la migración. Planifica una breve ventana de indisponibilidad.

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:

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

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.

Si usas external secrets:

crm:
  enabled: true
  useExistingSecret: true
  existingSecretName: "crm-secrets"

Paso 2 — Migra tus datos MongoDB

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

# 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

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.

Paso 3 — Deploy del CRM integrado

helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version 5.x.x \
  -n midaz \
  -f your-values.yaml

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

# 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

Paso 5 — Valida tus datos

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

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

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.

# 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

Paso 7 — Elimina el CRM standalone

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

helm uninstall plugin-crm -n midaz-plugins

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

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

kubectl delete namespace midaz-plugins

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:

Deshabilita el CRM en el chart de Midaz:

crm:
  enabled: false

Re-despliega el chart de Midaz:

helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version 5.x.x -n midaz -f your-values.yaml

Re-instala el plugin-crm standalone:

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

Restaura el DNS o ingress para apuntar de vuelta al servicio standalone.

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:

crm:
  configmap:
    SERVER_PORT: "4013"

Próximos pasos

Visión General del CRM

Conoce las funcionalidades y principios de diseño del CRM.

Usando el CRM

Comienza a trabajar con holders y alias accounts.

Actualizando Helm

Guía completa de actualización de Helm cubriendo todas las rutas de migración.

Deploy de Midaz usando Helm

Referencia completa de deployment para Midaz v5.x.

Midaz Core

CRM

Fees

Migrando desde CRM standalone

Qué cambió

Comparación de arquitectura

Cambios en la API

Qué permanece igual

Checklist pre-migración

Pasos de migración

Paso 1 — Habilita el CRM en el chart de Midaz

Paso 2 — Migra tus datos MongoDB

Paso 3 — Deploy del CRM integrado

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

Paso 5 — Valida tus datos

Paso 6 — Actualiza DNS e ingress

Paso 7 — Elimina el CRM standalone

Permisos del Access Manager

Procedimiento de rollback

Solución de problemas

Próximos pasos

Visión General del CRM

Usando el CRM

Actualizando Helm

Deploy de Midaz usando Helm

​Qué cambió

​Comparación de arquitectura

​Cambios en la API

​Qué permanece igual

​Checklist pre-migración

​Pasos de migración

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

​Paso 2 — Migra tus datos MongoDB

​Paso 3 — Deploy del CRM integrado

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

​Paso 5 — Valida tus datos

​Paso 6 — Actualiza DNS e ingress

​Paso 7 — Elimina el CRM standalone

​Permisos del Access Manager

​Procedimiento de rollback

​Solución de problemas

​Próximos pasos

Visión General del CRM

Usando el CRM

Actualizando Helm

Deploy de Midaz usando Helm

Qué cambió

Comparación de arquitectura

Cambios en la API

Qué permanece igual

Checklist pre-migración

Pasos de migración

Paso 1 — Habilita el CRM en el chart de Midaz

Paso 2 — Migra tus datos MongoDB

Paso 3 — Deploy del CRM integrado

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

Paso 5 — Valida tus datos

Paso 6 — Actualiza DNS e ingress

Paso 7 — Elimina el CRM standalone

Permisos del Access Manager

Procedimiento de rollback

Solución de problemas

Próximos pasos