Solução de problemas

Percorra esta página na ordem apresentada. As três primeiras seções cobrem a esmagadora maioria dos pedidos de suporte.

Antes de qualquer coisa, abra Addons > Perfex CRM Bridge no WHMCS e leia a Setup checklist. Ela foi projetada para apontar diretamente para o problema, e cada linha é explicada em Configuração.

Referência rápida

Sintoma	Causa mais provável	Solução
O módulo não aparece no menu Addons do WHMCS	Nenhum perfil de administrador marcado em Access Control	Marque o Access Control
Todo envio falha imediatamente	A URL do Perfex começa com http://	Use HTTPS
Linhas auth.rejected no log de entrada do Perfex	O segredo compartilhado não coincide	Reemparelhe
"Two-way sync requires Pro" na fila de saída do Perfex	O lado do WHMCS está no plano Free	Ative o Pro
Os eventos entram na fila, mas nada é entregue	A sincronização está pausada, ou o cron do WHMCS não está rodando	Verifique o cron
Uma fatura nunca chega e é reprocessada para sempre	A moeda da fatura não existe no Perfex	Adicione a moeda
A licença não ativa	Chave ausente, ou sem conectividade com o serviço de licenciamento	Leia a cor do aviso
Nenhum Connection code na página do Perfex	O Perfex não está em HTTPS, ou o segredo salvo é curto demais	Generate e Save
O mapeamento de departamentos mostra uma área de texto, e não menus suspensos	Plano Free, ou WHMCS inacessível a partir do Perfex	Alternativas de mapeamento
Linhas travadas no estado dead	15 tentativas fracassadas pelo mesmo motivo	Reprocesse as linhas mortas

O módulo não está no menu Addons

Sintoma. Você ativou o Perfex CRM Bridge em System Settings > Addon Modules, o WHMCS informou que ele foi ativado, e o módulo não está em lugar nenhum do menu Addons da esquerda.

Causa. Nenhum perfil de administrador recebeu acesso. O WHMCS oculta completamente um addon de qualquer perfil que não esteja marcado, portanto o módulo está instalado e plenamente funcional, mas não tem link em nenhum lugar da área administrativa. Este é, de longe, o relato de "não instalou" mais comum.

Solução.

1. Vá em System Settings > Addon Modules.
2. Clique em Configure ao lado de Perfex CRM Bridge.
3. Em Access Control, marque Full Administrator, mais qualquer outro perfil que deva usar o módulo.
4. Clique em Save Changes.
5. Atualize a área administrativa. O módulo agora aparece em Addons.

Não há mais nada nessa tela Configure

Todas as configurações reais ficam na página do próprio módulo, em Addons > Perfex CRM Bridge. A tela Configure guarda apenas o Access Control, porque quem o renderiza é o núcleo do WHMCS e ele não pode ser movido.

Todo envio falha imediatamente, ou a URL é recusada

Sintoma. Os eventos entram na fila e falham na hora. O log Recent activity se enche de erros de conexão. Ou o campo Perfex CRM URL simplesmente se recusa a salvar.

Causa. O HTTPS é obrigatório por design. O transporte HTTP está fixado no protocolo https e valida o certificado TLS. Uma URL http:// faz falhar todo e qualquer envio, e o campo WHMCS URL do lado do Perfex também se recusa a salvar se o valor não começar com https://.

Solução.

1. Defina a Perfex CRM URL com um endereço https:// do lado do WHMCS.
2. Defina a WHMCS URL com um endereço https:// do lado do Perfex.
3. Confirme que os dois certificados realmente validam a partir do outro servidor, e não apenas no seu navegador. Um certificado autoassinado só funciona se o servidor que faz a chamada confiar nele.
4. Clique em Test Connection na página do módulo no WHMCS.

Não existe configuração para desativar a validação de HTTPS

Isso é deliberado. O seu segredo compartilhado e os dados dos seus clientes trafegam por esse canal. Se um certificado não valida, corrija o certificado.

Linhas auth.rejected no log do Perfex

Sintoma. O WHMCS reporta erros HTTP 401. No Perfex, Setup > WHMCS Bridge > Recent inbound events mostra linhas vermelhas auth.rejected.

Causa. O segredo compartilhado não coincide entre os dois lados, ou o timestamp da requisição está fora da janela de 300 segundos. Na prática, quase sempre é o segredo: alguém o regerou de um lado e nunca reemparelhou o outro.

Solução, pelo caminho rápido.

1. No Perfex, em Setup > WHMCS Bridge, copie o Connection code atual.
2. No WHMCS, em Addons > Perfex CRM Bridge, cole-o na caixa Re-pair e clique em Connect.
3. Clique em Test Connection. Você quer o aviso verde "Connection OK".
4. Clique em Run Sync Now. Os eventos em fila que estavam falhando agora são entregues.

Solução, na mão. Cole exatamente o mesmo segredo nos dois campos Shared Secret e salve nos dois lados. Os espaços em branco no início e no fim são removidos automaticamente, mas tudo o que estiver no meio precisa coincidir caractere por caractere.

Se não for o segredo. Verifique os relógios dos dois servidores. Um desvio de mais de 300 segundos entre eles faz toda requisição ser rejeitada como repetição. Coloque os dois hosts em NTP.

As linhas rejeitadas têm limite de taxa

O Perfex registra no máximo 10 linhas auth.rejected por minuto, para que um remetente mal configurado não encha o seu disco. Se você vir exatamente 10 num minuto, presuma que houve mais.

"Two-way sync requires Pro" na fila de saída do Perfex

Sintoma. Você edita um cliente no Perfex. O painel Outbound queue em Setup > WHMCS Bridge mostra a linha com a mensagem "Two-way sync requires Pro on the WHMCS side." e um link Upgrade to Pro. As tentativas aumentam e, por fim, a linha morre.

Causa. A sincronização bidirecional é um recurso Pro, e a licença fica do lado do WHMCS. A sua instalação do WHMCS está no plano Free, portanto o endpoint de entrada dela responde 403 a qualquer alteração originada no Perfex. O complemento do Perfex está se comportando corretamente ao enfileirar e reprocessar.

Solução. Ative uma licença Pro do lado do WHMCS. Veja Licenciamento e ativação do Pro. Assim que o Pro estiver ativo, o WHMCS envia o novo estado do plano ao Perfex imediatamente, o convite de upgrade desaparece, e as linhas pendentes são entregues na próxima execução do cron do Perfex.

As linhas que já ficaram dead enquanto você estava no Free não serão reprocessadas por conta própria. Veja Linhas travadas no estado dead.

Confira primeiro o painel de plano

O painel WHMCS plan fica logo acima da Outbound queue na página de configurações do Perfex, exatamente por esse motivo. Se ele disser Free, você já tem a sua resposta sem ler uma única linha da fila.

Nada sincroniza

Sintoma. Os eventos aparecem na fila, o Queue pending sobe, e nada nunca chega ao Perfex. Sem erros, apenas silêncio.

Há duas causas, e a checklist as distingue.

Causa A: a sincronização está pausada

A linha Sync enabled da checklist está vermelha.

Solução. Na página do módulo no WHMCS, em Settings > Sync behaviour, marque Enable Sync e clique em Save Settings. Nada foi perdido durante a pausa; os eventos continuaram entrando na fila e agora serão escoados.

Causa B: o cron do sistema do WHMCS não está rodando

A linha Cron delivering da checklist está vermelha ou âmbar.

Solução.

1. Comprove que a própria ponte funciona clicando em Run Sync Now. Se a sua fila for escoada, a entrega está bem e o problema é realmente o cron.
2. Verifique o status do cron do próprio WHMCS em Utilities > System > System Health Status. O WHMCS informa quando o cron do sistema rodou pela última vez.
3. Se o cron não rodou recentemente, corrija isso no nível do servidor. O gerenciador de cron do seu painel de hospedagem, ou o crontab do seu servidor, é onde fica o comando de cron do WHMCS. A documentação do próprio WHMCS traz o comando exato para a sua versão.
4. Assim que o cron voltar a rodar, a linha Cron delivering fica verde no primeiro carregamento de página após um trabalho real da ponte acontecer.

O Run Sync Now não consegue deixar a linha do cron verde

Essa linha acompanha deliberadamente apenas a atividade genuína do cron do sistema do WHMCS, porque ela responde à pergunta "isso vai continuar funcionando quando ninguém estiver olhando?". Um clique num botão não pode responder a isso. Se o Run Sync Now funciona, mas a linha continua vermelha por horas, o seu cron não está rodando.

Uma linha de cron em âmbar nem sempre é um problema

A linha acompanha trabalho real da ponte: esvaziamento da fila, limpeza de logs e reconciliação. Uma instalação saudável, mas ociosa, sem alterações a sincronizar, pode ficar em âmbar sem que haja nada a corrigir.

Uma fatura está travada e nunca chega ao Perfex

Sintoma. Uma fatura falha repetidamente. A mensagem do log menciona uma moeda, e a linha continua sendo reprocessada com um atraso crescente.

Causa. A moeda da fatura não está configurada no Perfex. O Perfex rejeita a fatura, corretamente, porque não consegue registrar um total numa moeda que desconhece.

Solução.

1. No Perfex, vá em Setup > Finance > Currencies.
2. Adicione a moeda, usando o código ISO exato que o WHMCS usa, por exemplo EUR ou USD.
3. Não faça mais nada. O evento em fila é reprocessado no seu próprio cronograma e tem sucesso na próxima tentativa.

Você tem cerca de 40 horas

O cronograma de tentativas permite 15 tentativas ao longo de aproximadamente 40 horas. Adicione a moeda dentro dessa janela, ou a linha vai para dead-letter e terá de ser reprocessada manualmente. Se você está prestes a importar faturas históricas, adicione antes todas as moedas que os seus clientes usam.

O caso relacionado: "Not mapped (will retry)"

Um registro filho chegou antes do seu pai: um contato cujo cliente ainda não está no Perfex, uma fatura cujo cliente ainda não foi mapeado, ou uma resposta de ticket cujo ticket não sincronizou.

Normalmente isso se resolve sozinho. A fila entrega em ordem, o pai chega, e o filho tem sucesso na tentativa seguinte. Isso só vira um problema real quando o pai nunca vai sincronizar, por exemplo quando você importou serviços sem importar clientes. Nesse caso, coloque o pai na fila (edite o cliente no WHMCS, ou execute um backfill de Clients) e os filhos vão atrás.

A licença não ativa

Sintoma. Você colou uma chave e a instalação continua mostrando Free.

Duas coisas são necessárias para o Pro: uma chave válida e conectividade do seu servidor WHMCS até o serviço de licenciamento. Leia a cor do aviso, porque ela indica qual das duas está faltando.

Aviso	Significado	Solução
🔴 Vermelho	O servidor de licenciamento recusou ativamente a chave, e a mensagem diz por quê.	Copie a chave do e-mail de compra de uma vez só. As chaves têm 32 caracteres e podem conter pontuação, portanto não corte nem reformate nada. Se a mensagem mencionar instalações ou uma cota, libere um slot de ativação removendo a chave de uma instalação que não precisa mais dela.
🟠 Âmbar	O seu servidor não conseguiu alcançar o serviço de licenciamento. Isso não é uma recusa.	A chave está salva e as tentativas continuam. Libere HTTPS de saída para api.freemius.com em qualquer firewall de saída ou proxy no servidor do WHMCS. Depois clique em Check licence now.
⚪ Nenhum aviso	Você salvou a mesma chave que já estava armazenada, portanto nada foi reverificado.	Clique em Check licence now.
O cabeçalho diz "awaiting first verification"	Há uma chave armazenada, mas ela nunca foi confirmada.	Clique em Check licence now.

Outras verificações:

• Confirme que a chave está em Pro License Key, em Settings > Pro licence, na página do próprio módulo, e não em algum lugar da tela Configure do WHMCS.
• Pressione Check licence now e espere alguns segundos entre um clique e outro. Um segundo clique rápido responde "checked a moment ago" sem enviar uma requisição.
• Se o Pro está ativo no WHMCS mas o Perfex ainda mostra Free, pressione Check licence now ou Test Connection no WHMCS. Os dois entregam o estado do plano ao Perfex imediatamente. Depois recarregue a página de configurações do Perfex.

Todos os detalhes estão em Licenciamento e ativação do Pro.

Nenhum Connection code aparece no Perfex

Sintoma. Você está em Setup > WHMCS Bridge, salvou um segredo, e não existe campo Connection code, apenas uma nota cinza.

Causas e soluções. A própria nota diz qual delas se aplica.

Nota	Causa	Solução
"not served over HTTPS"	O emparelhamento exige uma instalação do Perfex em HTTPS.	Corrija o certificado ou use a configuração manual.
"shorter than 32 characters"	O segredo salvo é curto demais. Clicar em Generate sem clicar em Save é a causa habitual.	Clique em Generate e depois em Save. O código aparece ao recarregar.

O emparelhamento falha com "the shared secret does not match"

Sintoma. Você colou um Connection code no WHMCS e recebeu um aviso vermelho mencionando HTTP 401.

Causa. O código carrega um segredo que o Perfex não tem mais. Quase sempre isso é um código copiado antes de um Generate e Save posteriores, ou um Generate que nunca foi salvo.

Solução. No Perfex, clique em Save na página de configurações para que o segredo atual seja realmente armazenado, copie um Connection code novo e cole esse. Nada foi armazenado do lado do WHMCS pela tentativa que falhou, portanto a sua configuração anterior, que funcionava, está intacta.

O mapeamento de departamentos mostra uma área de texto em vez de menus suspensos

Sintoma. A página de configurações do Perfex mostra uma área de texto simples para o mapeamento de departamentos, em vez de um menu suspenso por departamento do WHMCS.

Causa. A página não conseguiu obter o diretório de departamentos de suporte do seu WHMCS. A dica abaixo da área de texto informa qual caso se aplica:

Dica	Causa	Solução
"Couldn't fetch WHMCS departments (needs Pro + working connection)"	A ponte não está configurada, o WHMCS está inacessível a partir do servidor do Perfex, ou o WHMCS está no plano Free. O diretório fica atrás da mesma barreira de licença que a sincronização de tickets.	Conclua o emparelhamento, verifique se o Perfex consegue alcançar a sua URL do WHMCS por HTTPS, e ative o Pro.
"Connection OK, but WHMCS has no support departments yet"	A busca funcionou; simplesmente não há nada a mapear.	Crie departamentos no WHMCS em Support > Support Departments e depois recarregue a página do Perfex.

A área de texto manual whmcs_deptid=perfex_department_id sempre funciona nesse meio-tempo, com um mapeamento por linha. A sincronização não fica bloqueada por causa disso: um ticket sem mapeamento recai no seu departamento padrão, ou no menor ID de departamento do Perfex.

Linhas travadas no estado dead

Sintoma. O contador Dead events na página do módulo no WHMCS, ou a contagem de mortas no painel Outbound queue do Perfex, está acima de zero.

Causa. Essas linhas falharam 15 vezes ao longo de aproximadamente 40 horas pelo mesmo motivo. Linhas mortas nunca são reprocessadas automaticamente nem removidas na limpeza, deliberadamente, para que você possa examiná-las.

Solução.

1. Descubra por quê. Abra o Recent activity no WHMCS, ou a coluna "Last error" da Outbound queue no Perfex, e leia o erro nas linhas afetadas. A causa é quase sempre uma destas: uma moeda ausente no Perfex, um segredo divergente, um plano Free bloqueando um evento Pro, ou o Perfex ter ficado fora do ar.

2. Corrija essa causa raiz primeiro. Reprocessar uma linha sem corrigir a causa apenas queima mais 40 horas.

3. Recoloque o trabalho na fila. O caminho mais seguro não exige acesso ao banco de dados:

   • Para clientes, contatos, faturas, serviços e domínios, dispare o evento novamente. Edite e salve o registro no WHMCS, ou execute o assistente de backfill no modo Only new (not yet synced).
   • Para alterações do lado do Perfex, edite o registro do Perfex de novo para gerar um evento novo.

4. Se você preferir reprocessar a linha original e tiver acesso ao banco de dados, redefina-a para pendente. Faça um backup antes:

   UPDATE mod_perfexbridge_outbox
      SET status = 'pending', attempts = 0, next_attempt_ts = 0
    WHERE id = 123;

   Substitua 123 pelo ID da linha que você quer reprocessar. A tabela equivalente do lado do Perfex é tblwhmcs_bridge_outbox, com o prefixo de tabelas do seu Perfex.

Uma alteração no Perfex nunca chega ao WHMCS

Percorra esta lista:

1. O lado do WHMCS está com Pro? Verifique o painel WHMCS plan na página de configurações do Perfex. A sincronização bidirecional é exclusiva do Pro.
2. A WHMCS URL está definida do lado do Perfex? Setup > WHMCS Bridge > WHMCS URL, em HTTPS, sem caminho no final. Normalmente o emparelhamento preenche isso no primeiro pareamento, mas ele nunca sobrescreve um valor que já estava lá.
3. O servidor do Perfex consegue alcançar o WHMCS por HTTPS? O cliente de envio do Perfex exige HTTPS e valida o certificado, exatamente como o lado do WHMCS.
4. O cron do Perfex está rodando? As alterações originadas no Perfex são entregues pelo cron do Perfex, não pelo do WHMCS. Verifique o seu cron job do Perfex.
5. O registro está mapeado? Somente os clientes que foram sincronizados a partir do WHMCS estão mapeados. Um cliente criado diretamente no Perfex não tem equivalente no WHMCS e nunca é enviado. Da mesma forma, tickets criados diretamente no Perfex permanecem no Perfex.
6. Leia o painel Outbound queue. Ele indica o último erro de cada linha.

Uma alteração voltou e sobrescreveu a minha edição

Sintoma. Você editou um registro num sistema e ele reverteu para o valor do outro sistema.

Causa. Os dois lados alteraram o mesmo registro desde a última sincronização, e a sua Two-Way Conflict Policy decidiu o vencedor.

Solução. Escolha a política que corresponde ao modo como a sua equipe trabalha, em Settings > Sync behaviour, na página do módulo no WHMCS:

• newest_wins (padrão) - a edição mais recente vence. Exige que os relógios dos dois servidores estejam corretos.
• whmcs_wins - o WHMCS é sempre a autoridade.
• perfex_wins - o Perfex é sempre a autoridade.

Se os relógios dos dois hosts estiverem fora do seu controle, evite newest_wins: o desvio de relógio desloca as decisões dela na mesma medida do desvio.

Os clientes recebem dois e-mails por uma única resposta de ticket

Sintoma. Um funcionário do Perfex responde a um ticket sincronizado, e o cliente recebe duas notificações.

Causa. O Perfex envia o seu próprio e-mail de resposta de ticket, e a resposta sincronizada para o WHMCS faz o WHMCS enviar a sua própria notificação também. Este é um comportamento documentado, não um laço de sincronização. A supressão de e-mails cobre apenas o sentido WHMCS para Perfex.

Solução. Se os seus clientes usam o portal de clientes do WHMCS, desative o template de e-mail ticket-reply do Perfex em Setup > Email Templates > Tickets, no Perfex.

Ainda travado: o que reunir antes de contatar o suporte

Tenha estes itens em mãos e a resposta normalmente vem já na primeira réplica:

• A versão dos dois módulos, atualmente 1.3.4, e a confirmação de que os dois lados estão na mesma versão.
• A versão do WHMCS, a versão do Perfex CRM e a versão do PHP nos dois servidores.
• Uma captura de tela da Setup checklist da página do módulo no WHMCS.
• As contagens de Queue pending e Dead events.
• As linhas relevantes de Recent activity no WHMCS e de Recent inbound events no Perfex, com a coluna de mensagem completa.
• O que você estava fazendo quando falhou, e se alguma vez chegou a funcionar.

Nunca envie o seu segredo compartilhado nem o seu Connection code

O Connection code contém o seu segredo compartilhado. Nenhum dos dois deve ir para um ticket de suporte, uma captura de tela ou uma mensagem de chat. O suporte nunca precisa de nenhum deles para diagnosticar um problema.