Pular para o conteúdo principal
A partir do Midaz v3.5.0 e do Helm Chart v5.x, o CRM não é mais deployado como um plugin standalone. Ele agora está integrado diretamente ao monorepo e ao Helm chart do Midaz como um componente embarcado. Este guia explica como migrar do deployment standalone plugin-crm para o CRM integrado.
Se você está iniciando um novo deployment do Midaz (v5.x+), você não precisa deste guia. Simplesmente habilite o CRM nos seus valores do Helm conforme descrito em Deploy do Midaz usando Helm. O CRM integrado é agora o único modelo de deployment suportado.

​
O que mudou

O plugin CRM era originalmente mantido como um codebase separado com seu próprio ciclo de release e deployado independentemente através de um Helm chart dedicado (plugin-crm) no namespace midaz-plugins. A partir do Midaz v3.5.0-beta.12 (Dezembro 2025), o CRM foi incorporado ao monorepo do Midaz em components/crm/. Seu deployment foi então consolidado no Helm chart principal do Midaz a partir do v5.x.

​
Comparação de arquitetura

AspectoStandalone (v4.x e anterior)Integrado (v5.x+)
Código-fonteRepositório separadocomponents/crm/ no monorepo do Midaz
Helm chartplugin-crm (chart dedicado)Parte do chart midaz
Namespacemidaz-pluginsmidaz
VersionamentoCiclo de release independenteAcompanha a versão do Midaz core
MongoDBConfiguração de conexão própriaMongoDB compartilhado com outros serviços do Midaz
Instalaçãohelm install plugin-crm oci://...crm.enabled: true nos values do Midaz
Porta40034003 (sem alteração)

​
Mudanças na API

A API do CRM permanece totalmente retrocompatível. Todos os endpoints disponíveis na versão standalone continuam funcionando da mesma forma no deployment integrado.
RecursoEndpointsStatus
HoldersPOST, GET (lista), GET (por ID), PATCH, DELETESem alteração
AliasesPOST, GET (lista por holder), GET (por ID), PATCH, DELETESem alteração
Aliases (global)GET /v1/aliases (lista entre todos os holders)Sem alteração
Related PartiesDELETEAdicionado na versão integrada
O endpoint GET /v1/aliases permite listar aliases de todos os holders com filtros avançados. Os filtros incluem holder_id, account_id, ledger_id, document, dados bancários, campos regulatórios e atributos de related parties.Este endpoint complementa os endpoints com escopo de holder sob /v1/holders/{holder_id}/aliases.
O endpoint DELETE /v1/holders/{holder_id}/aliases/{alias_id}/related-parties/{related_party_id} foi introduzido com o CRM integrado.Se você precisava remover related parties individualmente, essa operação agora é suportada diretamente. Em versões anteriores, era necessário atualizar o payload do alias sem a related party.

​
O que permanece igual

  • Contrato da API: Todos os endpoints existentes, schemas de request e response e comportamentos permanecem inalterados.
  • Banco de dados: MongoDB continua sendo o backend de armazenamento.
  • Autenticação: A integração com o Access Manager funciona da mesma forma (PLUGIN_AUTH_ENABLED, PLUGIN_AUTH_ADDRESS).
  • Chaves de criptografia: LCRYPTO_HASH_SECRET_KEY e LCRYPTO_ENCRYPT_SECRET_KEY continuam sendo obrigatórias.
  • Porta padrão: O CRM continua rodando na porta 4003.

​
Checklist pré-migração

Antes de iniciar a migração, confirme o seguinte:
1
Identifique sua versão standalone atual
helm list -n midaz-plugins
Anote a versão do chart plugin-crm e a versão da aplicação.
2
Faça backup dos seus valores Helm atuais
helm get values plugin-crm -n midaz-plugins > plugin-crm-values-backup.yaml
3
Faça backup dos seus dados MongoDB
# Encontre o pod do MongoDB no namespace midaz-plugins
kubectl get pods -n midaz-plugins -l app=mongodb

# Exporte o banco de dados do CRM
kubectl exec -n midaz-plugins <mongodb-pod> -- \
  mongodump --db crm --archive=/tmp/crm-backup.archive

# Copie o backup localmente
kubectl cp midaz-plugins/<mongodb-pod>:/tmp/crm-backup.archive ./crm-backup.archive
4
Verifique se seu chart do Midaz é v5.x ou superior
helm list -n midaz
Se você está no v4.x ou anterior, atualize o Midaz primeiro usando o guia Atualizando o Helm.
5
Agende uma janela de manutençãoO CRM ficará temporariamente indisponível durante a migração. Planeje uma breve janela de indisponibilidade.

​
Passos da migração

​
Passo 1 — Habilite o CRM no chart do Midaz

Adicione a configuração do CRM aos seus valores Helm do 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: "<sua-senha-mongodb>"
    LCRYPTO_HASH_SECRET_KEY: "<sua-chave-hash-existente>"
    LCRYPTO_ENCRYPT_SECRET_KEY: "<sua-chave-encrypt-existente>"
Use as mesmas chaves de criptografia (LCRYPTO_HASH_SECRET_KEY e LCRYPTO_ENCRYPT_SECRET_KEY) usadas no deployment standalone. Chaves diferentes tornarão os dados criptografados existentes ilegíveis.
Se você usa external secrets: 
crm:
  enabled: true
  useExistingSecret: true
  existingSecretName: "crm-secrets"

​
Passo 2 — Migre seus dados MongoDB

Se seu CRM standalone usava sua própria instância MongoDB, restaure os dados no MongoDB gerenciado pelo Midaz. 
# Copie o backup para o pod do MongoDB do Midaz
kubectl cp ./crm-backup.archive midaz/<midaz-mongodb-pod>:/tmp/crm-backup.archive

# Restaure o banco de dados do CRM
kubectl exec -n midaz <midaz-mongodb-pod> -- \
  mongorestore --archive=/tmp/crm-backup.archive --db crm --drop
Se o CRM standalone e o integrado já usam a mesma instância MongoDB, você pode pular este passo. Apenas confirme que MONGO_HOST e MONGO_NAME são iguais.

​
Passo 3 — Deploy do CRM integrado

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

​
Passo 4 — Verifique se o CRM integrado está rodando

# Verifique o status do pod
kubectl get pods -n midaz -l app=crm

# Verifique os logs
kubectl logs -n midaz deployment/midaz-crm

# Teste o endpoint de health (execute port-forward em um terminal separado)
kubectl port-forward -n midaz svc/midaz-crm 4003:4003 &
curl http://localhost:4003/health

​
Passo 5 — Valide seus dados

Execute uma validação rápida para confirmar que seus dados foram migrados corretamente. 
# Liste holders pelo CRM integrado
curl -H "X-Organization-Id: <seu-org-id>" \
  http://localhost:4003/v1/holders

# Verifique um holder específico
curl -H "X-Organization-Id: <seu-org-id>" \
  http://localhost:4003/v1/holders/<holder-id-conhecido>
Compare os resultados com o deployment standalone.

​
Passo 6 — Atualize DNS e ingress

Atualize seus registros DNS ou regras de ingress para apontar para o serviço CRM no namespace midaz. 
# O nome do serviço CRM muda em relação ao chart standalone
# Antigo: plugin-crm.midaz-plugins.svc.cluster.local
# Novo: midaz-crm.midaz.svc.cluster.local

​
Passo 7 — Remova o CRM standalone

Após confirmar que tudo funciona como esperado, remova o deployment standalone. 
helm uninstall plugin-crm -n midaz-plugins
Só desinstale o CRM standalone após validar o deployment integrado. Esta operação remove o deployment standalone e seus recursos.
Se o namespace midaz-plugins não é mais necessário, você pode opcionalmente removê-lo. 
kubectl delete namespace midaz-plugins

​
Permissões do Access Manager

As permissões do Access Manager permanecem inalteradas após a migração. O nome da aplicação continua sendo plugin-crm, e as permissões se aplicam aos recursos holders e aliases.
PermissãoDescriçãoRecursosMétodos Permitidos
plugin-crm-editor-permissionAcesso totalholders, aliasespost, get, patch, delete
plugin-crm-contributor-permissionLeitura e escritaholders, aliasespost, get, patch
plugin-crm-viewer-permissionSomente leituraholders, aliasesget
Nenhuma atualização é necessária na sua configuração do Access Manager.

​
Procedimento de rollback

Se você precisar reverter para o CRM standalone:
1
Desabilite o CRM no chart do Midaz:
crm:
  enabled: false
2
Re-deploy o chart do Midaz:
helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version 5.x.x -n midaz -f your-values.yaml
3
Re-instale o plugin-crm standalone:
helm install plugin-crm oci://registry-1.docker.io/lerianstudio/plugin-crm \
  --version <sua-versao-anterior> \
  -n midaz-plugins \
  -f plugin-crm-values-backup.yaml
4
Restaure o DNS ou ingress para apontar de volta para o serviço standalone.

​
Solução de problemas

Pod do CRM falha ao iniciar com erros de criptografia
  • Confirme que LCRYPTO_HASH_SECRET_KEY e LCRYPTO_ENCRYPT_SECRET_KEY correspondem exatamente aos valores usados no deployment standalone.
Dados aparecem vazios após a migração
  • Verifique se MONGO_HOST e MONGO_NAME apontam para a instância e banco de dados MongoDB corretos.
  • Se você executou mongorestore, confirme que a restauração foi concluída com sucesso.
Access Manager rejeita requisições
  • O nome da aplicação no Access Manager deve continuar sendo plugin-crm. Nenhuma alteração é necessária.
Conflito de porta na 4003
  • Executar o CRM standalone e o integrado simultaneamente criará um conflito na porta 4003.
Se você precisar executar ambos durante testes, altere temporariamente a porta nos values do Midaz: 
crm:
  configmap:
    SERVER_PORT: "4013"

​
Próximos passos

Visão Geral do CRM

Conheça as funcionalidades e princípios de design do CRM.

Usando o CRM

Comece a trabalhar com holders e alias accounts.

Atualizando o Helm

Guia completo de atualização do Helm cobrindo todos os caminhos de migração.

Deploy do Midaz usando Helm

Referência completa de deployment para Midaz v5.x.