Módulo Efí Boleto para WHMCS

Gerencianet agora é Efí. O nome mudou mas este continua sendo, desde 2016, um dos módulos mais completos do mercado para emissão de boleto bancário registrado via WHMCS, integrando geração, consulta e baixa automática de boletos pela API Efí (antiga Gerencianet). Desenvolvido pela Gofas Software, é 100% gratuito.

Configuração simples, objetiva e focada em atender todos os modelos de negócio. Nos bastidores o módulo automatiza os principais processos, cuidando dos detalhes da automatização de recebimentos.

• Download
• Funcionalidades
• Requisitos
• Instalação
• Configuração
• Juros e multa
• Informações importantes
• Suporte
• Licença

Baixar a versão mais recente

O download é gratuito e exige cadastro no gofas.net. Quem ainda não tem conta é levado ao cadastro e, depois de confirmar o e-mail, faz login e baixa o módulo.

• Boletos registrados sem taxas de registro/baixa
• Juros e multa após o vencimento, registrados na própria cobrança e calculados pela Efí no momento do pagamento. O boleto vencido mantém o mesmo código, o mesmo vencimento e o mesmo valor
• Respeita a configuração da sua conta Efí: se a conta já cobra juros e multa, o módulo não sobrescreve e avisa isso na tela de configuração
• 2ª via automática ao acessar a fatura, sem duplicar boletos pagáveis
• Confirmação automática de pagamento e baixa nas faturas via notificações (callback) ou tarefa cron
• Boleto com sua marca: logotipo, mensagem e instruções da sua empresa
• Informações do boleto na fatura: desconto, taxas, cálculos e outras informações
• Linha digitável na fatura, com opção de copiar em um clique
• Informações do boleto nos emails: opcionalmente o módulo gera o boleto quando a fatura é criada e fornece mergetags para os templates de email do WHMCS (linha digitável, link HTML e PDF, vencimento, ID do boleto e mais). O cliente paga sem precisar acessar o WHMCS
• Link direto para o boleto usando a tag padrão {$invoice_link} dos templates de email, sem redirecionamentos, autenticação ou edição de templates
• Redirecionamento para o boleto ao acessar a fatura (opcional), ideal em conjunto com o Módulo Auto Login para WHMCS. Também via parâmetro redirectToBillet=true (ou false para desativar) no URL da fatura
• Anexo do boleto em PDF ao email de fatura (opcional)
• Dispensa configuração de campos CPF/CNPJ: o módulo detecta automaticamente os campos personalizados de clientes
• Notifica administradores por email sobre erros ao gerar boletos, agilizando o diagnóstico antes do cliente acionar o suporte
• Imagem personalizada para o botão de pagamento
• Desconto por método de pagamento, fixo (R$) ou em porcentagem (%), para todos os boletos deste método
• Desconto antes do vencimento: define até quantos dias antes do vencimento o desconto se aplica
• Descontos personalizados por cliente, fixo (R$) ou em porcentagem (%), via campos personalizados
• Tarifa adicional configurável, fixa (R$) ou em porcentagem (%)
• Cancelamento automático do boleto: ao cancelar a fatura, ao gerar 2ª via de boleto vencido, ou manualmente pelo addon incluso no download
• Aviso de atualização e verificação de versão na própria tela de configuração do módulo
• Configuração simples e intuitiva: seleção de campos, departamentos de suporte e afins via menus suspensos (dropdown)
• Suporte a produção e a testes (sandbox) e a múltiplas contas
• Logs de diagnóstico configuráveis
• Configurações personalizadas sem editar o código original (atualizável sem perder customizações)
• E muito mais.

• WHMCS >= 8.6
• PHP 8.2 ou superior
• ionCube Loader 15 ou superior
• Conta Efí (Efí Pay) com API habilitada
• Credenciais: Client ID e Client Secret (produção e desenvolvimento)

O certificado .p12 não é necessário para o boleto. Ele é exigido apenas pelo módulo Efí Pix.

1. Baixe o arquivo em https://gofas.net/gefibd/ e descompacte. Será criada a pasta gofasgerencianetboleto.
2. Copie as pastas includes e modules de dentro de gofasgerencianetboleto para a raiz da instalação do WHMCS, mesclando com as pastas existentes.
3. Ative o módulo em Opções > Pagamentos > Portais para Pagamentos > Aba All Payment Gateways.
4. Informe o Client ID e o Client Secret.

1. Depois de ativar o módulo no WHMCS, faça login na sua conta Efí, acesse API > Minhas Aplicações > Nome da Aplicação para criar sua aplicação e gerar as credenciais Client ID e Client Secret.

2. No painel WHMCS, navegue até Opções > Pagamentos > Portais para Pagamentos > All Payment Gateways e clique em "Gofas Efí Boleto" para ativar o módulo.
3. Crie um campo personalizado de cliente para CPF e/ou CNPJ (um campo unificado ou dois campos distintos). O módulo identifica os campos do perfil do cliente automaticamente.

• Client ID Produção: (obrigatório) Client ID da aba Produção da sua aplicação.
• Client Secret Produção: (obrigatório) Client Secret da aba Produção da sua aplicação.
• Client ID Desenvolvimento: (obrigatório) Client ID da aba Desenvolvimento da sua aplicação.
• Client Secret Desenvolvimento: (obrigatório) Client Secret da aba Desenvolvimento da sua aplicação.
• Modo de Testes / Sandbox: alterna entre os ambientes de Desenvolvimento e Produção.
• Modo Diagnóstico / Debug: exibe resultados e erros retornados pela API Efí e pela API interna do WHMCS. Use apenas em testes ou para diagnóstico.
• Baixa via cron: verifica o status dos boletos a cada execução do cron do WHMCS e dá baixa nas faturas pagas. Ativar essa opção desativa a baixa via notificação (callback).
• Salvar Logs: grava informações de diagnóstico em Utilitários > Logs > Log de Módulo. É necessário ativar o "Log de Debug" nesse menu.
• Administrador do WHMCS: (obrigatório) usuário ou ID do administrador com permissão de uso da API interna do WHMCS.
• Valor da tarifa por Boleto: (opcional) valor pago à Efí por boleto confirmado. Não é somado ao total; preenche o campo "Taxas" (fee) da transação. Use ponto para decimais.
• Valor mínimo do Boleto: (opcional) valor mínimo da fatura para permitir pagamento via boleto. Padrão R$5,00.
• Informações do Boleto no email: adiciona link, linha digitável, vencimento e outras informações ao corpo dos emails de fatura. Faz o boleto ser gerado no momento em que a fatura é criada.
• Substituir link da fatura por link do boleto: substitui a tag {$invoice_link} do template "Invoice Created" pelo link do boleto.
• Cancelar Boleto ao cancelar Fatura: (opcional) cancela o boleto associado quando a fatura é cancelada no WHMCS.
• Cancelar Boleto Vencido: (opcional) cancela o boleto anterior antes de gerar segunda via. Sem essa opção, o módulo altera a data de vencimento do boleto vencido ou gera um novo sem alterar o status do anterior.
• Dias adicionais para nova data de vencimento: dias somados ao vencimento ao gerar segunda via ou atualizar boleto vencido. Aplica-se apenas a faturas vencidas.
• Notificar admins sobre erros: departamento que recebe email quando ocorre erro ao gerar o boleto, permitindo ação antes do contato do cliente.
• Tipo de Desconto Personalizado: campo personalizado de clientes que define o tipo de desconto (R$ ou %).
• Valor do Desconto Personalizado: campo personalizado usado para descontos por cliente. Decimal com ponto, maior ou igual a 0.00 e menor que o valor da cobrança.
• Desconto ou Taxa adicional: oferece desconto ou acrescenta taxa para pagamentos via boleto.
• Tipo de desconto/taxa: porcentagem ou reais.
• Valor do Desconto ou Taxa: valor abatido ou acrescentado ao total.
• Validade do desconto: máximo de dias antes do vencimento para aplicar desconto. Em branco aplica mesmo após o vencimento; 0 aplica a boletos gerados até o vencimento; de 1 a X aplica entre 1 e X dias antes do vencimento.
• Multa após o vencimento: máximo 10%. Use ponto para decimais. A multa é registrada na cobrança e calculada pela Efí no pagamento, então o valor do boleto não muda depois do vencimento.
• Juros após o vencimento: juros por dia (mínimo 0.001, máximo 0.33). Use ponto para decimais. Também são registrados na cobrança e calculados pela Efí no pagamento.
• Dias para baixa do Boleto vencido: (opcional) de 0 a 120 dias, período em que o boleto vencido continua podendo ser pago. Em branco usa o padrão da Efí, que é 90 dias. Aplica-se apenas quando multa ou juros estão definidos no módulo.
• Exibir linha digitável: exibe a linha digitável abaixo do botão "visualizar boleto".
• Exibir data de Vencimento: exibe o vencimento na fatura.
• Exibir Desconto / Taxa na fatura: informa desconto ou taxa na fatura.
• Redirecionar para o Boleto: redireciona o cliente ao URL do boleto ao acessar a fatura. Adicione &redirectToBillet=false ao URL para desativar em acessos específicos.
• Imagem do botão "Visualizar Boleto": URL da imagem do botão (recomendado 160x43px).
• Mensagem ao cliente: mensagem no boleto (máximo 80 caracteres).
• 1ª a 4ª Instrução do boleto: linhas de instruções do boleto.
• Anexar PDF do Boleto no email: adiciona o boleto em PDF como anexo aos emails de fatura.
• Opções customizadas: opções personalizadas adicionadas com conhecimento básico de PHP, sem editar o código do módulo.

As tags disponíveis aparecem abaixo do editor dos templates de email do WHMCS:

• {$ggnb_billet_info}: bloco HTML com todas as informações do boleto (exemplo).
• {$ggnb_link}: link do boleto.
• {$ggnb_pdf}: link do boleto em PDF.
• {$ggnb_barcode}: linha digitável (representação numérica do código de barras).
• {$ggnb_expire_at}: data de vencimento.
• {$ggnb_total}: valor total.
• {$ggnb_charge_id}: ID da transação na API Efí.
• {$ggnb_api_mode}: sandbox ou live.
• {$ggnb_debug}: informações de depuração no corpo do email.

Juros e multa nunca são somados ao valor do boleto pelo módulo. Eles são registrados na cobrança e calculados pela Efí e pela rede bancária no momento do pagamento, que é o funcionamento correto do boleto registrado. Por isso o boleto de uma fatura vencida mantém o mesmo código, o mesmo vencimento e o mesmo valor principal, independentemente de quantos dias se passem ou de quantos avisos de atraso o WHMCS envie.

Existem dois lugares possíveis, mas apenas um deles vale por vez:

1. Na sua conta Efí, em Configurações de cobranças > Boletos bancários e carnês. Vale para todas as cobranças da conta, inclusive as emitidas fora do WHMCS.
2. No módulo, nos campos "Multa após o vencimento" e "Juros após o vencimento". Vale apenas para os boletos emitidos por este módulo.

A regra de prioridade é simples: se a sua conta Efí já cobra juros ou multa, a configuração da conta vence e os campos do módulo são ignorados. O módulo detecta isso automaticamente e mostra o aviso na tela de configuração, com os valores que a sua conta está aplicando. Para usar os valores do módulo, remova juros e multa na conta Efí.

Essa prioridade existe porque a API da Efí trata juros e multa como um bloco único: quando o módulo envia esses valores, ele substitui por completo o que estiver configurado na conta. Enviar apenas a multa removeria os juros da conta. Enviar ambos zerados removeria os dois. Deixar a conta no comando evita esse efeito.

• Multa: máximo 10%, e a Efí costuma recusar valores acima de 2% conforme a carteira de cobrança.
• Juros: mínimo 0,001% e máximo 0,33% ao dia. O limite legal usual é 0,033% ao dia (1% ao mês).
• Boleto vencido continua pagável por 90 dias após o vencimento, padrão da Efí. Use o campo "Dias para baixa do Boleto vencido" para definir de 0 a 120 dias.

Após o vencimento, acesse a fatura e confira: o valor do boleto continua sendo o valor da fatura, sem juros somados. A fatura informa os percentuais que o banco vai cobrar no pagamento. O código do boleto não muda. Quem calcula os encargos é o banco, no caixa ou no aplicativo, no momento em que o cliente paga.

• A tarifa do boleto é paga separadamente à Efí (R$2,37 para usuários do módulo, sujeito a alteração pela Efí).
• Sempre faça backup antes de mudar algo no seu sistema.
• Ao editar templates de email, use o editor HTML do WHMCS para evitar erros de formatação ao copiar e colar.

• Configurações personalizadas e alterações de funcionamento podem ser feitas sem editar o código original, mantendo o módulo atualizável.

Além dos códigos de erro da API Efí, o módulo fornece mensagens específicas e legíveis para facilitar o diagnóstico. Erros que dependem do cliente (como CPF ou dados cadastrais inválidos) exibem mensagem com instruções e link direto para o cliente corrigir o cadastro, sem acionar o suporte.

• Tela branca ou erro 500: verifique logs do servidor e do WHMCS.
• "Erro de comunicação na 1ª conexão com a API": verifique Client ID e Client Secret (produção e desenvolvimento são diferentes).
• "Falha ao gerar a transação na 2ª conexão com a API": verifique os campos "Descrição" e "Valor total" da fatura.
• "Erro de comunicação na 2ª/3ª conexão com a API": ative o Debug do módulo para diagnóstico detalhado.
• "CPF/Telefone/Nome incorretos": dados cadastrais do cliente precisam ser corrigidos.
• "Não é possível antecipar o vencimento": a Efí só permite adiar o vencimento de um boleto, nunca antecipar.
• Juros ou multa acima do permitido pela carteira de cobrança: ajuste os percentuais na sua conta Efí, em Configurações de cobranças.

Abra um tópico no fórum do módulo. Para enviar código ou logs, use um link do Gist (gist.github.com) ou do Pastebin (pastebin.com).

Contrato de licença de uso

Documentação temporariamente indisponível. Recarregue a página em alguns minutos.