# 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/`.

   A estrutura final tem que ficar assim:

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

2. No admin do WHMCS: **Configuração → Módulos de Complementos → ConectIQ → Ativar**.

3. Preencha os campos:

   | Campo | Onde encontrar |
   |---|---|
   | URL do webhook | ConectIQ → Integrações → Webhooks → **WHMCS** |
   | Segredo compartilhado | você escolhe; cadastre o **mesmo valor** no ConectIQ (Configurações → Checkouts e gateways → WHMCS) |
   | Chave pública do projeto | ConectIQ → Integrações → Rastreamento (é o `k=` do script) |
   | Endereço do ConectIQ | ex.: `https://painel.seudominio.com.br` |

4. Marque quem pode ver o módulo em **Acesso** e salve.

5. Clique em **Enviar pedido de teste** na página do módulo. Deve aparecer
   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.