Como funciona e uso diário
Depois que a ponte está emparelhada e a sincronização ativada, ela funciona sozinha. Esta página explica o que ela realmente faz, para que, quando algo parecer estranho, você saiba onde olhar em vez de adivinhar.
O motor de sincronização em linguagem simples
1. Uma alteração gera um evento
Toda alteração relevante no WHMCS dispara um hook do WHMCS: um cliente é adicionado ou editado, um contato é criado, uma fatura é finalizada, um pagamento entra, um pedido é feito, um serviço é provisionado ou suspenso, um ticket é aberto ou respondido.
O hook não faz uma chamada HTTP. Ele grava um pequeno evento numa tabela de outbox (mod_perfexbridge_outbox) e retorna imediatamente.
Se um hook do WHMCS chamasse o Perfex diretamente, um servidor Perfex lento ou inacessível travaria uma página administrativa do WHMCS ou o checkout de um cliente. Gravar numa tabela local leva um milissegundo e nunca pode falhar por causa da rede de outra pessoa. Tudo o que vem depois acontece em segundo plano.
2. O cron esvazia a fila
A cada execução do cron do sistema do WHMCS, o despachante retira da outbox um lote de eventos vencidos e envia cada um deles por POST para a sua instalação do Perfex via HTTPS.
Cada requisição carrega dois cabeçalhos ao lado do corpo JSON: um timestamp e uma assinatura HMAC-SHA256 calculada sobre esse timestamp mais o corpo exato da requisição, usando o seu segredo compartilhado. O Perfex recalcula a assinatura com a sua própria cópia do segredo e rejeita qualquer coisa que não confira, ou cujo timestamp tenha mais de 300 segundos.
Você pode forçar um esvaziamento imediato a qualquer momento com o Run Sync Now, na página do módulo no WHMCS.
3. As falhas são reprocessadas e depois vão para dead-letter
Um envio que falha não é perdido, e não é repetido num laço apertado. Ele é reagendado com backoff exponencial: cerca de 60 segundos após a primeira falha, depois 2 minutos, 4, 8, e assim por diante, com um teto de 6 horas entre as tentativas.
Após 15 tentativas, o que abrange aproximadamente 40 horas, a linha é marcada como dead. Linhas mortas nunca são reprocessadas automaticamente nem removidas na limpeza. Elas são a sua gaveta de dead-letter: o contador Dead events, no topo da página do módulo no WHMCS, informa quantas existem, e a linha do log informa o motivo.
Ir para dead-letter significa que o mesmo evento falhou por quase dois dias pelo mesmo motivo. Quase sempre a causa é uma de quatro coisas: uma moeda ausente no Perfex, um segredo divergente, um plano Free bloqueando um evento Pro, ou o Perfex estar fora do ar. Corrija a causa e recoloque o trabalho na fila. Veja Solução de problemas.
4. Pausar não perde nada
Desmarcar Enable Sync pausa apenas a entrega. Os hooks continuam gravando eventos na outbox, portanto nada é descartado durante a pausa. Reative e o acúmulo é escoado na próxima execução, ou imediatamente com o Run Sync Now.
5. A supressão de eco impede laços infinitos
A sincronização bidirecional cria um risco evidente: o WHMCS aplica uma alteração vinda do Perfex, essa gravação dispara os próprios hooks do WHMCS, e a alteração volta imediatamente. Sem controle, uma única edição ficaria indo e voltando para sempre.
A ponte impede isso com camadas de proteção, aplicadas nos dois lados:
- Um marcador de origem dentro da requisição, definido enquanto a ponte está aplicando uma alteração recebida, para que as gravações que ela mesma faz não sejam tratadas como novas edições de usuário.
- Uma consulta ao mapa de entidades e de IDs de resposta, para que uma resposta de ticket que a ponte acabou de criar seja reconhecida em vez de reenviada como nova.
- Uma comparação de checksum, que transforma um evento em operação nula quando os dados já são iguais ao último estado sincronizado.
Cada lado tem o seu próprio marcador de origem, e o checksum funciona como rede de segurança caso um marcador seja contornado. As proteções falham deliberadamente para o lado aberto: se uma delas não conseguir decidir, prefere-se um envio extra inofensivo a uma atualização silenciosamente descartada.
6. Manutenção
Os dois lados executam uma limpeza diária autolimitada, no máximo uma vez a cada 24 horas:
- as linhas da outbox já entregues com mais de 7 dias são apagadas;
- as linhas de log com mais de 90 dias são apagadas;
- as linhas pendentes e mortas nunca são removidas, porque pendente é trabalho não entregue e morta é a sua gaveta de dead-letter.
O que sincroniza, e em qual sentido
Do WHMCS para o Perfex CRM
| Dados | Free | Pro | O que chega ao Perfex |
|---|---|---|---|
| 👥 Clientes | ✅ | ✅ | Um cliente do Perfex, mais um contato principal com o nome e o e-mail do cliente |
| 👤 Contatos | ✅ | ✅ | Contatos adicionais sob o mesmo cliente do Perfex |
| 🗑️ Exclusão de cliente | ✅ | ✅ | O cliente do Perfex é desativado, não destruído |
| 📄 Faturas | ➖ | ✅ | Uma fatura do Perfex com itens, uma linha de imposto, totais equivalentes, status e o número da fatura do WHMCS na nota administrativa |
| 💳 Pagamentos e transações | ➖ | ✅ | Um registro de pagamento na fatura espelhada, com o gateway e o ID da transação. Duplicatas são recusadas |
| 💸 Reembolsos | ➖ | ✅ | O espelho no Perfex é cancelado e anotado |
| 🛒 Pedidos | ➖ | ✅ | Um lead do Perfex por pedido, ou uma nota no cliente, ou nada, conforme o Order Sync Target |
| 📦 Serviços | ➖ | ✅ | Linhas na aba WHMCS do cliente: nome do produto, domínio, status, ciclo de faturamento, valor e próxima data de vencimento |
| 🌐 Domínios | ➖ | ✅ | Linhas na mesma aba: registrador, status, expiração e próxima data de vencimento |
| 🎫 Tickets e respostas | ➖ | ✅ | Um ticket do Perfex sob o cliente, no departamento mapeado, com respostas e status |
No plano Free, o status e as notas de um cliente viajam no payload, mas não são gravados no Perfex. Apenas a exclusão de cliente age sobre o registro do Perfex, desativando o cliente.
Do Perfex CRM para o WHMCS (somente Pro)
| Alteração feita no Perfex | O que acontece no WHMCS |
|---|---|
| Dados da empresa do cliente editados | O registro de cliente do WHMCS é atualizado, sujeito à política de conflitos |
| Contato principal editado | Os campos de identidade do cliente no WHMCS são atualizados, porque o contato principal é a identidade do cliente |
| Contato não principal editado | O contato correspondente no WHMCS é atualizado |
| Funcionário responde a um ticket espelhado | A resposta aparece no ticket do WHMCS, atribuída ao seu Ticket Reply Admin se ele estiver definido, caso contrário ao nome do funcionário do Perfex |
| Status do ticket alterado | O status do ticket no WHMCS acompanha |
Apagar um cliente ou um registro no Perfex não apaga nada no WHMCS. Os registros de faturamento são preservados independentemente do que acontece no CRM. Isso é deliberado e não é configurável.
Comportamentos conhecidos que vale conhecer antes de depender deles
Estas são decisões documentadas, não bugs:
- Tickets criados diretamente no Perfex permanecem no Perfex. Eles nunca são criados no WHMCS, porque um ticket do WHMCS precisa de uma conta de cliente e de um departamento de suporte que um ticket criado no CRM pode não ter.
- Alterações de status de ticket feitas pelo formulário completo de configurações de ticket do Perfex não se propagam. O menu de status de um único ticket, as respostas, as mudanças de status em massa e o fechamento automático sincronizam corretamente.
- O tempo registrado numa tarefa do Perfex por ticket não é sincronizado de volta para o WHMCS. A tarefa existe para os relatórios nativos de timesheet do Perfex.
- A cadência de faturas recorrentes não é modelada. As faturas do WHMCS são espelhadas como faturas avulsas comuns do Perfex.
- A fusão de dois clientes do WHMCS não é tratada. Depois de uma fusão, remapeie ou remova as linhas de mapa do cliente absorvido.
- A resposta de um funcionário do Perfex num ticket sincronizado pode gerar dois e-mails ao cliente, um do Perfex e outro do WHMCS. Se os seus clientes usam o portal de clientes do WHMCS, desative o template de e-mail
ticket-replydo Perfex em Setup > Email Templates > Tickets.
Onde ficam os logs
Esta é a seção que mais economiza tempo. As pessoas costumam procurar no lugar errado.
Lado do WHMCS: a página do próprio módulo
Vá em Addons > Perfex CRM Bridge e role até Recent activity.
A ponte não grava no Activity Log do WHMCS, em Utilities > Logs. A tabela própria dela é exibida como o painel Recent activity na página do módulo, e esse é o único lugar onde procurar do lado do WHMCS.
A tabela mostra os últimos 50 eventos, com estas colunas:
| Coluna | Significado |
|---|---|
| Time | Quando a linha foi gravada |
| Dir | out para WHMCS até Perfex, in para Perfex até WHMCS |
| Event | Por exemplo client.upsert, invoice.upsert, cron.drain |
| Entity | client, contact, invoice, ticket, e assim por diante |
| WHMCS ID | O ID do registro no WHMCS |
| Status | ok em verde ou error em vermelho |
| Message | O resultado, ou o texto exato do erro |
Logo acima dela, a linha de cabeçalho mostra as contagens de Queue pending e Dead events. Esses dois números são o seu resumo de saúde: os pendentes devem cair a zero em um ou dois ciclos de cron, e os mortos devem permanecer em zero.
Lado do Perfex: dois painéis na página de configurações
Vá em Setup > WHMCS Bridge.
O Recent inbound events lista o que o WHMCS enviou para esta instalação do Perfex, com o tipo de evento, o ID do WHMCS, o ID do Perfex ao qual ele foi mapeado, um selo de status e uma mensagem. É aqui que uma requisição rejeitada aparece como uma linha auth.rejected, o que significa um problema de assinatura ou de timestamp, quase sempre um segredo divergente. As linhas rejeitadas são limitadas a 10 por minuto, para que uma enxurrada não encha o seu disco.
O Outbound queue lista as alterações do lado do Perfex aguardando envio ao WHMCS, com:
- as contagens de pending e dead no título do painel;
- uma linha por alteração em fila, mostrando o evento, a entidade, o status, o número de tentativas, a hora da próxima tentativa e o último erro;
- uma explicação em linguagem clara em vez de um erro bruto quando a causa é conhecida. Um 403 de um WHMCS sem licença aparece como "Two-way sync requires Pro on the WHMCS side", com um link de upgrade, em vez de um despejo de JSON.
Apenas as 20 linhas mais recentes são exibidas. As linhas entregues se limpam sozinhas após 7 dias; as pendentes e as mortas são mantidas.
Qual log responde a qual pergunta
| Pergunta | Olhe aqui |
|---|---|
| 📤 A minha alteração no WHMCS saiu do WHMCS? | WHMCS: Recent activity, direção out |
| 📥 O Perfex aceitou a alteração? | Perfex: Recent inbound events |
| 🔑 O meu segredo compartilhado está errado? | Perfex: linhas auth.rejected em Recent inbound events |
| 🔁 A minha edição no Perfex chegou ao WHMCS? | Perfex: Outbound queue, depois WHMCS: Recent activity, direção in |
| ⏰ O cron está rodando? | WHMCS: a linha Cron delivering da checklist |
| 🔇 Por que a sincronização bidirecional está silenciosa? | Perfex: o painel WHMCS plan. Se ele disser Free, essa é a sua resposta |
O assistente de backfill (Pro)
A sincronização ao vivo só trata atividade nova. Se você instalar a ponte numa instalação do WHMCS já em uso, os seus clientes e faturas existentes não estarão no Perfex até que você faça o backfill deles.
O Backfill wizard fica na página do módulo no WHMCS, abaixo do formulário de configurações. Ele coloca os seus registros existentes na mesma outbox usada pela sincronização ao vivo, de modo que eles herdam a mesma assinatura, as mesmas novas tentativas, o mesmo backoff e o mesmo dead-lettering.
Escopos
Marque um ou mais:
| Escopo | O que ele coloca na fila |
|---|---|
| Clients + contacts | Todos os clientes do intervalo. Os contatos acompanham automaticamente o seu cliente |
| Invoices | Todas as faturas do intervalo |
| Services + domains | Todos os serviços e domínios do intervalo, preenchendo a aba WHMCS do Perfex |
Tickets históricos não sincronizam. Somente a atividade nova de tickets circula depois que a ponte entra em funcionamento. Esta é uma limitação documentada, não um problema de configuração.
Modos
| Modo | Comportamento |
|---|---|
| All history | Todos os registros dos escopos escolhidos |
| Date range | Apenas os registros criados dentro de uma janela YYYY-MM-DD de e até. Um intervalo inválido, por exemplo um "de" posterior a um "até", é rejeitado com uma mensagem clara e nada é colocado na fila |
| Only new (not yet synced) | Ignora os registros que já estão mapeados. Este é o modo a usar em execuções repetidas |
O limite de 500 entidades e como continuar
Cada execução coloca na fila no máximo 500 entidades, para que um backfill numa instalação grande não possa inundar a fila nem travar o seu cron.
Quando o limite é atingido, o assistente avisa. A rotina é:
- Clique em Queue Backfill. Um aviso informativo indica quantos registros foram planejados, quantos entraram na fila, quantos deram erro e se a execução foi truncada.
- Acompanhe o contador Queue pending, no topo da página, ir baixando, seja pelo cron ou com o Run Sync Now.
- Execute o assistente novamente no modo Only new (not yet synced).
- Repita até que uma execução não planeje nada novo.
Não há risco de duplicatas. Registros já mapeados são ignorados, e um evento cujos dados já coincidem com o lado do Perfex é respondido como operação nula.
Duas regras de ordem que economizam tempo
Um registro filho cujo cliente pai ainda não está no Perfex recebe a resposta "not mapped, will retry" e permanece na fila até o pai chegar. Normalmente a própria ordem da fila resolve isso. Mas se você fizer o backfill apenas de serviços ou faturas numa instalação cujos clientes nunca foram sincronizados, esses eventos serão reprocessados por cerca de 40 horas e depois irão para dead-letter.
Ou marque Clients + contacts na mesma execução, ou faça primeiro o backfill dos clientes.
Uma fatura numa moeda que o Perfex não conhece é rejeitada e reprocessada, e vai para dead-letter após cerca de 40 horas. Antes de fazer o backfill de faturas, adicione todas as moedas usadas pelos seus clientes do WHMCS em Setup > Finance > Currencies no Perfex, usando o código ISO exato.
Faturas históricas já pagas
As faturas importadas retroativamente que já estavam pagas no WHMCS são quitadas no Perfex com um registro de pagamento sintético, de modo que aparecem como Pagas em vez de Vencidas. Executar um backfill de novo não cria pagamentos duplicados.
Operação do dia a dia
Depois de configurado, há muito pouco a fazer. Uma olhada semanal rápida na página do módulo no WHMCS é suficiente:
| O que observar | Saudável |
|---|---|
| Setup checklist | Tudo verde, com cinza na linha da licença se você usa o Free |
| Queue pending | Pequeno e caindo entre as execuções do cron |
| Dead events | 0 |
| Recent activity | Majoritariamente linhas ok |
| Outbound queue do Perfex | 0 pendentes, 0 mortas, em instalações Pro com sincronização bidirecional |
Se algo dessa lista estiver errado, Solução de problemas traz a causa e a correção.