Requisitos do sistema: PHP >= 7.1.+, WHMCS >= 7.10.+

• Baixe, descompacte o arquivo gofasgerencianetboleto.zip
• Copie o arquivo /modules/gateways/gofasgerencianetboleto.php e o diretório /modules/gateways/gofasgerencianetboleto/, (encontrados na pasta recém descompactada) para dentro do diretório de gateways do WHMCS: /modules/gateways/;
• Ative o módulo na interface administrativa do no menu `Opções > Pagamentos > Portais para Pagamentos > Aba All Payment Gateways`.

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. Administrador do WHMCS: (Obrigatório) Defina o administrador com permissões para utilizar a API interna do WHMCS;
6. Modo de Testes / Sandbox: Marque essa opção para alternar entre o modo Desenvolvimento e Produção;
7. 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;
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);

0.2.3

• Nova opção: Valor da tarifa por Boleto. Agora é possível configurar o valor relativo à comissão paga à Gerencianet a cada Boleto com pagamento confirmado. Essa informação servirá para calcular e preencher o campo "Taxas" (fees) da lista de transações, fazendo o cálculo do valor líquido recebido via Boletos;
• Nova opção: Mensagem ao cliente. Agora é possível configurar uma mensagem personalizada com até 80 caracteres, que será exibida entre o cabeçalho e o descritivo do Boleto com o título "Observação". O intuito dessa nova funcionalidade é que não seja necessário utilizar as linhas de instrução para mensagens direcionadas ao cliente, afinal, as linhas de instrução são mensagens destinadas ao Caixa e não devem ser utilizadas para outro propósito;
• Nova opção: Multa após o vencimento. Agora é possível configurar multa em percentagem (%), que será adicionada ao valor total do Boleto quando o mesmo for gerado após o vencimento e também adiciona instruções ao Caixa informando a multa;
• Nova opção: Juros por dia após o vencimento. Agora é possível configurar juros por dia em percentagem (%), que será adicionado ao valor total do Boleto quando o mesmo for gerado após o vencimento e também adiciona instruções ao Caixa informando sobre os juros;
• Melhoria: Agora a opção "Dias adicionais à data de vencimento do Boleto" permite gerar o Boleto com vencimento para a mesma data que foi gerado, ao configurar essa opção com 0 (zero).
• Melhoria: Textos explicativos das configurações foram reformulados e as configurações mais sensíveis contém links com mais informações;
• Melhoria: Modo debug agora contém mais explicações, links para artigos com mais informações e destaca as mensagens de erro em letras vermelhas para localização mais rápida do trecho onde o script foi interrompido;
• Melhoria: Otimização e revisão completa do código, agora trechos do script que eram repetidos em situações diferentes foram convertidos em funções, que podem ser executadas separadamente e em casos diferentes apenas alterando os argumentos;
• Melhoria: Callback agora inclui um debug completo do recebimento da notificação, verificação dos dados do Boleto e da Fatura (GN API e WHMCS API). O resultado do recebimento de notificações pode ser visualizado na sua conta Gerencianet > API > Aplicação > Produção ou Desenvolvimento > Histórico de Notificações;
• Corrigido o bug que adicionava o valor da taxa do Boleto com crédito ao cliente, após a confirmação do pagamento;
• Corrigido o bug que adicionava/abatia o valor da taxa ou desconto fixo (R$) de cada item da fatura, especificamente quando o admin configurava taxa ou desconto fixo e o sistema gerava faturas com mais de um item;

0.2.2

• Evita falhas ao gerar a data de vencimento do Boleto quando o admin não configura ou configura com 0(zero) a opção "Dias adicionais à data de vencimento do Boleto";
• Alerta nas configurações que as opções "Debug" e "Redirecionar para o Boleto" não podem ser usadas simultaneamente;
• Melhora mensagens de erro atualizadas na API Gerencianet;

0.2.0

• Agora os Boletos são gerados apenas quando o cliente acessa a Fatura;
• Agora quando uma fatura é acessada após o vencimento, o Boleto gerado anteriormente tem a data de vencimento atualizada, ao invés de gerar um novo boleto;
• Nova opção: Cancelar o boleto vencido e gerar um novo. Ao marcar essa opção, quando o cliente acessar uma Fatura vencida o módulo vai cancelar o Boleto associado à ela e gerar um novo;
• Adicionada a capacidade de reportar todos os erros e avisos do php, independente da configuração do servidor;
• Melhorias de segurança;
• Melhorias de compatibilidade com PHP < 5.6;
• Melhorias no callback, como a adição de um debugque grava as respostas do servidor nos logs das transações na API Gerencianet;

0.1.9

• Corrige erro "Fatal error: Class 'GerencianetGerencianet' not found " quando o boleto é gerado no fluxo de contratação do WHMCS;

0.1.8

• Nova opção: Valor mínimo para aceitar pagamentos via boleto;
• Nova opção: Dias adicionais à data de vencimento do Boleto. Se aplica a faturas vencidas, faturas que não venceram geram boletos com a mesma data de vencimento da fatura;
• Nova opção: Desconto ou Taxa adicional, em R$ (reais) ou % (porcentagem);
• Nova opção: Exibir Desconto ou Taxa na fatura;
• Nova opção: Novos campos para adicionar as credenciais Client_Id e Client_Secret de Desenvolvimento. Agora para alternar rapidamente entre Desenvolvimento/Produção basta assinalar/desassinalar a opção "Sandbox";
• Melhoria: Exibir Data de vencimento e Linha digitável agora são duas opções distintas e podem ser configuradas separadamente;
• Nova opção: Agora é possível configurar apenas um campo personalizado para CPF ou CNPJ, o módulo reconhece o tipo de documento e gera a cobrança como pessoa física ou jurídica de acordo com o documento informado. Ainda é possível utilizar dois campos, um campo para cada documento;
• Melhoria: Ao gerar uma cobrança como Pessoa Jurídica (CNPJ), se o cliente não preencheu o campo "Empresa", o módulo preenche esse campo automaticamente com o Nome e Sobrenome do cliente, evitando erros de validação da API Gerencianet;

0.1.7

• Agora não é mais obrigatório enviar o nome e CPF do cliente quando a cobrança é para Pessoa Jurídica, por padrão, o módulo vai ignorar o CPF se eles estiver incorreto ou ausente;
• Adicionada a opção "Exigir CPF e CNPJ de Pessoa Jurídica", no caso do admin desejar tornar obrigatório o envio também do nome e CPF da pessoa física que está concretizando o pagamento em nome da empresa, nesse caso será exibido um erro se o CPF ou o CNPJ estiverem incorretos;
• Agora se ocorrer um erro ao gerar Boleto devido ao CNPJ do cliente estar incorreto, o sistema vai tentar gerar o boleto com o CPF antes de exibir um erro;
• Adicionada a opção "Mostrar erro "CNPJ incorreto", no caso do admin desejar exibir um erro quando a cobrança não é realizada devido a CNPJ inválido, do contrário, o sistema tenta associar a cobrança ao CPF do cliente no caso de CNPJ incorreto ou ausente, como descrito na feature anterior;
• Agora o módulo adiciona um 0 (zero) no começo do CPF se esse tem 10 dígitos, como forma de impedir o erro "CPF Incorreto". O motivo dessa feature é por que muitas vezes que o CPF do cliente inicia com dígito zero, ele acredita que não precisa preencher esse dígito;
• Agora o módulo adiciona um 0 (zero) no começo do CNPJ se esse tem 13 dígitos, como forma de impedir o erro "CNPJ Incorreto" ou associar o Boleto ao CPF do cliente. O motivo dessa feature é o mesmo da anterior;

0.1.6

• Quando ativo o Debug é exibido apenas na visualização da fatura e não no admin;
• Quando ativo o Redirecionamento da fatura para o boleto só ocorre na visualização da fatura e não no admin.

0.1.5

• Adicionadas as opções "Ordem do campo CPF" e "Ordem do campo CNPJ" às configurações do módulo, que permitem apontar a ordem de exibição dos campos personalizados;
• Melhorias nos textos, adição de links e nova ordem das opções do módulo, tornando-o ainda mais intuitivo;

0.1.4

• Adicionada a opção de redirecionar o link da fatura diretamente para o URL do boleto;
• Melhoria na opção de envio de email em caso de erro, agora é possível escolher o departamento de suporte que será notificado.

0.1.3

• Agora o cliente associado à transação pode ser uma Pessoa Jurídica. Nesse caso, além do CPF, devem ser informados a Razão Social e o CNPJ da empresa. Se os campos Empresa e CNPJ (segundo campo personalizado) estiverem preenchidos no perfil do cliente o boleto será gerado com as informações de pessoa jurídica, se algum desses dois capos estiver em branco, o boleto será gerado com as informações de pessoa física.

0.1.2

• Adicionada a opção de notificar o admin por email em caso de falha ao gerar o Boleto;
• Removido o comando gettransactions que consultava transações geradas pela fatura atual, a consulta por transações agora é realizada analisando o resultado do comando getinvoice.

0.1.1

• Redução de variáveis desnecessárias tornando a validação de dados mais rápida e eficaz;
• Debug mais completo: adicionadas novas informações de resultados às consultas às APIs;

0.1.0

• Lançamento

• A tarifa do Boleto paga separadamente à Gerencianet é de R$2,99 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."