> ## 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 do CRM standalone

> Guia completo para migrar do deployment standalone plugin-crm para o componente CRM integrado ao Midaz sem perder dados nem histórico.

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.

<Info>
  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](/pt/platform/helm/midaz/midaz-installation). O CRM integrado é agora o único modelo de deployment suportado.
</Info>

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

<Tip>
  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`.
</Tip>

<Note>
  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.
</Note>

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

<Steps>
  <Step>
    **Identifique sua versão standalone atual**

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

    Anote a versão do chart `plugin-crm` e a versão da aplicação.
  </Step>

  <Step>
    **Faça backup dos seus valores Helm atuais**

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

  <Step>
    **Faça backup dos seus dados MongoDB**

    <CodeGroup>
      ```bash Shell theme={null}
      # 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
      ```
    </CodeGroup>
  </Step>

  <Step>
    **Verifique se seu chart do Midaz é v5.x ou superior**

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

    Se você está no v4.x ou anterior, atualize o Midaz primeiro usando o guia [Atualizando o Helm](/pt/platform/helm/midaz/midaz-upgrade-guide).
  </Step>

  <Step>
    **Agende uma janela de manutenção**

    O CRM ficará temporariamente indisponível durante a migração. Planeje uma breve janela de indisponibilidade.
  </Step>
</Steps>

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

<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: "<sua-senha-mongodb>"
      LCRYPTO_HASH_SECRET_KEY: "<sua-chave-hash-existente>"
      LCRYPTO_ENCRYPT_SECRET_KEY: "<sua-chave-encrypt-existente>"
  ```
</CodeGroup>

<Warning>
  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.
</Warning>

Se você usa external secrets:

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

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

<CodeGroup>
  ```bash Shell theme={null}
  # 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
  ```
</CodeGroup>

<Tip>
  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.
</Tip>

### Passo 3 — Deploy do 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>

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

<CodeGroup>
  ```bash Shell theme={null}
  # 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
  ```
</CodeGroup>

### Passo 5 — Valide seus dados

Execute uma validação rápida para confirmar que seus dados foram migrados corretamente.

<CodeGroup>
  ```bash Shell theme={null}
  # 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>
  ```
</CodeGroup>

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

<CodeGroup>
  ```yaml ingress-example.yaml theme={null}
  # 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
  ```
</CodeGroup>

### Passo 7 — Remova o CRM standalone

Após confirmar que tudo funciona como esperado, remova o deployment standalone.

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

<Danger>
  Só desinstale o CRM standalone **após validar o deployment integrado**. Esta operação remove o deployment standalone e seus recursos.
</Danger>

Se o namespace `midaz-plugins` não é mais necessário, você pode opcionalmente removê-lo.

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

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

<Steps>
  <Step>
    Desabilite o CRM no chart do Midaz:

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

  <Step>
    Re-deploy o chart do 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-instale o `plugin-crm` standalone:

    <CodeGroup>
      ```bash Shell theme={null}
      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
      ```
    </CodeGroup>
  </Step>

  <Step>
    Restaure o DNS ou ingress para apontar de volta para o serviço standalone.
  </Step>
</Steps>

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

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

## Próximos passos

***

<CardGroup cols={2}>
  <Card title="Visão Geral do CRM" icon="circle-info" href="/pt/midaz/crm/crm-overview">
    Conheça as funcionalidades e princípios de design do CRM.
  </Card>

  <Card title="Usando o CRM" icon="rocket" href="/pt/midaz/crm/crm-using-overview">
    Comece a trabalhar com holders e alias accounts.
  </Card>

  <Card title="Atualizando o Helm" icon="arrow-up" href="/pt/platform/helm/midaz/midaz-upgrade-guide">
    Guia completo de atualização do Helm cobrindo todos os caminhos de migração.
  </Card>

  <Card title="Deploy do Midaz usando Helm" icon="dharmachakra" href="/pt/platform/helm/midaz/midaz-installation">
    Referência completa de deployment para Midaz v5.x.
  </Card>
</CardGroup>