Pré Configuração

1. Depois de ativar o módulo Gateway e o Addon no WHMCS, faça login na sua conta Gerencianet, acesse API > Minhas Aplicações > Nome da Aplicação para criar sua Aplicação e gerar as credenciais Client ID e Client Secret;
2. Veja nesta imagem onde encontrar essa opção no antigo painel de controle Gerencianet e neste imagem onde se encontra essa opção na versão mais recente do painel de controle
3. No painel de controle WHMCS, navegue até Opções > Pagamentos > Portais para Pagamento > All Payment Gateways e clique  "Gofas Gerencianet - Boleto" para ativar o módulo;
4. Crie um campo personalizado de cliente para CPF e/ou CNPJ, ou se preferir, criar dois campos distintos, um campo apenas para CPF e outro campo para CNPJ. O módulo identifica os campos do perfil do cliente automaticamente

Opções do Módulo

Veja uma demonstração da tela de configurações do módulo clicando aqui.

1. Client_Id Produção: (Obrigatório) Cole a Client_Id encontrada na aba Produção da sua aplicação;
2. Client Secret Produção: (Obrigatório) Cole a Client Secret encontrada na aba Produção da sua aplicação;
3. Client_Id Desenvolvimento: (Obrigatório) Cole a Client_Id encontrada na aba Desenvolvimento da sua aplicação;
4. Client Secret Desenvolvimento:(Obrigatório) Cole a Client Secret encontrada na aba Desenvolvimento da sua aplicação;
5. Modo de Testes / Sandbox: Marque essa opção para alternar entre o modo Desenvolvimento e Produção;
6. Modo Diagnóstico / Debug: Marque essa opção para exibir resultados e erros retornados pela API Gerencianet e API interna do WHMCS. Use isso apenas em modo de testes ou se precisar diagnosticar erros;
7. Baixa via cron: Verifica o status dos boletos cada vez que o cron do WHMCS roda e da baixa nas faturas pagas automaticamente. A baixa via notificação de pagamentos (callback) será desativada ao ativar essa opção;
8. Salvar Logs: Salva informações de diagnóstico no menu Utilitários > Logs > Log de Módulo do painel de controle do WHMCS. Para essa opção funcionar, é necessário acessar Utilitários > Logs > Log de Módulo e ativar o debug de módulo clicando em "Ativar Log de Debug";
9. Administrador do WHMCS: (Obrigatório) Insira o nome de usuário ou ID do administrador com permissão de uso da API interna do WHMCS;
10. Valor da tarifa por Boleto: (Opcional) Insira o valor da comissão paga à Gerencianet a cada Boleto com pagamento confirmado. Esse valor não será somado ao total do boleto, servirá apenas para calcular e preencher o campo "Taxas" (fee) da lista de transações do WHMCS. Use ponto(.) para separar casas decimais, ex.: 1.5;
11. Valor mínimo do Boleto:  (Opcional) Insira o valor mínimo da fatura para permitir pagamento via Boleto, 5 equivale à R$ 5,00. O valor mínimo padrão é R$5,00. Use ponto(.) para separar casas decimais, ex.: 1.5;
12. Informações do Boleto no email: Adiciona link, linha digitável, vencimento e outras informações do boleto no corpo dos emails de faturas. Essa opção faz o módulo gerar os boletos no momento em que a fatura é gerada, (do contrário o Boleto é gerado no 1º acesso à Fatura). Veja abaixo, nas configurações do addon, a lista de tags disponíveis.
13. Substituir link da fatura por link do boleto: Substitui o URL da Fatura pelo URL do Boleto nos emails de "Nova Fatura" (tag {$invoice_link} do template de email Invoice Created).
14. Cancelar Boleto ao cancelar Fatura: (Opcional) Cancela o Boleto associado à uma fatura quando essa fatura é cancelada no WHMCS;
15. Cancelar Boleto Vencido: (Opcional) Cancela o Boleto gerado anteriormente pela Fatura antes de gerar novo Boleto/segunda via. Sem essa opção definida, o módulo altera a data de vencimento do Boleto vencido associado à Fatura, ou gera um novo boleto mas não altera o status do Boleto anterior;
16. Dias adicionais para nova data de vencimento de Boletos: Número de dias que serão somados a data do vencimento do Boleto ao gerar segunda via ou atualizar um boleto vencido. Essa opção aplica-se apenas a Faturas vencidas, faturas que ainda não venceram sempre irão gerar Boletos com a mesma data de vencimento da Fatura;
17. Notificar admins do WHMCS sobre erros: Escolha o departamento de suporte que receberá notificação por email quando houver erros ao gerar o boleto. Esse recurso possibilita uma tomada de ação antes que o cliente contacte o suporte ou desista da compra, como por exemplo, quando o boleto não é gerado por um erro de cadastro do cliente;
18. Tipo de Desconto Personalizado: Selecione o Campo Personalizado de Clientes que define o tipo de desconto personalizado em R$(Reais) e %(Porcentagem). Veja aqui como configurar os Campos Personalizados de Clientes;
19.  Valor do Desconto Personalizado: Escolha o Campo Personalizado de Clientes usado para aplicar descontos diferenciados para clientes específicos. Formato: Decimal, separado por ponto. Maior ou igual a 0.00 e menor que o valor da cobrança.
20. Desconto ou Taxa adicional: Escolha de deseja oferecer desconto ou acrescentar taxa para pagamentos via Boleto;
21. Tipo de desconto/taxa: Escolha se o desconto ou taxa será em Porcentagem ou em Reais;
22. Valor do Desconto ou Taxa: Valor que será abatido ou acrescentado ao valor total das faturas;
23. Validade do desconto: Defina o máximo de dias antes do vencimento para aplicar desconto.
    - Deixe em branco para aplicar desconto mesmo após o vencimento;
    - Insira 0 (zero) para aplicar desconto a Boletos gerados até a data de vencimento da Fatura;
    - Insira de 1 a X, sendo X = ao nº de dias antes do vencimento, que as Faturas são geradas para aplicar desconto apenas a Boletos gerados entre 1 e X dias antes da data de vencimento da Fatura.
    Ao ativar essa opção a data de vencimento do Boleto será igual a data de vencimento da Fatura - (menos) o nº de dias definido nesse campo. Será adicionada a instrução ao caixa "não aceitar pagamento após o vencimento";
24. Multa após o vencimento: Multa cobrada após o vencimento (máximo 10%). Use ponto(.) para separar casas decimais, ex.: 1.5;
25. Juros após o vencimento: Juros por dia cobrados após o vencimento (Mínimo de 0.001 e máximo de 0.33). Use ponto(.) para separar casas decimais;
26. Exibir linha digitável: Exibe a linha digitável/código de barras do Boleto, abaixo do botão "visualizar boleto";
27. Exibir data de Vencimento: Exibe a data de vencimento do Boleto na fatura, abaixo do botão "visualizar boleto";
28. Exibir Desconto / Taxa na fatura: Assinale se desejar informar sobre o Desconto ou Taxa na fatura;
29. Redirecionar para o Boleto: Redireciona o cliente diretamente para o URL do boleto ao acessar a fatura. Adicione &redirectToBillet=false ao URL da fatura para desativar em acessos específicos, exemplo: https://whmcs.gofas.net/viewinvoice.php?id=4800&redirectToBillet=false. Nos templates de email a mergetag ficaria desta forma: {$invoice_link}&redirectToBillet=false
30. Imagem do botão "Visualizar Boleto": Insira o URL da imagem que será usada como botão "Visualizar Boleto" (tamanho recomendado: 160x43px);
31. Mensagem ao cliente: Inclui no boleto uma mensagem personalizada para o cliente (máximo 80 caracteres);
32. 1ª Instrução do boleto: Insira a 1ª linha de instruções do Boleto;
33. 2ª Instrução do boleto: Insira a 2ª linha de instruções do Boleto;
34. 3ª Instrução do boleto: Insira a 3ª linha de instruções do Boleto;
35. 4ª Instrução do boleto: Insira a 4ª linha de instruções do Boleto;
    Opções customizadas
    Nessa sessão serão exibidas as opções personalizadas, que podem ser adicionadas com conhecimento básico em PHP e sem editar diretamente o código do módulo, como descrito neste tutorial.

Exibir informações do Boleto nos Emails

Antes de configurar os templates de email, tenha certeza de ter executado o segundo passo da sessão "Instalação" referente a instalação do Móduo Addon.
Com o módulo Gateway e o Addon ativados, você encontrará as tags de email disponíveis logo abaixo do editor dos templates de email do WHMCS:

Tags de mesclagem (mergetags) disponíveis:

{$ggnb_billet_info}: Exibe em conjunto todas as informações do boleto formatadas em um bloco HTML semelhante a tag padrão `{$invoice_html_contents}` (exemplo);

{$ggnb_link} - Exibe o link do Boleto. Pode ser utilizado em um botão de forma semelhante a esta: <a href="{$ggnb_link}">Visualizar Boleto</a>;

{$ggnb_pdf} - Exibe o link do Boleto em PDF;

{$ggnb_barcode} - Exibe a linha digitável do boleto (representação numérica do código de barras);

{$ggnb_expire_at} - Exibe a data de vencimento do Boleto;

{$ggnb_total} - Exibe o valor total do Boleto;

{$ggnb_charge_id} - Exibe o ID da transação registrada na API Gerencianet;

{$ggnb_api_mode} - Exibe sandbox para boletos gerados no modo de teste e live, para Boletos gerados no modo produção da API;

{$ggnb_debug} - Exibe informações de depuração no corpo do email (use apenas quando precisar coletar informações de diagnóstico);

• A tarifa do Boleto paga separadamente à Gerencianet é de R$2,37 para usuários do módulo Gofas Gerencianet Boleto para WHMCS;
• Sempre faça backup antes de mudar algo em seu sistema.
• Para evitar erros ao editar os templates de email, por copiar e colar texto com formatação no editor de texto do WHMCS, abra o editor HTML e copie o template para um editor de código (Dreamweaver ou Brackets por exemplo), edite, abra novamente o editor de HTML dos templates de email do WHMCS e cole o modelo atualizado. Veja na imagem abaixo onde encontrar o editor HTML dos templates de email;
  
• Configurações Personalizadas e alterações no funcionamento do módulo podem ser realizadas, sem editar o código original, podendo atualizar o módulo no futuro sem perder suas customizações.
  Para mais informações consulte o Tutorial: Adicionar configurações customizadas ao Módulo Gerencianet Boleto para WHMCS;
• Para Diagnosticar Erros em mais detalhes, consulte o tutorial: Diagnosticar erros do módulo Gerencianet Boleto para WHMCS;

Erros comuns:

Além dos códigos de erro GN API, fornecemos mensagens de erro específicos do módulo, humanamente entendíveis, para facilitar o diagnóstico e solução de dificuldades.
Erros que necessitam da interação do cliente não mostram códigos na tela, como no caso de CPF ou outras informações cadastrais inválidas, nesse caso é exibida uma mensagem personalizada com instruções e o link direto para a edição do cadastro, para que o próprio cliente possa alterar suas informações cadastrais e continuar o pagamento, sem ter de acionar o suporte.

Opcionalmente, você pode configurar o módulo para disparar um email ao departamento de suporte encarregado cada vez que um dos seus clientes ver um erro ao gerar o boleto, essa é uma ótima forma de identificar e corrigir o erro antes do cliente acionar o suporte e assim minimizar o impacto negativo que erros de aplicações podem causar :P. A seguir você confere os erros mais comuns e como são impressos na tela:

• Tela branca ou erro 500, veja o artigo: Como resolver o Erro 500, tela branca e os “falsos erros” do WHMCS;

• "Erro de comunicação na 1ª conexão com a GN API".
  Acontece no momento de verificar se a fatura atual já gerou algum boleto.
  Solução: Verifique as os suas credenciais (client_id e client_secret) e as configurações do módulo, lembre-se de que as credenciais são diferentes para o ambiente de produção e desenvolvimento;
• "Falha ao gerar a transação, na 2º conexão com a GN API". Significa que o sistema constatou que não há nenhum boleto dentro do prazo de vencimento associado a fatura atual, mas não conseguiu gerar a transação. Verifique se os campos "Descrição" e "Valor total" da fatura estão configurados corretamente;
• "Erro de comunicação na 2º conexão com a GN API".
  Significa que o sistema constatou que não há nenhum boleto dentro do prazo de vencimento associado a fatura atual, mas não conseguiu se conectar novamente para gerar a transação. Ative a opção "Debug" do módulo para diagnosticar com maiores detalhes;
• "Erro de comunicação na 3º conexão com a GN API".
  Acontece no momento em que seria gerado o Boleto. Ative a opção "Debug" do módulo para diagnosticar com maiores detalhes;
• "Não foi possível gerar o boleto porque o seu CPF está incorreto."
  "Não foi possível gerar o boleto porque o seu Telefone está incorreto."
• "Não foi possível gerar o boleto porque o seu Nome e/ou Sobrenome estão incorretos."