Saltar al contenido principal
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

AspectoStandalone (v4.x y anterior)Integrado (v5.x+)
Código fuenteRepositorio separadocomponents/crm/ en el monorepo de Midaz
Helm chartplugin-crm (chart dedicado)Parte del chart midaz
Namespacemidaz-pluginsmidaz
VersionamientoCiclo de release independienteSigue la versión del Midaz core
MongoDBConfiguración de conexión propiaMongoDB compartido con otros servicios de Midaz
Instalaciónhelm install plugin-crm oci://...crm.enabled: true en los values de Midaz
Puerto40034003 (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.
RecursoEndpointsEstado
HoldersPOST, GET (lista), GET (por ID), PATCH, DELETESin cambio
AliasesPOST, GET (lista por holder), GET (por ID), PATCH, DELETESin cambio
Aliases (global)GET /v1/aliases (lista entre todos los holders)Sin cambio
Related PartiesDELETEAgregado 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_ADDRESS).
  • 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:
1
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.
2
Haz backup de tus valores Helm actuales
helm get values plugin-crm -n midaz-plugins > plugin-crm-values-backup.yaml
3
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
4
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.
5
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.
PermisoDescripciónRecursosMétodos Permitidos
plugin-crm-editor-permissionAcceso totalholders, aliasespost, get, patch, delete
plugin-crm-contributor-permissionLectura y escrituraholders, aliasespost, get, patch
plugin-crm-viewer-permissionSolo lecturaholders, aliasesget
No se requieren actualizaciones en tu configuración del Access Manager.

​
Procedimiento de rollback

Si necesitas revertir al CRM standalone:
1
Deshabilita el CRM en el chart de Midaz:
crm:
  enabled: false
2
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
3
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
4
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.