Home
»
Como Criar Seu Gateway Personalizado para o Zapcel WHMC

Como Criar Seu Gateway Personalizado para o Zapcel WHMC

novembro 21, 2025

6 min de leitura

Guia completo para desenvolvedores – Zapcel WHMCS 2.1.1

📋 Índice

Introdução
Pré-requisitos
Estrutura de um Gateway
Passo 1: Criar o Arquivo
Passo 2: Descobrir o Nome do Gateway
Passo 3: Encontrar Tabelas e Campos
Passo 4: Implementar Extração de PIX
Passo 5: Implementar Extração de Boleto
Passo 6: Ativar o Gateway
Exemplos Práticos
Compartilhe com a Comunidade
Perguntas Frequentes (FAQ)

🎯 Introdução

O módulo Zapcel WHMCS permite que você envie mensagens automáticas via WhatsApp para seus clientes, incluindo dados de pagamento como PIX e Boleto. Para que o sistema consiga extrair esses dados, você precisa criar um gateway personalizado que saiba onde seu gateway de pagamento armazena essas informações no banco de dados.

Este tutorial ensina como criar seu próprio gateway de forma simples e rápida, permitindo que o Zapcel extraia automaticamente:

✅ Dados de PIX

QR Code: URL ou base64 da imagem

Código Copia e Cola: String do PIX

Data de Expiração: (opcional)

✅ Dados de Boleto

Linha Digitável: Código de barras numérico

URL do PDF: Link para download/visualização

Código de Barras: (opcional)

Data de Vencimento: (opcional)

📚 Pré-requisitos

Antes de começar, certifique-se de ter:

Requisito	Descrição	Obrigatório
Conhecimento PHP	Básico (variáveis, arrays, classes)	✅
Acesso ao Banco de Dados	phpMyAdmin ou MySQL Workbench	✅
Gateway de Pagamento Instalado	Iugu, MercadoPago, PagHiper, etc.	✅
Zapcel WHMCS 2.1+	Módulo instalado e configurado	✅
Editor de Código	VS Code, Sublime, PHPStorm, etc.	⚪

🏗️ Estrutura de um Gateway

Todo gateway no Zapcel segue uma estrutura padronizada. Os arquivos ficam localizados em:

/modules/addons/zapcel/gateways/
├── GatewayInterface.php      # Interface (NÃO MODIFICAR)
├── AbstractGateway.php        # Classe abstrata (NÃO MODIFICAR)
├── IuguGateway.php           # Exemplo: Gateway Iugu
└── SeuGateway.php            # Seu novo gateway aqui

⚠️ Importante

Nunca modifique os arquivos GatewayInterface.php e AbstractGateway.php. Eles são a base do sistema e suas alterações serão perdidas em atualizações.

📝 Passo 1: Criar o Arquivo

Crie um novo arquivo PHP na pasta /modules/addons/zapcel/gateways/ seguindo a convenção de nomenclatura:

[NomeDoGateway]Gateway.php

📌 Exemplos de Nomenclatura:

Gateway	Nome do Arquivo	Classe
Mercado Pago	`MercadoPagoGateway.php`	`MercadoPagoGateway`
Banco Inter	`BancoInterGateway.php`	`BancoInterGateway`
PagHiper	`PagHiperGateway.php`	`PagHiperGateway`
Asaas	`AsaasGateway.php`	`AsaasGateway`

🎨 Template Básico:

Cole este código no arquivo criado e adapte conforme necessário:

<?php

namespace WHMCS\Module\Addon\Zapcel\Gateways;

use Illuminate\Database\Capsule\Manager as Capsule;

/**
 * Gateway: [NOME DO SEU GATEWAY]
 * 
 * Extrai dados de PIX e Boleto do gateway [NOME]
 * 
 * @author Seu Nome
 * @version 1.0.0
 */
class SeuGatewayGateway extends AbstractGateway
{
    /**
     * Nome do gateway (deve ser EXATAMENTE o nome do módulo no WHMCS)
     * @var string
     */
    protected $gatewayName = 'seugateway';

    /**
     * Extrai dados do PIX da fatura
     * 
     * @param int $invoiceId ID da fatura
     * @return array|null Array com dados do PIX ou null se não houver
     */
    public function extractPixData($invoiceId)
    {
        try {
            // TODO: Implementar extração de dados do PIX
            
            return null;
        } catch (\Exception $e) {
            return null;
        }
    }

    /**
     * Extrai dados do Boleto da fatura
     * 
     * @param int $invoiceId ID da fatura
     * @return array|null Array com dados do Boleto ou null se não houver
     */
    public function extractBoletoData($invoiceId)
    {
        try {
            // TODO: Implementar extração de dados do Boleto
            
            return null;
        } catch (\Exception $e) {
            return null;
        }
    }
}

🔍 Passo 2: Descobrir o Nome do Gateway

O nome do gateway deve ser exatamente o nome do módulo de pagamento no WHMCS. Para descobrir:

📂 Método 1: Verificar Pasta de Módulos

Acesse a pasta /modules/gateways/ e veja o nome do arquivo do seu gateway:

/modules/gateways/
├── iugu.php           → gatewayName = 'iugu'
├── mercadopago.php    → gatewayName = 'mercadopago'
├── paghiper.php       → gatewayName = 'paghiper'
└── seugateway.php     → gatewayName = 'seugateway'

🗄️ Método 2: Consultar Banco de Dados

Execute esta query no phpMyAdmin:

SELECT DISTINCT gateway FROM tblinvoices WHERE gateway != '' ORDER BY gateway;

Isso retornará todos os gateways em uso no seu WHMCS.

🗄️ Passo 3: Encontrar Tabelas e Campos

Agora você precisa descobrir onde seu gateway armazena os dados de PIX e Boleto no banco de dados.

🔎 Método 1: Buscar Tabelas do Gateway

Execute no phpMyAdmin:

-- Listar todas as tabelas do gateway
SHOW TABLES LIKE '%seugateway%';

-- Ou buscar por palavras-chave
SHOW TABLES LIKE '%pix%';
SHOW TABLES LIKE '%boleto%';

📊 Método 2: Ver Estrutura da Tabela

Depois de encontrar a tabela, veja sua estrutura:

-- Ver estrutura da tabela
DESCRIBE mod_seugateway_pix;

-- Ou
SHOW COLUMNS FROM mod_seugateway_pix;

🔬 Método 3: Analisar Dados Reais

Crie uma fatura de teste e veja os dados salvos:

-- Buscar dados de uma fatura específica
SELECT * FROM mod_seugateway_pix WHERE invoice_id = 123;

-- Ver todos os campos e valores
SELECT * FROM mod_seugateway_pix LIMIT 1;

💡 Dica Pro

Procure por campos com nomes como: qrcode, qr_code, pix_code, linha_digitavel, barcode, pdf_url, boleto_url, etc.

💳 Passo 4: Implementar Extração de PIX

Agora vamos implementar o método extractPixData() que retorna os dados do PIX.

📋 Formato de Retorno Esperado:

return [
    'qrcode' => 'URL ou base64 da imagem QR Code',
    'copiaecola' => 'Código PIX Copia e Cola',
    'expiration' => '2024-12-31 23:59:59' // Opcional
];

🎯 Exemplo de Implementação:

public function extractPixData($invoiceId)
{
    try {
        // Buscar dados do PIX no banco
        $pixData = Capsule::table('mod_seugateway_pix')
            ->where('invoice_id', $invoiceId)
            ->first();

        // Se não houver dados, retorna null
        if (!$pixData) {
            return null;
        }

        // Retorna array com dados formatados
        return [
            'qrcode' => $pixData->qr_code_url,
            'copiaecola' => $pixData->pix_code,
            'expiration' => $pixData->expiration_date ?? null
        ];
        
    } catch (\Exception $e) {
        // Em caso de erro, retorna null
        return null;
    }
}

⚠️ Importante

Sempre use try-catch para evitar erros

Retorne null se não houver dados

Os campos qrcode e copiaecola são obrigatórios

O campo expiration é opcional

📄 Passo 5: Implementar Extração de Boleto

Agora vamos implementar o método extractBoletoData() que retorna os dados do Boleto.

📋 Formato de Retorno Esperado:

return [
    'linha_digitavel' => 'Linha digitável do boleto',
    'pdf_url' => 'URL do PDF do boleto',
    'barcode' => 'Código de barras' // Opcional
    'expiration' => '2024-12-31' // Opcional
];

🎯 Exemplo de Implementação:

public function extractBoletoData($invoiceId)
{
    try {
        // Buscar dados do Boleto no banco
        $boletoData = Capsule::table('mod_seugateway_boleto')
            ->where('invoice_id', $invoiceId)
            ->first();

        // Se não houver dados, retorna null
        if (!$boletoData) {
            return null;
        }

        // Retorna array com dados formatados
        return [
            'linha_digitavel' => $boletoData->linha_digitavel,
            'pdf_url' => $boletoData->pdf_url,
            'barcode' => $boletoData->barcode ?? null,
            'expiration' => $boletoData->due_date ?? null
        ];
        
    } catch (\Exception $e) {
        // Em caso de erro, retorna null
        return null;
    }
}

✅ Passo 6: Ativar o Gateway

Após salvar o arquivo, siga estes passos para ativar seu gateway:

🚀 Passos para Ativação:

Acesse o painel admin do WHMCS

Vá em Addons → Zapcel → Gateways

Seu gateway aparecerá automaticamente na lista

Clique no card do seu gateway para selecioná-lo

Confirme a ativação

Pronto! O sistema começará a usar seu gateway

💡 Testando o Gateway

Para testar se está funcionando:

Crie uma fatura de teste

Gere o PIX/Boleto pelo seu gateway

Vá em Addons → Zapcel → Templates

Use as variáveis {codigopix}, {qr_code_url}, {linhadigitavel}

Envie uma mensagem de teste

📚 Exemplos Práticos

Veja exemplos reais de gateways já implementados pela comunidade:

💜 Exemplo 1: Gateway Iugu

<?php

namespace WHMCS\Module\Addon\Zapcel\Gateways;

use Illuminate\Database\Capsule\Manager as Capsule;

/**
 * Gateway: Iugu
 * @author Edvan - Hostcel
 * @version 1.0.0
 */
class IuguGateway extends AbstractGateway
{
    protected $gatewayName = 'iugu';

    public function extractPixData($invoiceId)
    {
        try {
            $pixData = Capsule::table('mod_iugu_pix')
                ->where('invoiceid', $invoiceId)
                ->first();

            if (!$pixData) {
                return null;
            }

            return [
                'qrcode' => $pixData->qrcode,
                'copiaecola' => $pixData->qrcode_text,
            ];
        } catch (\Exception $e) {
            return null;
        }
    }

    public function extractBoletoData($invoiceId)
    {
        try {
            $boletoData = Capsule::table('mod_iugu_boleto')
                ->where('invoiceid', $invoiceId)
                ->first();

            if (!$boletoData) {
                return null;
            }

            return [
                'linha_digitavel' => $boletoData->digitable_line,
                'pdf_url' => $boletoData->pdf,
            ];
        } catch (\Exception $e) {
            return null;
        }
    }
}

💙 Exemplo 2: Gateway Mercado Pago

<?php

namespace WHMCS\Module\Addon\Zapcel\Gateways;

use Illuminate\Database\Capsule\Manager as Capsule;

/**
 * Gateway: Mercado Pago
 * @author Comunidade Zapcel
 * @version 1.0.0
 */
class MercadoPagoGateway extends AbstractGateway
{
    protected $gatewayName = 'mercadopago';

    public function extractPixData($invoiceId)
    {
        try {
            // Mercado Pago salva na tabela tblinvoices
            $invoice = Capsule::table('tblinvoices')
                ->where('id', $invoiceId)
                ->where('gateway', 'mercadopago')
                ->first();

            if (!$invoice || !$invoice->notes) {
                return null;
            }

            // Decodifica JSON do campo notes
            $notes = json_decode($invoice->notes, true);

            if (!isset($notes['pix'])) {
                return null;
            }

            return [
                'qrcode' => $notes['pix']['qr_code_base64'],
                'copiaecola' => $notes['pix']['qr_code'],
            ];
        } catch (\Exception $e) {
            return null;
        }
    }

    public function extractBoletoData($invoiceId)
    {
        // Mercado Pago não usa boleto tradicional
        return null;
    }
}

🧡 Exemplo 3: Gateway PagHiper

<?php

namespace WHMCS\Module\Addon\Zapcel\Gateways;

use Illuminate\Database\Capsule\Manager as Capsule;

/**
 * Gateway: PagHiper
 * @author Comunidade Zapcel
 * @version 1.0.0
 */
class PagHiperGateway extends AbstractGateway
{
    protected $gatewayName = 'paghiper';

    public function extractPixData($invoiceId)
    {
        try {
            $pixData = Capsule::table('mod_paghiper')
                ->where('invoice_id', $invoiceId)
                ->where('type', 'pix')
                ->first();

            if (!$pixData) {
                return null;
            }

            return [
                'qrcode' => $pixData->emv,
                'copiaecola' => $pixData->emv,
            ];
        } catch (\Exception $e) {
            return null;
        }
    }

    public function extractBoletoData($invoiceId)
    {
        try {
            $boletoData = Capsule::table('mod_paghiper')
                ->where('invoice_id', $invoiceId)
                ->where('type', 'boleto')
                ->first();

            if (!$boletoData) {
                return null;
            }

            return [
                'linha_digitavel' => $boletoData->digitable_line,
                'pdf_url' => $boletoData->url_slip_pdf,
                'barcode' => $boletoData->bar_code,
            ];
        } catch (\Exception $e) {
            return null;
        }
    }
}

🤝 Compartilhe com a Comunidade

Criou um gateway funcional? Compartilhe com a comunidade! Isso ajuda outros desenvolvedores e fortalece o ecossistema Zapcel.

📤 Como Compartilhar Seu Gateway

Envie seu gateway para a comunidade e ajude outros desenvolvedores!

🚀 Enviar Gateway para o GitHub

📋 Checklist Antes de Compartilhar:

✓	Item
☐	Código testado e funcionando
☐	Comentários e documentação no código
☐	Try-catch em todos os métodos
☐	Retorna null quando não há dados
☐	Nome do arquivo e classe corretos
☐	Informações de autor e versão

💡 Benefícios de Compartilhar

Ajuda outros desenvolvedores

Recebe feedback e melhorias da comunidade

Seu nome aparece como colaborador

Fortalece o ecossistema Zapcel

❓ Perguntas Frequentes (FAQ)

❓ Meu gateway não aparece na lista. O que fazer?

Verifique se:

O arquivo está na pasta correta (/modules/addons/zapcel/gateways/)
O nome do arquivo termina com Gateway.php
A classe estende AbstractGateway
Não há erros de sintaxe no código

❓ As variáveis aparecem vazias nas mensagens. Por quê?

Possíveis causas:

O gateway não está ativado em Addons → Zapcel → Gateways
Os nomes dos campos no banco estão incorretos
A fatura não tem dados de PIX/Boleto gerados
O método extractPixData() ou extractBoletoData() está retornando null

❓ Posso ter múltiplos gateways ativos ao mesmo tempo?

Não. O Zapcel permite apenas 1 gateway ativo por vez. Se você usa múltiplos gateways de pagamento, crie um gateway personalizado que detecte qual gateway foi usado na fatura e busque os dados correspondentes.

❓ Meu gateway salva os dados em JSON. Como extrair?

Use json_decode() para decodificar o JSON:

$data = json_decode($invoice->notes, true);
$pixCode = $data['pix']['code'] ?? null;

❓ Preciso reiniciar o WHMCS após criar o gateway?

Não! O Zapcel detecta automaticamente novos gateways. Basta recarregar a página Addons → Zapcel → Gateways.

❓ Como debugar meu gateway?

Adicione logs temporários:

// No método extractPixData()
file_put_contents('/tmp/zapcel_debug.log', print_r($pixData, true), FILE_APPEND);

🎉 Parabéns!

Você aprendeu a criar gateways personalizados para o Zapcel WHMCS!

Agora você pode extrair dados de PIX e Boleto de qualquer gateway de pagamento e enviar mensagens automáticas via WhatsApp para seus clientes.

Como Criar Seu Gateway Personalizado para o Zapcel WHMC

📋 Índice

🎯 Introdução

✅ Dados de PIX

✅ Dados de Boleto

📚 Pré-requisitos

🏗️ Estrutura de um Gateway

⚠️ Importante

📝 Passo 1: Criar o Arquivo

📌 Exemplos de Nomenclatura:

🎨 Template Básico:

🔍 Passo 2: Descobrir o Nome do Gateway

📂 Método 1: Verificar Pasta de Módulos

🗄️ Método 2: Consultar Banco de Dados

🗄️ Passo 3: Encontrar Tabelas e Campos

🔎 Método 1: Buscar Tabelas do Gateway

📊 Método 2: Ver Estrutura da Tabela

🔬 Método 3: Analisar Dados Reais

💡 Dica Pro

💳 Passo 4: Implementar Extração de PIX

📋 Formato de Retorno Esperado:

🎯 Exemplo de Implementação:

⚠️ Importante

📄 Passo 5: Implementar Extração de Boleto

📋 Formato de Retorno Esperado:

🎯 Exemplo de Implementação:

✅ Passo 6: Ativar o Gateway

🚀 Passos para Ativação:

💡 Testando o Gateway

📚 Exemplos Práticos

💜 Exemplo 1: Gateway Iugu

💙 Exemplo 2: Gateway Mercado Pago

🧡 Exemplo 3: Gateway PagHiper

🤝 Compartilhe com a Comunidade

📤 Como Compartilhar Seu Gateway

📋 Checklist Antes de Compartilhar:

💡 Benefícios de Compartilhar

❓ Perguntas Frequentes (FAQ)

❓ Meu gateway não aparece na lista. O que fazer?

❓ As variáveis aparecem vazias nas mensagens. Por quê?

❓ Posso ter múltiplos gateways ativos ao mesmo tempo?

❓ Meu gateway salva os dados em JSON. Como extrair?

❓ Preciso reiniciar o WHMCS após criar o gateway?

❓ Como debugar meu gateway?

🎉 Parabéns!

Tutoriais Relacionados

Abaixo temos mais tutoriais relacionados ao assunto acima

Como instalar certificado SSL em localhost para XAMPP

Usando arquivos SVG no WordPress

Como Resolver ERR_TOO_MANY_REDIRECTS no WordPress

Comentários

Serviços

Páginas