ConectIQ para WHMCS

Rastreia de onde vem cada cliente da sua hospedagem e manda as faturas para o ConectIQ, onde viram receita atribuída à campanha, ao anúncio e ao criativo — com ROAS, ROI e lucro calculados em cima do gasto real de mídia.

Requisitos: WHMCS 8.0+ e PHP 8.0+. Sem dependências externas.

Instalação

1. Copie a pasta conectiq para <whmcs>/modules/addons/.
2. A estrutura final tem que ficar assim:

   modules/addons/conectiq/conectiq.php
   modules/addons/conectiq/hooks.php
   modules/addons/conectiq/lib/Sender.php

1. No admin do WHMCS: Configuração → Módulos de Complementos → ConectIQ → Ativar.
2. Preencha os campos:

1. Marque quem pode ver o módulo em Acesso e salve.
2. Clique em Enviar pedido de teste na página do módulo. Deve aparecer
3. um pedido TESTE-… no painel do ConectIQ em segundos.

O que o módulo faz

Rastreamento — injeta o script do ConectIQ na área do cliente. Ele grava em cookie de onde o visitante veio (UTMs, fbclid, gclid, ids de anúncio).

Captura no checkout — quando o pedido é fechado, a origem é gravada na tabela mod_conectiq_attribution, amarrada ao pedido e à fatura.

Eventos de fatura — em InvoiceCreated, InvoicePaid, InvoiceCancelled e InvoiceRefunded, o módulo envia a fatura assinada com HMAC-SHA256.

Site e WHMCS em endereços diferentes

Se a loja fica em seusite.com.br e o WHMCS em financeiro.seusite.com.br, instale o script nos dois. O cookie é gravado no domínio raiz e atravessa o subdomínio sozinho — a visita do anúncio e a compra viram a mesma pessoa.

Se forem domínios diferentes (seusite.com e meufinanceiro.net), o cookie não atravessa. Nesse caso a ligação acontece pelo e-mail do cliente, que o ConectIQ usa como último recurso de atribuição — funciona, mas só depois que a pessoa já comprou uma vez.

Renovação x venda nova

Fatura de renovação é gerada pelo cron e não tem pedido associado — é assim que o módulo separa as duas. A renovação é enviada marcada como renewal, então:

• entra na receita normalmente;
• não conta como aquisição nova, o que manteria o CAC honesto;
• é creditada à campanha que trouxe aquele cliente na primeira compra.
• Se preferir não enviar renovações, desligue a opção nas configurações.

Segurança

Cada envio leva o header X-Signature com hash_hmac('sha256', corpo_cru, segredo). No ConectIQ, deixe o gateway em modo monitoramento por alguns dias; quando o painel mostrar zero divergências, ligue a recusa e nenhuma requisição sem assinatura válida será aceita.

O segredo nunca aparece na área do cliente nem no HTML — ele só existe no banco do WHMCS e no do ConectIQ.

Resolução de problemas

"assinatura recusada" — o segredo aqui e o do ConectIQ estão diferentes. Recadastre os dois.

"URL do webhook inválida" — confira se a URL termina com a chave secreta do projeto e se o gateway no meio dela é whmcs.

Pedido chega sem campanha — o script não está no site onde o anúncio cai, ou o domínio do cookie não é compartilhado. Confira em "Visitas com origem gravada" na página do módulo: se estiver zerado, é o script.

Nada chega — ligue Registrar envios e olhe em Utilitários → Logs → Log do Módulo.