Migrando do CRM standalone

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

Aspecto	Standalone (v4.x e anterior)	Integrado (v5.x+)
Código-fonte	Repositório separado	`components/crm/` no monorepo do Midaz
Helm chart	`plugin-crm` (chart dedicado)	Parte do chart `midaz`
Namespace	`midaz-plugins`	`midaz`
Versionamento	Ciclo de release independente	Acompanha a versão do Midaz core
MongoDB	Configuração de conexão própria	MongoDB compartilhado com outros serviços do Midaz
Instalação	`helm install plugin-crm oci://...`	`crm.enabled: true` nos values do Midaz
Porta	4003	4003 (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.

Recurso	Endpoints	Status
Holders	POST, GET (lista), GET (por ID), PATCH, DELETE	Sem alteração
Aliases	POST, GET (lista por holder), GET (por ID), PATCH, DELETE	Sem alteração
Aliases (global)	GET `/v1/aliases` (lista entre todos os holders)	Sem alteração
Related Parties	DELETE	Adicionado 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_HOST).
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:

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.

Faça backup dos seus valores Helm atuais

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

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

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.

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ão	Descrição	Recursos	Métodos Permitidos
`plugin-crm-editor-permission`	Acesso total	holders, aliases	post, get, patch, delete
`plugin-crm-contributor-permission`	Leitura e escrita	holders, aliases	post, get, patch
`plugin-crm-viewer-permission`	Somente leitura	holders, aliases	get

Nenhuma atualização é necessária na sua configuração do Access Manager.

Procedimento de rollback

Se você precisar reverter para o CRM standalone:

Desabilite o CRM no chart do Midaz:

crm:
  enabled: false

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

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

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.

Midaz Core

CRM

Fees

Migrando do CRM standalone

O que mudou

Comparação de arquitetura

Mudanças na API

O que permanece igual

Checklist pré-migração

Passos da migração

Passo 1 — Habilite o CRM no chart do Midaz

Passo 2 — Migre seus dados MongoDB

Passo 3 — Deploy do CRM integrado

Passo 4 — Verifique se o CRM integrado está rodando

Passo 5 — Valide seus dados

Passo 6 — Atualize DNS e ingress

Passo 7 — Remova o CRM standalone

Permissões do Access Manager

Procedimento de rollback

Solução de problemas

Próximos passos

Visão Geral do CRM

Usando o CRM

Atualizando o Helm

Deploy do Midaz usando Helm

​O que mudou

​Comparação de arquitetura

​Mudanças na API

​O que permanece igual

​Checklist pré-migração

​Passos da migração

​Passo 1 — Habilite o CRM no chart do Midaz

​Passo 2 — Migre seus dados MongoDB

​Passo 3 — Deploy do CRM integrado

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

​Passo 5 — Valide seus dados

​Passo 6 — Atualize DNS e ingress

​Passo 7 — Remova o CRM standalone

​Permissões do Access Manager

​Procedimento de rollback

​Solução de problemas

​Próximos passos

Visão Geral do CRM

Usando o CRM

Atualizando o Helm

Deploy do Midaz usando Helm

O que mudou

Comparação de arquitetura

Mudanças na API

O que permanece igual

Checklist pré-migração

Passos da migração

Passo 1 — Habilite o CRM no chart do Midaz

Passo 2 — Migre seus dados MongoDB

Passo 3 — Deploy do CRM integrado

Passo 4 — Verifique se o CRM integrado está rodando

Passo 5 — Valide seus dados

Passo 6 — Atualize DNS e ingress

Passo 7 — Remova o CRM standalone

Permissões do Access Manager

Procedimento de rollback

Solução de problemas

Próximos passos