Configuração

Tudo nesta página pressupõe que os dois módulos estejam instalados e ativados, e que você consiga acessar Addons > Perfex CRM Bridge no WHMCS e Setup > WHMCS Bridge no Perfex CRM. Se algum dos dois estiver faltando, volte a Instalação. No WHMCS, a causa habitual é a marcação do Access Control.

Como os dois lados se autenticam

Os dois endpoints autenticam cada requisição com uma assinatura HMAC-SHA256 derivada de um segredo compartilhado.

Em linguagem simples: o remetente assina o corpo da requisição com o segredo e a carimba com um timestamp. O receptor recalcula a assinatura com a sua própria cópia do segredo e rejeita qualquer coisa cuja assinatura não confira, ou cujo timestamp tenha mais de 300 segundos. Essa janela de tempo é o que impede alguém de reproduzir mais tarde uma requisição capturada.

A consequência: o segredo precisa ser idêntico byte a byte nos dois lados, ou toda e qualquer requisição falha com um 401. Cada endpoint também recusa todo o tráfego enquanto o seu próprio segredo estiver vazio, de modo que uma ponte configurada pela metade fica fechada, e não aberta.

Os dois lados removem os espaços em branco do início e do fim antes de usar o valor, portanto um espaço ou uma quebra de linha capturados sem querer numa cópia e cola não vão quebrar nada. Tudo o que estiver no meio precisa coincidir exatamente.

Trate o segredo compartilhado como uma credencial

O segredo compartilhado concede acesso de escrita a clientes e contatos do Perfex e, com uma licença Pro, a faturas, pagamentos, pedidos e tickets nos dois lados. Faça a rotação dele nos dois lados imediatamente se algum dos bancos de dados, ou um backup de um deles, for exposto. Os segredos são armazenados em texto puro em tbladdonmodules (WHMCS) e tbloptions (Perfex), o que é prática padrão nos dois ecossistemas, portanto qualquer pessoa com acesso ao banco de dados tem o segredo.

Emparelhamento: o caminho rápido (recomendado)

Você não precisa copiar configurações de um lado para o outro na mão. O Perfex gera um único Connection code que carrega tanto a URL do Perfex quanto o segredo compartilhado, e o WHMCS o consome com uma única colagem.

Passo 1: gerar o segredo no Perfex

1. No Perfex CRM, vá em Setup > WHMCS Bridge.
2. Ao lado de Shared Secret, clique em Generate. O campo é preenchido com um segredo aleatório forte de 64 caracteres e fica visível para que você veja o que está prestes a salvar. O botão do olho alterna a visibilidade de volta.
3. Clique em Save.

Passo 2: copiar o Connection code

A página recarrega e passa a mostrar um campo Connection code somente leitura. O valor dele é uma única string começando por PBC1..

Clique em Copy. O botão pisca "Copied!" quando o código está na sua área de transferência.

O Connection code é uma senha

O código é PBC1. seguido de um JSON codificado em base64url contendo a URL do seu Perfex e o seu segredo compartilhado. Isso é codificação, não criptografia. Qualquer pessoa que obtenha o código consegue se comunicar com os endpoints da sua ponte. Não cole o código num ticket público, num canal de chat, numa captura de tela ou num pedido de suporte.

Se nenhum Connection code aparecer

O código só é exibido quando duas condições são atendidas: a sua instalação do Perfex é servida por HTTPS e o segredo compartilhado salvo tem pelo menos 32 caracteres. Clicar em Generate sem clicar em Save é a causa habitual. A página informa qual condição falhou:

• "not served over HTTPS" - o emparelhamento exige HTTPS. Use a configuração manual ou corrija o certificado.
• "shorter than 32 characters" - clique em Generate, depois em Save, e o código aparece.

Passo 3: colar o código no WHMCS

1. No WHMCS, abra Addons > Perfex CRM Bridge.
2. Localize a caixa verde Quick setup, perto do topo da página.
3. Cole o código no campo.
4. Clique em Connect.

O que o Connect realmente faz

Numa única etapa, e nesta ordem:

1. Ele decodifica o código e o valida com rigor: o prefixo PBC1., base64url estrito, um objeto JSON bem formado, uma URL que comece com https:// e passe na validação de URL, e um segredo de pelo menos 32 caracteres.
2. Ele envia um ping assinado para a sua instalação do Perfex usando a URL e o segredo decodificados, e aguarda o pong.
3. Somente se esse ping tiver sucesso é que ele salva a Perfex CRM URL e o Shared Secret do lado do WHMCS.
4. Apenas no primeiro emparelhamento, o ping também leva a URL base do seu WHMCS, de modo que o campo WHMCS URL do lado do Perfex é preenchido para você. Isso só acontece quando o seu WHMCS é servido por HTTPS, e nunca sobrescreve um valor que já esteja definido.
5. Ele registra a verificação bem-sucedida, de modo que a linha Connection verified da checklist fica verde no mesmo carregamento de página.

Em caso de sucesso, você recebe um aviso verde indicando a URL do Perfex com a qual o emparelhamento foi feito. Em caso de falha, você recebe um aviso vermelho explicando exatamente o que deu errado, e nada é salvo. Um código que falha na verificação nunca consegue sobrescrever uma configuração que está funcionando.

Reemparelhar mais tarde

Depois que o WHMCS está configurado, a caixa Quick setup vira um formulário discreto de Re-pair. Cole um código novo sempre que fizer a rotação do segredo ou mover o Perfex para um novo domínio. A mesma regra vale: um código que falha na verificação não altera nada.

Faça a rotação do segredo e depois reemparelhe, nessa ordem

Se você clicar em Generate e Save do lado do Perfex, todas as requisições existentes do WHMCS passam a falhar imediatamente com HTTP 401 até você colar o novo código no WHMCS. Faça as duas etapas uma logo após a outra. Um código antigo, copiado antes da rotação, será rejeitado, e o aviso vai lhe dizer que o Perfex respondeu 401.

Emparelhamento: a alternativa manual

O Connection code é comodidade, não mágica. Tudo o que ele faz pode ser feito à mão, e você vai precisar deste caminho se a sua instalação do Perfex ainda não estiver em HTTPS, ou se o seu fluxo de trabalho proibir colar uma credencial combinada.

1. Gere um segredo aleatório forte de pelo menos 32 caracteres. Use o botão Generate na página de configurações do Perfex, ou a sua própria ferramenta, por exemplo openssl rand -hex 32.
2. No Perfex, em Setup > WHMCS Bridge, cole-o em Shared Secret e clique em Save.
3. No WHMCS, abra Addons > Perfex CRM Bridge, role até Settings > Connection e:
   • defina a Perfex CRM URL com a URL base do seu Perfex, por exemplo https://crm.example.com, em HTTPS e sem caminho no final;
   • cole o mesmo segredo em Shared Secret.
4. Clique em Save Settings.
5. Clique em Test Connection, no topo da página. Você quer o aviso verde "Connection OK".
6. Para a sincronização bidirecional do Pro, defina também a WHMCS URL na página de configurações do Perfex. O emparelhamento teria feito isso por você.

Configurações do WHMCS, seção por seção

Todas as configurações ficam na página do próprio módulo

Abra Addons > Perfex CRM Bridge e role até Settings. Não procure na tela Configure do WHMCS, em System Settings > Addon Modules; essa tela guarda apenas o Access Control, que é renderizado pelo núcleo do WHMCS e não pode ser movido.

Clique em Save Settings para aplicar. O formulário é tudo ou nada: uma entrada inválida, por exemplo uma URL sem HTTPS, rejeita o envio inteiro e não altera nada.

As duas caixas de segredo nunca mostram o valor armazenado

Shared Secret e Pro License Key são sempre exibidos vazios, de modo que uma credencial armazenada nunca fica no código-fonte da página de todos os administradores que possam abrir o módulo. Deixe uma caixa em branco para manter o valor atual. Digite nela para substituir esse valor. Para remover completamente uma chave Pro, marque Remove the stored key.

Connection

Configuração	O que faz	Padrão recomendado
Perfex CRM URL	A URL base da sua instalação do Perfex, por exemplo https://crm.example.com. Precisa ser HTTPS: a ponte se recusa a enviar por HTTP simples.	Definida automaticamente pelo emparelhamento
Shared Secret	O segredo HMAC. Precisa coincidir com o segredo configurado no Perfex em Setup > WHMCS Bridge. Deixe em branco para manter o que está armazenado.	Definido automaticamente pelo emparelhamento

Sync behaviour

Configuração	O que faz	Padrão recomendado
Enable Sync	A chave geral. Desmarque para pausar toda a entrega de saída. Os eventos continuam entrando na fila durante a pausa, portanto nada se perde; eles são entregues na primeira execução após você reativar.	Ligado, uma vez configurado
Order Sync Target (Pro)	No que um pedido do WHMCS se transforma no Perfex. lead cria um lead do Perfex por pedido. note adiciona uma nota no cliente do Perfex em vez disso. off não sincroniza pedidos.	lead
Two-Way Conflict Policy (Pro)	Qual lado vence quando os dois sistemas alteraram o mesmo cliente ou contato desde a última sincronização. Veja abaixo.	newest_wins

As opções de política de conflito, uma linha cada:

• newest_wins (padrão) - compara a hora do evento recebido do Perfex com a hora da última sincronização, e a edição mais recente vence.
• whmcs_wins - mantém os dados do WHMCS e descarta a edição conflitante do Perfex.
• perfex_wins - aplica a edição do Perfex sobre os dados do WHMCS.

A política de conflitos só entra em ação num conflito real

Ela se aplica apenas quando os dois lados alteraram o mesmo registro desde a última sincronização bem-sucedida. Uma edição comum feita de um lado, com o outro lado intocado, é sempre aplicada. Você não está escolhendo qual sistema "vence" de modo geral, apenas como desempatar.

Uma observação sobre newest_wins e os relógios dos servidores

"Mais recente" compara o timestamp do servidor remetente com a hora da última sincronização do servidor receptor, portanto os relógios dos dois hosts importam. Mantenha os dois servidores com NTP. Se o desvio de relógio entre o seu host do WHMCS e o do Perfex estiver fora do seu controle, prefira whmcs_wins ou perfex_wins, que são determinísticos.

Tickets

Configuração	O que faz	Padrão recomendado
Ticket Reply Admin (Pro)	O nome de usuário do administrador do WHMCS usado quando uma resposta da equipe do Perfex é sincronizada para um ticket do WHMCS. Deixe vazio para atribuir a resposta ao nome do funcionário do Perfex, publicada como uma resposta não administrativa.	Vazio

Licença Pro

Configuração	O que faz	Padrão recomendado
Pro License Key	Deixe vazio para o plano Free. Cole aqui a sua chave Pro para desbloquear os recursos Pro. As chaves começam com sk_. Salvar uma chave que tenha mudado faz a verificação ao vivo, imediatamente.	Vazio (Free)
Remove the stored key	Uma caixa de seleção que aparece apenas quando há uma chave armazenada. Marcá-la e salvar reverte a instalação para Free e libera o slot de ativação deste site, para que a licença possa ser usada em outro lugar.	Desmarcada
Check licence now (botão, no topo da página)	Força uma reverificação imediata da chave já armazenada, ignorando o limite de uma verificação por dia.	-
Upgrade to Pro / Buy a Pro licence (links)	Abrem o checkout. Numa instalação sem Pro, eles aparecem ao lado da caixa da chave, na linha da checklist referente à licença e nas caixas de destaque do Pro.	-

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

As configurações Pro podem ser preenchidas com segurança no plano Free

Order Sync Target, Two-Way Conflict Policy e Ticket Reply Admin são salvos perfeitamente numa instalação Free. Eles simplesmente não têm efeito enquanto não houver uma licença válida ativa, e a página avisa isso abaixo de cada campo. Configure-os com antecedência se quiser.

Configurações do Perfex CRM, campo a campo

Abra Setup > WHMCS Bridge na área administrativa do Perfex e depois clique em Save.

Connection

Campo	O que faz	Padrão / alternativa
Shared Secret	Precisa coincidir com o Shared Secret do WHMCS. Use Generate para obter um segredo forte e depois Save. O botão do olho revela ou oculta o valor. O endpoint rejeita todo o tráfego enquanto este campo estiver vazio.	Vazio, endpoint fechado
Connection code	Somente leitura. Aparece assim que o segredo salvo tiver 32 caracteres ou mais e o Perfex estiver em HTTPS. Copie-o para a caixa Quick setup do WHMCS.	Exibido automaticamente
WHMCS URL	A URL base da instalação do WHMCS que roda o addon. Necessária apenas para o tráfego do Perfex para o WHMCS, que é um recurso Pro. Precisa começar com https://, caso contrário não é salva.	Preenchida automaticamente no primeiro emparelhamento, nunca sobrescrita depois de definida

Sincronização de tickets (Pro)

Campo	O que faz	Padrão / alternativa
Department mapping (WHMCS to Perfex)	Mapeia cada departamento de tickets do WHMCS para um departamento do Perfex. É exibido como um menu suspenso por departamento do WHMCS quando o diretório pode ser obtido, ou como uma área de texto manual caso contrário.	Vazio, nada mapeado
Default department for unmapped WHMCS tickets	O departamento do Perfex usado para qualquer ticket do WHMCS cujo departamento não esteja no mapa.	"Lowest department id (automatic)"
Staff author for synced WHMCS staff replies	O funcionário do Perfex creditado como autor das respostas da equipe do WHMCS espelhadas no Perfex.	"First active admin (automatic)"
Create a Perfex task per synced ticket	Quando marcado, cada ticket sincronizado ganha uma tarefa vinculada no Perfex para que a sua equipe possa registrar tempo nela com as timesheets nativas do Perfex.	Desligado

Como o mapeamento de departamentos é exibido

A experiência normal é com menus suspensos. Quando a página de configurações carrega, ela busca o diretório de departamentos de suporte do seu WHMCS pela ponte assinada e exibe uma linha por departamento do WHMCS, com um menu suspenso dos seus departamentos do Perfex. Escolha um destino para cada linha, ou deixe em - not mapped -, e clique em Save.

Essa busca precisa de uma conexão funcionando e de um WHMCS com licença Pro, porque o diretório de departamentos fica atrás da mesma barreira de licença que a sincronização de tickets. Quando ela não pode ser executada, a página recorre automaticamente a uma área de texto manual e informa o motivo:

O que você vê	O que significa
Menus suspensos, um por departamento do WHMCS	Está tudo funcionando
Área de texto, "Couldn't fetch WHMCS departments (needs Pro + working connection)"	A ponte ainda não está configurada, o WHMCS está inacessível a partir do servidor do Perfex, ou a instalação do WHMCS está no plano Free
Área de texto, "Connection OK, but WHMCS has no support departments yet"	A busca funcionou. Crie departamentos no WHMCS em Support > Support Departments e recarregue esta página

A busca tem um limite de poucos segundos, portanto um WHMCS inacessível deixa a página de configurações um pouco mais lenta, mas nunca a trava.

O formato manual é um mapeamento por linha, com o ID do departamento do WHMCS à esquerda e o ID do departamento do Perfex à direita:

1=2
2=5
3=5

Com os menus suspensos visíveis, o link Advanced: edit the mapping manually abre a mesma área de texto. Enquanto esse editor manual estiver aberto, é o texto dele que será salvo, sobrepondo-se às seleções dos menus.

Ordem de resolução do departamento de um ticket recebido:

1. Uma correspondência exata no mapa.
2. Caso contrário, o Default department configurado.
3. Caso contrário, o menor ID de departamento do Perfex, escolhido automaticamente.

Um erro de digitação numa linha de mapeamento degrada graciosamente para a alternativa. Isso não impede o salvamento nem quebra a sincronização.

O tempo registrado na tarefa por ticket permanece no Perfex

A tarefa opcional do Perfex existe para que a sua equipe possa usar as timesheets nativas do Perfex num ticket. Esses lançamentos de tempo não são sincronizados de volta para o WHMCS, e a tarefa não é fechada automaticamente quando o ticket é fechado.

Painéis na mesma página

A coluna da direita de Setup > WHMCS Bridge traz três painéis somente leitura:

• WHMCS plan - qual plano o lado do WHMCS reportou por último (Pro, Free ou Unknown), quando a licença foi verificada pela última vez, e um botão Upgrade to Pro quando houver algo a comprar.
• Outbound queue - alterações do lado do Perfex aguardando envio ao WHMCS, com as contagens de pendentes e mortas, número de tentativas, hora da próxima tentativa e o último erro de cada linha.
• Recent inbound events - o que o WHMCS enviou para esta instalação do Perfex, com status e mensagem.

Esses são os seus diagnósticos do lado do Perfex. Veja Como funciona e uso diário.

A setup checklist, linha a linha

A página do módulo no WHMCS abre com uma Setup checklist de seis linhas. Cada linha traz uma marca verde, um alerta âmbar, uma cruz vermelha ou um traço cinza, além de uma dica de uma linha. Tudo verde, com cinza na linha da licença se você estiver no Free, significa que a ponte está saudável.

Linha	Verde significa	Qualquer outra coisa significa
Module tables present	As tabelas de outbox, mapa e log existem todas.	🔴 Vermelho: falta uma tabela. Desative e reative o módulo em System Settings > Addon Modules para recriá-la.
Connection configured	A URL do Perfex e o segredo compartilhado estão ambos definidos.	🔴 Vermelho: ainda não definidos. Cole um Connection code no Quick setup, ou preencha os dois campos em Settings > Connection.
Connection verified	Um ping assinado recebeu um pong de volta, e a linha mostra há quanto tempo.	🔴 Vermelho: a última verificação falhou, e a linha mostra o erro. Corrija e clique em Test Connection. ⚪ Cinza: nunca verificado, ou a última verificação tem mais de 24 horas. Clique em Test Connection para atualizar.
Sync enabled	A entrega de saída está ligada.	🔴 Vermelho: a sincronização está pausada. Os eventos continuam entrando na fila, mas não são entregues. Marque Enable Sync em Settings > Sync behaviour e salve.
Cron delivering	O cron do sistema do WHMCS executou trabalho real da ponte recentemente, e a linha mostra há quanto tempo.	🟠 Âmbar: sem atividade de cron há algum tempo. Verifique se o cron do sistema do WHMCS está rodando. 🔴 Vermelho: nunca houve atividade de cron registrada. Numa instalação novinha isso é normal até a primeira entrega; se persistir, o seu cron não está rodando.
License / plan	O Pro está ativo.	⚪ Cinza: nenhuma chave de licença, ou seja, o plano Free, que é uma forma perfeitamente suportada de usar este módulo. 🔴 Vermelho: há uma chave definida, mas ela não valida. Confira a chave e clique em Check licence now.

A linha "Cron delivering" é deliberadamente difícil de forjar

Só uma execução genuína do cron do sistema do WHMCS deixa esta linha verde. O Run Sync Now entrega os eventos em fila e comprova que a entrega funciona, mas não toca nesta linha. E esse é justamente o ponto: a linha responde à pergunta "isso vai continuar funcionando quando ninguém estiver olhando?", e um clique num botão não pode responder a isso.

A linha acompanha trabalho real da ponte: esvaziamento da fila, limpeza de logs e passagens de reconciliação. Portanto, uma instalação ociosa há muito tempo, mas perfeitamente saudável, pode ficar em âmbar sem que haja nada a corrigir, simplesmente porque não houve nada a fazer.

Tanto o Connect (emparelhamento) quanto o Test Connection atualizam a linha Connection verified.

Para onde ir a seguir

• Verifique o pipeline de ponta a ponta: Instalação, passo 5.
• Desbloqueie a sincronização bidirecional, as faturas e os tickets: Licenciamento e ativação do Pro.
• Entenda o que sincroniza e onde ficam os logs: Como funciona e uso diário.