whmcs-woovi-gateway

Integração completa de pagamentos PIX via Woovi (antiga OpenPix) para WHMCS, com geração de QR Code na fatura e baixa automática via webhook.

Módulo de Gateway Woovi (OpenPix) para WHMCS

Integração completa de pagamentos PIX via Woovi (antiga OpenPix) para WHMCS, com geração de QR Code na fatura e baixa automática via webhook.

  ➕     ➕  

---

👤 Créditos

Este projeto foi desenvolvido por:

• Samuel de Sousa Santos
• YouTube: https://www.youtube.com/c/samucatutoriais
• Contato Comercial: samucamg@gmail.com

---

🖼️ Módulo em Ação 🖼️

Veja como o QR Code do PIX é exibido diretamente na fatura do seu cliente.

---

✨ Funcionalidades

• Geração de PIX na Fatura: Gera dinamicamente um QR Code e um código "PIX Copia e Cola" na página da fatura do cliente.
• Baixa Automática: Utiliza webhooks para processar a confirmação de pagamento e marcar a fatura como "Paga" automaticamente, sem intervenção manual.
• Segurança HMAC: Implementa o método de validação de assinatura HMAC recomendado pela Woovi, garantindo que apenas notificações legítimas sejam processadas.
• Ambiente de Testes: Permite alternar facilmente entre o ambiente de produção e o sandbox da Woovi.
• Prevenção de Duplicidade: O módulo verifica se já existe uma cobrança para uma fatura antes de tentar criar uma nova, permitindo que o cliente recarregue a página sem gerar erros.

---

🚀 Guia de Instalação e Configuração

Siga os passos na ordem correta para garantir uma instalação sem erros.

Passo 1: Instalar o Módulo no WHMCS

Primeiro, vamos colocar os arquivos do módulo no seu servidor.

1. Vá até a seção de Releases aqui no GitHub e baixe a última versão do gateway (whmcs-woovi-gateway.zip).
2. Descompacte o arquivo .zip no seu computador.
3. Envie a pasta modules que foi descompactada para a raiz da sua instalação do WHMCS. Se o seu sistema pedir para sobrescrever a pasta, pode confirmar. Isso apenas adicionará os arquivos do nosso módulo dentro dela.

Passo 2: Criar e Configurar a API (AppID)

Agora, vamos obter a primeira chave na Woovi e configurar no WHMCS.

1. Acesse o painel da Woovi, vá para API/Plugins na barra lateral e clique em Nova API/Plugin.

2. Dê um nome para a integração (ex: "Gateway WHMCS") e selecione API. Clique em Salvar.

3. Após a autenticação de dois fatores, a Woovi exibirá sua Chave da Aplicação (AppID). Copie esta chave longa!

4. Agora, vá ao seu WHMCS:

   • Acesse o painel de administrador.
   • Vá em Configuração > Pagamentos > Módulos de Pagamento e ative o "Woovi PIX".
   • No campo Woovi AppID, cole a chave longa que você acabou de copiar.
   • Importante: Se você estiver usando uma conta de testes da Woovi, marque a caixa "Modo Sandbox". Se for para pagamentos reais, deixe desmarcada.
   • Clique em Salvar. Não preencha o campo HMAC ainda.

Passo 3: Criar e Configurar o Webhook (HMAC Key)

Com o módulo já no lugar, a criação do webhook funcionará perfeitamente.

1. Volte ao painel da Woovi, na seção API/Plugins, e clique na aba Webhooks.
2. Crie um Novo Webhook:
   • URL: Insira a URL completa para o arquivo de callback: https://[SEU_DOMINIO_WHMCS.COM]/modules/gateways/callback/woovipix.php.
   • Evento: Selecione o evento Cobrança paga.
   • Clique em Salvar. A Woovi testará a URL e, como nosso script já está no lugar, a criação será um sucesso!
3. Após criar, clique nos detalhes do webhook recém-criado. A Woovi irá exibir a HMAC Secret Key.
4. Copie esta HMAC Secret Key.
5. Volte pela última vez ao WHMCS, na configuração do módulo Woovi PIX.
6. Cole a HMAC Secret Key no campo correspondente e salve as alterações.

Pronto! 🎉 Seu gateway está 100% configurado e pronto para automatizar seus pagamentos PIX.

---

🧠 Aprendizados do Desenvolvimento

Durante a criação deste módulo, enfrentei alguns desafios que serviram como grandes aprendizados:

• Dois Métodos de Segurança de Webhook: A descoberta mais crucial foi que a Woovi oferece dois sistemas de validação distintos. A falha inicial foi tentar usar o método de assinatura de API (Client Secret) em um webhook que exigia o método de validação HMAC (HMAC Secret Key). Alinhar o código ao método correto resolveu os erros 401 Unauthorized.
• Prevenção de Cobranças Duplicadas: Implementei a lógica de "buscar antes de criar". O módulo primeiro verifica via GET se uma cobrança já existe antes de tentar criar uma nova via POST, evitando erros de duplicidade.
• Carregamento de Funções do WHMCS: Um erro 500 Internal Server Error no callback revelou a necessidade de incluir manualmente require_once 'includes/gatewayfunctions.php'; para que scripts externos tivessem acesso às funções de gateway.
• Múltiplos Eventos de Webhook: O script final foi tornado flexível para entender e processar os diferentes eventos de pagamento bem-sucedido que a Woovi pode enviar (CHARGE_COMPLETED e TRANSACTION_RECEIVED).

---

📁 Arquivos do Módulo

• woovipix.php - O arquivo principal do gateway (configuração e exibição na fatura).
• callback/woovipix.php - O endpoint do webhook (recebimento e processamento dos pagamentos).

---

📄 Licença

Este projeto é de código aberto e pode ser utilizado e modificado livremente.