Módulo Gerencianet Boleto para WHMCS

• PHP >= 5.4.0
• WHMCS >= 6.0.4

Instalação via "FTP"

1. Baixe, descompacte o arquivo gofasgerencianetboleto.zip e copie o arquivo /modules/gateways/gofasgerencianetboleto.php e o diretório /modules/gateways/gofasgerencianetboleto/ para dentro do diretório de gateways do WHMCS: /whmcs/modules/gateways/;
2. (opcional) Mova a pasta /modules/addons/gofasgerencianet/ para a para dentro do diretório de addons do WHMCS: /whmcs/modules/addons/.

Configurações do gateway

• Faça login na sua conta Gerencianet e acesse API > Minhas Aplicações > Nome da Aplicação para criar sua Aplicação e gerar as credenciais Client ID e Client Secret;
• No painel de controle WHMCS, navegue até Opções > Pagamentos > Portais para Pagamento > All Payment Gateways e ative o módulo Gofas Gerencianet Boleto e configure as opções descritas a seguir;
• Client_Id Produção: (Obrigatório) Cole a Client_Id encontrada na aba Produção da sua aplicação;
• Client Secret Produção: (Obrigatório) Cole a Client Secret encontrada na aba Produção da sua aplicação;
• Client_Id Desenvolvimento: (Obrigatório) Cole a Client_Id encontrada na aba Desenvolvimento da sua aplicação;
• Client Secret Desenvolvimento:(Obrigatório) Cole a Client Secret encontrada na aba Desenvolvimento da sua aplicação;
• Sandbox: Marque essa opção para alternar entre o modo Desenvolvimento e Produção;
• 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;
• Exibir data de Vencimento: Exibe na fatura a data de vencimento do Boleto;
• Exibir linha digitável e vencimento do Boleto: Exibe a linha digitável do boleto (código de barras), útil para pagamentos via internet banking;
• Redirecionar para o Boleto: Marque essa opção para redirecionar o cliente diretamente para o URL do boleto ao acessar a fatura;
• Exigir CPF e CNPJ de Pessoa Jurídica: Quando consta empresa e CNPJ no cadastro do cliente, o sistema obriga o envio também do nome e CPF da pessoa que está concretizando o pagamento em nome da empresa;
• Enviar email em caso de erro: Adicione o ID do departamento de suporte que será notificado em caso de erro nas transações. Deixe em branco para desativar;
• Administrador atribuído: Insira o ID ou nome de usuário do administrador do WHMCS que será atribuído às transações(opcional, o usuário id 1 será atribuído se essa opção não for preenchida);
• Ordem do campo CPF: Insira a ordem de exibição do campo personalizado criado para coletar o CPF do cliente;
• Ordem do campo CNPJ: Insira a ordem de exibição do campo personalizado criado para coletar o CNPJ do cliente;
• Valor mínimo: Valor totla mínimo da fatura para permitir pagamento via Boleto;
• Dias adicionais à data de vencimento do Boleto: Número de dias adicionais para o vencimento do Boleto, quando gerado após a data de vencimento da Fatura;
• Desconto ou Taxa adicional: Escolha de deseja oferecer desconto ou acrescentar taxa para pagamentos via Boleto;
• Tipo de desconto/taxa: Escolha se o desconto ou taxa será em % (Porcentagem) ou em R$ (Reais);
• Valor do Desconto ou Taxa: Valor que será abatido ou acrescentado ao valor total das faturas;
• Exibir Desconto / Taxa na fatura: Assinale se desejar informar sobre o Desconto ou Taxa na fatura;
• Imagem do botão "Visualizar Boleto": Insira o URL da imagem que será usada no chekout e faturas como botão "Visualizar Boleto" (opcional);
• Instruções do boleto: Insira até 4 linhas de instruções diferentes que serão inseridas no Boleto;
• Salve e você já pode emitir Boletos!

Configurações do addon Gofas Gerencianet Dashboard (opcional)

A partir da versão 0.2.5 o módulo Gofas Gerencianet Dashboard foi mesclado com o módulo Gofas Gerencianet Boleto. A instalação dele é opcional, se você deseja ativa-lo, antes tenha certeza de ter executado o segundo passo da sessão "Instalação".

1. Ative em Opções > Módulos Addons;
2. Após a ativação do módulo clique em "Configure" e insira suas credenciais da API;
3. Selecione a Opção Sandbox se deseja usar a API de testes;
4. Selecione a Opção Debug se deseja ver todos os resultados crus na tela (use apenas para testes e depuração de erros).

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 debug que grava as respostas do servidor nos logs das transações na API Gerencianet;

0.1.9

• Corrige erro "Fatal error: Class 'Gerencianet\Gerencianet' 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

Além dos códigos de erro GN API, fornecemos mensagens de erro específicos do módulo para facilitar o diagnóstico e solução de falhas.

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 😛 A seguir você confere como aparecem os erros na tela para o cliente:

Erros comuns:

• "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."