# Como instalar o WHMCS no servidor da revenda

Pré-requisitos, licença amarrada a domínio e IP, fechamento seguro da instalação e o que fazer quando o instalador trava, antes de ligar o provisionamento ao WHM.

> instale o WHMCS no endereço final, com PHP suportado e ionCube ativo, crie banco com todos os privilégios, rode /install/, apague a pasta install e configure o cron. A licença fica presa a domínio, IP e pasta; mudou, reemita.

João Rizzon · 2026-11-12 · Revenda

---

## O que precisa estar pronto antes de abrir o instalador

O WHMCS é a camada de cobrança. Ele só cria contas no WHM depois de instalado, licenciado e ligado ao servidor. A criação da conta após o pagamento é disparada pela confirmação do pagamento, não pelo cron. O cron cuida das rotinas agendadas: faturas recorrentes, suspensões e lembretes. Quem pula essa ordem acaba depurando o módulo de provisionamento quando o problema está na instalação. Por isso vale separar a tarefa em duas: primeiro o WHMCS de pé e acessível pelo painel administrativo, depois a ligação com o WHM.

A documentação oficial da cPanel trata justamente dessas duas etapas iniciais, compra da licença e instalação, no guia [How to Purchase and Install WHMCS](https://docs.cpanel.net/knowledge-base/third-party/how-to-purchase-and-install-whmcs/). Use esse guia como referência para os passos da cPanel. O que segue organiza o processo para quem vai repetir isso em mais de um cliente e acrescenta o tratamento dos erros mais comuns.

Antes de baixar qualquer arquivo, confirme estes pontos na conta onde o WHMCS vai morar:

| Item | Como conferir | Por que trava a instalação |
|---|---|---||
| Domínio ou subdomínio definitivo | DNS já apontado e SSL emitido | A licença fica associada ao domínio usado no primeiro acesso |
| IP do servidor | IP que aparece no cPanel da conta | A licença também valida o IP de onde o WHMCS responde |
| Versão de PHP suportada | MultiPHP Manager no cPanel | Versão fora da faixa suportada faz o verificador de requisitos recusar |
| ionCube Loader ativo | `php -m` ou phpinfo | Os arquivos do WHMCS são codificados e não executam sem ele |
| Banco MySQL e usuário | MySQL Databases no cPanel | O instalador cria as tabelas e precisa de todas as permissões |
| Acesso ao cron | Cron Jobs no cPanel | Sem cron, faturas recorrentes, suspensões e lembretes não rodam (a criação da conta após o pagamento depende da confirmação do pagamento, não do cron) |

A faixa exata de versões de PHP suportadas muda a cada versão do WHMCS. Consulte os requisitos da versão que você vai baixar, não um tutorial antigo.

## Por que a licença do WHMCS trava se domínio, IP ou pasta mudarem

A licença do WHMCS é validada contra o domínio, o IP e o diretório da instalação. Na prática, o primeiro acesso define esses valores. Se você instala em `teste.cliente.com.br` para depois mover para `financeiro.cliente.com.br`, a licença passa a acusar inválida no novo endereço.

Isso tem duas consequências para quem trabalha com vários clientes:

- **Instale direto no endereço final.** Subdomínio dedicado (por exemplo, `financeiro.` ou `area.`) costuma ser mais limpo que uma subpasta do site institucional, porque a migração do site não arrasta o WHMCS junto.
- **Mudou domínio, IP ou pasta, reemita a licença.** A reemissão (reissue) é feita na área de cliente de quem vendeu a licença. Se a compra foi pela loja da cPanel, procure a reemissão na área de cliente dessa loja, não no suporte da WHMCS. Em caso de dúvida, confirme com quem vendeu a licença.

Troca de servidor é o caso que mais pega agência de surpresa: o IP muda, o WHMCS para de abrir o painel e o cliente acha que perdeu os dados. Os dados estão no banco. Só a validação falhou.

Frase pronta para o cliente: "A licença do sistema de cobrança é registrada no endereço e no servidor onde ele roda. Como mudamos de servidor, preciso reemitir a licença. Os dados continuam intactos."

## Conferindo PHP e ionCube pelo terminal

Se a conta tem acesso SSH, dois comandos resolvem a maior parte das dúvidas antes de começar:

```
php -v
php -m | grep -i ioncube
```

O primeiro mostra a versão do PHP de linha de comando. O segundo deve devolver uma linha com `ionCube Loader`. Se não devolver nada, o loader não está carregado.

Atenção a um detalhe que gera horas de confusão: em servidores cPanel, o PHP do terminal pode ser diferente do PHP que atende o site. O que vale para o instalador web é o PHP configurado para o domínio no MultiPHP Manager. Para conferir o PHP web, crie temporariamente um arquivo com `phpinfo()` na pasta da instalação, abra no navegador, procure por ionCube e apague o arquivo em seguida.

Em conta de revenda você não controla os módulos do servidor. Se o ionCube não estiver disponível, peça ao provedor para habilitá-lo. Não tente contornar.

## Instalação passo a passo

O [guia da cPanel](https://docs.cpanel.net/knowledge-base/third-party/how-to-purchase-and-install-whmcs/) cobre a compra da licença e a instalação. Detalhes como renomear `configuration.php.new`, a permissão 400 e o intervalo do cron são prática comum, não parte desse guia: confira na documentação da versão que você baixou. Os nomes de pasta e domínio são exemplos fictícios.

### Obter a licença e baixar o pacote

Compre a licença (pela loja da cPanel ou diretamente na WHMCS) e baixe o pacote da versão atual. Guarde a chave de licença: o instalador vai pedi-la.

### Criar banco e usuário no MySQL do cPanel

No cPanel, em MySQL Databases, crie um banco (exemplo: `cliente_whmcs`), um usuário com senha forte e associe os dois com **todos os privilégios**. Anote nome do banco, usuário e senha exatamente como o cPanel mostra, com o prefixo da conta.

### Enviar e extrair os arquivos na raiz do subdomínio

Envie o pacote para a raiz do subdomínio (exemplo: `/home/cliente/financeiro.cliente.com.br/`) e extraia pelo Gerenciador de Arquivos. Se o pacote trouxer `configuration.php.new`, renomeie para `configuration.php` (confira na documentação da versão se o passo se aplica). O instalador grava os dados de conexão nesse arquivo, então ele precisa existir e estar gravável.

### Rodar o instalador em /install/

Acesse `https://financeiro.cliente.com.br/install/` no navegador. O fluxo aceita os termos, verifica requisitos, pede a chave de licença, os dados do banco e cria o primeiro administrador. Use um usuário administrador que não seja `admin`.

### Apagar a pasta install e fechar a permissão do configuration.php

Ao final, apague a pasta `install` e proteja o arquivo de configuração. A permissão 400 abaixo é prática recomendada. Confira o que a documentação da sua versão indica:

```
cd /home/cliente/financeiro.cliente.com.br
rm -rf install
chmod 400 configuration.php
ls -l configuration.php
```

O `ls -l` deve mostrar `-r--------`. Enquanto a pasta `install` existir, o painel administrativo exibe aviso e a instalação fica exposta.

### Configurar o cron com o comando copiado do painel

No cPanel, em Cron Jobs, adicione a tarefa de automação. Exemplo ilustrativo, com intervalo de 5 minutos e caminho a ajustar (a frequência recomendada está na documentação da versão):

```
*/5 * * * * php -q /home/cliente/financeiro.cliente.com.br/crons/cron.php
```

O WHMCS mostra o comando exato, com o caminho correto, em Configurações do sistema, na seção de automação. Copie de lá em vez de digitar. Depois de algumas execuções, o painel deixa de avisar que o cron não está rodando.

## O que fazer quando o instalador para no meio

Instalação interrompida deixa um estado misto: parte das tabelas criadas, `configuration.php` às vezes preenchido, às vezes não. Rodar de novo por cima costuma falhar com erro de tabela já existente. O caminho limpo:

| Sintoma | Causa provável | O que fazer |
|---|---|---||
| Tela branca ou erro 500 ao abrir `/install/` | ionCube ausente ou PHP incompatível | Conferir MultiPHP e phpinfo, ajustar e recarregar |
| Verificador de requisitos aponta item em vermelho | Extensão PHP faltando | Ativar a extensão no seletor de PHP ou pedir ao provedor |
| Erro de conexão com o banco | Nome sem prefixo, senha errada ou usuário sem privilégio | Copiar os nomes exatos do cPanel e reassociar com todos os privilégios |
| Mensagem de licença inválida | Chave errada, ou domínio, IP ou pasta diferente do registrado | Conferir a chave e reemitir a licença |
| Para na criação das tabelas | Tempo limite do PHP ou conexão caiu | Limpar o banco e reiniciar a instalação |
| Instalação conclui mas não grava nada | `configuration.php` inexistente ou sem permissão de escrita | Renomear o `.new` e liberar escrita só durante a instalação |

Para reiniciar do zero sem deixar lixo:

- No phpMyAdmin, apague todas as tabelas do banco do WHMCS (ou exclua e recrie o banco com o mesmo usuário). Só faça isso em instalação nova, nunca em WHMCS com clientes cadastrados.
- Restaure `configuration.php` a partir de uma cópia limpa de `configuration.php.new`.
- Confirme que a pasta `install` ainda está lá. Se você a apagou, extraia de novo só essa pasta do pacote.
- Corrija a causa pela tabela acima e rode o instalador.

Se o erro persistir, ative a exibição de erros temporariamente ou leia o `error_log` da pasta. A mensagem real quase sempre aparece ali, e é ela que o suporte vai pedir.

## Checklist reutilizável para cada cliente

Para padronizar entre vários projetos, transforme o processo em lista e marque item a item:

- Endereço final definido, DNS apontado e SSL ativo
- IP do servidor anotado junto com a chave de licença
- PHP do domínio na faixa suportada e ionCube confirmado via phpinfo
- Banco e usuário criados, privilégios completos, credenciais salvas no cofre de senhas
- `configuration.php` renomeado antes do instalador
- Administrador criado com usuário próprio e autenticação em dois fatores
- Pasta `install` apagada e `configuration.php` com permissão 400
- Cron configurado com o comando copiado do painel
- Aviso de cron sumiu do painel após algumas execuções
- Backup do banco agendado antes de cadastrar o primeiro cliente

Só depois dessa lista fechada faz sentido cadastrar o servidor WHM e o módulo cPanel no WHMCS. Se o provisionamento falhar nesse ponto, você já sabe que a instalação está sã e pode olhar direto para a integração.

Frase pronta para o cliente: "O sistema de cobrança já está instalado e licenciado. A próxima etapa é ligá-lo ao servidor para que as hospedagens sejam criadas automaticamente quando a fatura for paga."

