Instalação

Esta página instala as duas metades do Perfex CRM Integration for WHMCS. Siga-a na ordem apresentada. Todo o processo é feito a partir de duas abas do navegador, mais o File Manager do seu painel de hospedagem. Não é necessário SSH nem linha de comando.

Você já deve ter o upload.zip (themesic.com/marketplace/whmcs-perfex.zip) descompactado, o que lhe dá dois arquivos:

Arquivo	Vai para
🧩 perfex-module/module.zip	Perfex CRM
⚙️ whmcs-addon/addon.zip	WHMCS

Instalação rápida (a versão curta)

Para um administrador de hospedagem experiente, todo o trabalho se resume a cinco movimentos. Faça-os nesta ordem.

1. 🧩 Perfex primeiro. No Perfex CRM, vá em Setup > Modules > Upload Module, envie o module.zip e depois clique em Activate. Instalar primeiro o lado do Perfex significa que o endpoint receptor já existe antes de o WHMCS enviar qualquer coisa.
2. ⚙️ Addon do WHMCS. Envie e extraia o addon.zip para dentro de modules/addons/, de modo que você termine com modules/addons/perfexbridge/perfexbridge.php, e depois ative o Perfex CRM Bridge em System Settings > Addon Modules.
3. 🔓 Marque o Access Control. Na tela Configure do addon, marque Full Administrator (mais qualquer outro perfil que deva usá-lo) e clique em Save Changes. Sem isso o módulo fica invisível - ele nunca aparece no menu Addons.
4. 🔗 Emparelhe os dois lados. Abra Addons > Perfex CRM Bridge, cole o Connection code copiado do Perfex na caixa Quick setup e clique em Connect. Detalhes em Configuração.
5. ✅ Verifique. Crie um cliente de teste no WHMCS, clique em Run Sync Now e confirme que ele aparece no Perfex em Customers.

Cada clique, cada linha da checklist e a verificação completa de ponta a ponta estão no passo a passo detalhado abaixo.

Passo a passo detalhado

A ordem importa

Instale primeiro o complemento do Perfex. É ele que cria o endpoint receptor. Se você instalar primeiro o addon do WHMCS e começar a sincronizar, todos os eventos falham enquanto o lado do Perfex não existir, e você vai perder tempo lendo logs de erro sobre um problema que ainda nem causou.

Passo 1: instalar o complemento do Perfex CRM

O complemento do Perfex é gratuito, não usa chave de licença e é instalado inteiramente pela área administrativa do Perfex.

1. Faça login no Perfex CRM como Administrador.
2. Vá em Setup > Modules.
3. Clique no botão Upload Module.
4. Escolha o module.zip no seletor de arquivos e envie-o.
5. O Perfex lista o módulo como WHMCS Bridge. Clique em Install se for solicitado e depois clique em Activate.

Se o envio for rejeitado por causa do tamanho

O botão Upload Module envia o zip através do PHP, portanto os limites upload_max_filesize e post_max_size do seu servidor precisam ser ambos maiores que o arquivo. Se o envio falhar, aumente esses limites na configuração do PHP ou use a alternativa manual abaixo.

Alternativa manual: extraia o module.zip no seu computador e envie a pasta whmcs_bridge resultante para o diretório modules/ da sua instalação do Perfex, via FTP ou pelo File Manager do seu painel de hospedagem. O resultado precisa ser modules/whmcs_bridge/whmcs_bridge.php. Depois volte a Setup > Modules e clique em Activate.

Confirme que o lado do Perfex foi instalado corretamente

• Uma nova entrada WHMCS Bridge aparece no menu Setup do Perfex. É nessa página que você vai gerar o segredo compartilhado no próximo capítulo.

Passo 2: instalar o addon do WHMCS

O WHMCS não tem instalador de módulos dentro do admin. Você mesmo coloca os arquivos no disco e depois ativa pela área administrativa. O File Manager do seu painel de hospedagem dá conta de tudo.

1. Abra o File Manager do seu painel de hospedagem e navegue até o diretório modules/addons/ da sua instalação do WHMCS.
2. Envie o addon.zip para dentro de modules/addons/.
3. Use a ação Extract do File Manager sobre o arquivo enviado, extraindo para o mesmo diretório modules/addons/.
4. Confirme que o resultado é modules/addons/perfexbridge/perfexbridge.php. Se você acabou com modules/addons/perfexbridge/perfexbridge/perfexbridge.php, a extração aninhou um nível a mais. Mova a pasta interna para cima e apague o invólucro vazio.
5. Apague o addon.zip enviado do servidor assim que a extração tiver dado certo.

Alternativa por FTP

Extraia o addon.zip no seu próprio computador primeiro e depois envie a pasta perfexbridge resultante para modules/addons/ via FTP. O estado final é idêntico.

Agora ative o módulo:

6. No WHMCS, vá em System Settings > Addon Modules.
7. Localize Perfex CRM Bridge na lista e clique em Activate.

Passo 3: marque o Access Control, ou o módulo fica invisível

Este é o relato de "não instalou" mais comum de todos

Depois da ativação, o WHMCS mostra o painel de configuração do módulo com uma seção Access Control listando os seus perfis de administrador. Você precisa marcar pelo menos Full Administrator, mais qualquer outro perfil que deva usar o módulo, e clicar em Save Changes.

Enquanto nenhum perfil estiver marcado, o módulo não aparece no menu Addons da esquerda de forma alguma. O módulo está instalado, as tabelas existem e a página de configurações funciona perfeitamente, mas não há link para ele em lugar nenhum da área administrativa. Em nove de cada dez casos, "o módulo não instalou" significa que essa caixa nunca foi marcada.

Na prática:

1. Ainda em System Settings > Addon Modules, clique em Configure ao lado de Perfex CRM Bridge. Normalmente o WHMCS abre esse painel automaticamente logo após a ativação.
2. Em Access Control, marque Full Administrator. Marque também qualquer outro perfil de administrador que deva conseguir abrir e configurar a ponte.
3. Clique em Save Changes.
4. Atualize a área administrativa. O Perfex CRM Bridge agora aparece no menu Addons.

O Access Control é a única coisa na tela Configure

Todas as configurações reais deste módulo ficam na página própria dele, em Addons > Perfex CRM Bridge, e não na tela Configure do WHMCS. A tela Configure guarda apenas o Access Control, porque ele é renderizado pelo núcleo do WHMCS e não pode ser movido. Se você abrir o Configure procurando a URL do Perfex ou a chave de licença, está na tela errada. Veja Configuração.

Passo 4: abrir a página do módulo

Vá em Addons > Perfex CRM Bridge.

A página abre com a Setup checklist. Numa instalação nova, ela fica assim:

Linha da checklist	Estado esperado neste momento
Module tables present	🟢 Marca verde
Connection configured	🔴 Cruz vermelha, nada emparelhado ainda
Connection verified	⚪ Traço cinza, nunca verificado
Sync enabled	🔴 Cruz vermelha até você marcar Enable Sync
Cron delivering	🔴 Cruz vermelha, nenhuma atividade de cron registrada ainda
License / plan	⚪ Traço cinza, plano Free

Esse é o estado correto de uma ponte recém-instalada e ainda não configurada. Cada linha é explicada em Configuração.

O próximo passo é emparelhar os dois lados: Configuração.

Passo 5: verificar a primeira sincronização de ponta a ponta

Faça isso uma vez, logo após o emparelhamento, antes de confiar dados reais à ponte. Leva dois minutos e comprova todo o pipeline.

1. Conclua o emparelhamento descrito em Configuração. As linhas Connection configured e Connection verified da checklist precisam estar as duas verdes.
2. Na mesma página, em Settings > Sync behaviour, confirme que Enable Sync está marcado e clique em Save Settings. A linha Sync enabled fica verde.
3. No WHMCS, crie um cliente de teste. Qualquer nome e e-mail servem, por exemplo uma empresa chamada Bridge Test Ltd.
4. Volte a Addons > Perfex CRM Bridge. O contador Queue pending, perto do topo, deve indicar pelo menos 1.
5. Clique em Run Sync Now. Isso força uma tentativa de entrega imediata, sem esperar pelo cron. A página informa quantos eventos foram enviados, quantos falharam e quantos foram para dead-letter.
6. No Perfex CRM, abra Customers. O cliente de teste já está lá como cliente, com o nome e o e-mail do cliente do WHMCS como contato principal.
7. Confirme que os dois logs registraram a operação:
   • Lado do WHMCS: a tabela Recent activity, mais abaixo na página do módulo, mostra uma linha client.upsert com status ok.
   • Lado do Perfex: Setup > WHMCS Bridge, painel Recent inbound events, mostra uma linha client.upsert correspondente com um selo verde ok.
8. Apague o cliente de teste dos dois sistemas se não quiser mantê-lo.

"Run Sync Now" não comprova que o seu cron funciona

O Run Sync Now comprova a entrega. Ele não deixa verde a linha Cron delivering da checklist, porque essa linha acompanha deliberadamente a atividade real do cron do sistema do WHMCS. Se essa linha continuar vermelha ou âmbar uma hora depois, o cron do sistema do WHMCS não está rodando e nada será sincronizado automaticamente. Corrija o cron antes de entrar em produção. Veja Solução de problemas.

Atualizar para uma versão mais recente

Os dois módulos têm a mesma versão e devem ser sempre atualizados juntos.

Lado do Perfex. Envie o novo module.zip por Setup > Modules > Upload Module, sobrescrevendo o módulo existente, e depois carregue qualquer página administrativa. O complemento detecta a versão de banco desatualizada e aplica as próprias migrações no lugar. Se preferir, desative e reative o módulo. Os dois caminhos são seguros: toda instrução de migração é protegida, portanto executá-la de novo não altera nada que já esteja correto.

Lado do WHMCS. Envie e extraia o novo addon.zip sobre modules/addons/perfexbridge/. O WHMCS executa a rotina de upgrade do módulo assim que percebe o novo número de versão. Na dúvida, desative e reative o addon em System Settings > Addon Modules.

As suas configurações sobrevivem a um upgrade

As configurações, o segredo compartilhado, a chave de licença, o mapa de entidades e os logs ficam todos em tabelas do banco de dados que os upgrades nunca apagam. Desativar o addon do WHMCS também não apaga os dados dele.

Desinstalar

1. WHMCS: System Settings > Addon Modules > Perfex CRM Bridge > Deactivate e depois apague modules/addons/perfexbridge/ do disco.
2. Perfex: Setup > Modules, desative o WHMCS Bridge e depois remova o módulo.
3. Se você quiser eliminar também os dados, remova as tabelas do módulo no banco de dados de cada sistema (faça um backup antes).
4. Se havia uma licença Pro ativa, remova a chave antes de desinstalar, para que o slot de ativação seja liberado e a licença possa ser reutilizada em outro lugar. Veja Licenciamento e ativação do Pro.