Automatize a emissão de notas fiscais no WHMCS com a NFE.io!
A NFE.io é um sistema de emissão de notas fiscais que automatiza a comunicação com as prefeituras. Com a NFE.io você se livra de diversas tarefas chatas, melhorando o desempenho do seu negócio. E melhor, você economiza tempo e dinheiro.
Automatize a emissão de nota fiscal eletrônica de serviço diretamente em seu WHMCS através do Módulo Nota Fiscal para WHMCS via NFE.io. Com este módulo, é possível automatizar a rotina de geração e envio de NFSe para seus clientes quando eles realizam o pagamento de uma fatura referente a um pedido ou serviço recorrente, emitir notas a partir de faturas avulsas ou toda vez que um pagamento é recebido no WHMCS por exemplo.
Este módulo é para emissão de NFS-e, Nota Fiscal de Serviço Eletrônica, não sendo possível emissão de nota de produto.
- Emissão automática de notas fiscais
- Emissão manual de notas fiscais
- Agendamento de emissão de notas fiscais
- Cancelamento de nota fiscal quando fatura é cancelada
- Configuração de código de serviço personalizado por produto
- Painel intuitivo de visualização de notas emitidas
- Botões de ação rápida para emissão, cancelamento e envio
- Acompanhamento do status da emissão
- Envio de nota fiscal por e-mail
- Download de nota em PDF e XML
- Emite notas fiscais de forma sequencial, evitando sobrecargas nos sites das prefeituras.
- salva o debug das chamadas à API NFE.io no log de Módulo do WHMCS para diagnóstico
- seleciona nas configurações do módulo a opção de enviar o número inscrição municipal para a nota fiscal.
- seleciona nas configurações do módulo a opção de enviar a nota fiscal por e-mail automaticamente.
- valida CPF/CNPJ do cliente e não emite a nota fiscal caso inválido
Antes de realizar a instalação do módulo, leia com atenção as informações a seguir, elas são importantes para que todo o processo de instalação possa ocorrer sem problemas.
A documentação completa do módulo está disponível também em https://nfe.github.io/whmcs-addon/
O módulo de emissão de nota fiscal para WHMCS da NFE.io é compatível com versões do WHMCS 8 ou superiores. A tabela com o "suporte de longo termo" do WHMCS pode ser acessada em https://docs.whmcs.com/Long_Term_Support#WHMCS_Version_.26_LTS_Schedule
O módulo suporta PHP com versões superior a 7.2. Para visualizar a matrix de compatibilidade de PHP do WHMCS acesse https://docs.whmcs.com/PHP_Version_Support_Matrix
O módulo irá requerer os seguintes campos personalizados para o cliente:
| Campo | Criação | Preenchimento |
|---|---|---|
| CPF/CNPJ | Obrigatória | Obrigatório |
| Inscrição Municipal | Obrigatória | Opcional |
Na administração do WHMCS, crie um campo personalizado de cliente para registrar o CPF/CNPJ necessário para a emissão da NFSe e outro para a Inscrição Municipal.
Caso já exista um campo personalizado de cliente configurado e utilizado para registrar o número do documento (CPF/CNPJ), não será necessário criar outro.
O campo Inscrição Estadual é de criação obrigatória, mas de preenchimento opcional pelo cliente, necessário para emissão de notas para pessoa jurídica.
Atenção: O módulo identificará automaticamente se o número de documento informado no campo personalizado se trata de CPF ou CNPJ e emitirá a nota em conformidade com o tipo de pessoa (física ou jurídica).
Dica: é possível utilizar campos personalizados diferentes para preenchimento de CPF e CNPJ.
Os requisitos a seguir são necessários para o funcionamento adequado do módulo e integração.
- WHMCS versão 8 ou superior;
- PHP 7.2 ou superior;
- Chave de API da NFE.io;
- Automação do WHMCS devidamente configurada (https://docs.whmcs.com/Automation_Settings);
- Tarefas cron do Sistema sendo executadas conforme recomendações do WHMCS https://docs.whmcs.com/Crons#System_Cron.
Para instalar o módulo no WHMCS realize os seguintes passos.
Faça o download arquivo zip da última versão módulo neste link https://github.com/nfe/whmcs-addon/releases/latest
Veja a lista completa de versões em https://github.com/nfe/whmcs-addon/releases
Descompacte o zip baixado, o conteúdo do diretório extraído deve ser semelhante a este:
- modules
- addons
- NFEioServiceInvoices
- addons
Carregue o diretório modules existente no arquivo descompactado para o diretório de instalação do seu WHMCS.
Por exemplo, tendo o WHMCS instalado em public_html, carregue o diretório modules em public_html.
Dica: O arquivo descompactado já está na estrutura associada aos módulos addon do WHMCS
modules/addons. Ao carregar o diretóriomodulesvocê automaticamente carregará o diretório do módulomodules/addons/NFEioServiceInvoices.
Após realizar o carregamento dos arquivos do módulo, ele está disponível para ativação e configuração no WHMCS.
Veja a seguir os passos para ativação do módulo no WHMCS 8 e WHMCS 7.
Para ativar o módulo adicional no WHMCS versão 8.x vá até o ícone de chave no canto superior direito e clique em Opções.
O campo de busca em Opções digite addon e acesse a opção Módulos Addon.
Localize o módulo addon NFE.io NFSe e clique no botão Ativar.
Para ativar o módulo adicional no WHMCS versão 7.x acesse o menu Opções -> Módulos Addons.
Localize o módulo addon NFE.io NFSe e clique no botão Ativar.
Após ativar o Módulo Nota Fiscal para WHMCS via NFE.io as seguintes opções devem ser configuradas.
campo obrigatório
Chave de acesso privada gerado na sua conta NFE.io, necessária para a autenticação das chamadas à API.
Obtenha uma chave de acesso a API neste link https://app.nfe.io/account/apikeys
campo obrigatório
Informe o ID da empresa ao qual serão associadas as notas fiscais gerados pelo WHMCS.
Obtenha o ID da empresa neste link https://app.nfe.io/companies/
campo obrigatório
Código de serviço que será usado como padrão para geração das notas fiscais pelo WHMCS. Este código irá variar de acordo com a categoria de tributação do negócio no município.
Saiba mais sobre o código de serviço neste link https://nfe.io/docs/nota-fiscal-servico/conceitos-nfs-e/#o-que-e-codigo-de-servico
Emite as notas em modo "depuragem" sem valor real no lado da NFE.io, ative apenas em caso de necessidade ou homologação.
Marque essa opção para salvar informações de diagnóstico no Log de Módulo do WHMCS, ative apenas em caso de necessidade.
Escolha os grupos de administradores ou operadores que terão para acessar o módulo.
dica: informe todos os grupos de operadores que precisem acessar e operar o módulo.
Após a instalação e configuração inicial do addon como chave de API e código da empresa, é necessário realizar as configurações avançadas e rotinas de emissão das notas fiscais. Para isso acesse Addons -> NFE.io NFSe -> Configurações.
As configurações disponíveis estão descritas a seguir.
Chave de acesso privada gerado na sua conta NFE.io, necessária para a autenticação das chamadas à API.
Configurado na etapa de instalação do módulo.
ID da empresa ao qual serão associadas as notas fiscais gerados pelo WHMCS.
Configurado na etapa de instalação do módulo.
Código de serviço que será usado como padrão para geração das notas fiscais pelo WHMCS.
Configurado na etapa de instalação do módulo.
Campo legado RPS.
Habilita a opção de envio da nota fiscal por e-mail ao cliente.
O e-mail será enviado para o endereço principal cadastrado no perfil do cliente diretamente pela NFE.io.
Configuração global para emissão das nots ficais pelo WHMCS, as opções disponíveis são.
A NFSe será emitida assim que uma fatura seja publicada, ou seja, esteja disponível para o cliente.
A NFSe será emitida apenas quando a fatura registrar um pagamento. Esse pagamento poderá ser registrado por qualquer portal de pagamento dentro do fluxo transacional padrão do WHMCS ou manualmente ao adicionar um pagamento em uma fatura.
Número de dias após o pagamento da fatura que as notas devem ser emitidas. Informe quantos dias após o registro do pagamento em uma fatura a NFSe será emitida.
Atenção: agendar emissão de notas desativa a configuração Quando emitir NFE.
Marque esta opção para cancelar automaticamente uma nota quando a fatura associada é cancelada.
Selecione o campo personalizado criado anteriormente que será responsável por registrar o número de inscrição municipal do cliente.
Selecione o campo personalizado criado anteriormente que será responsável pelo CPF do cliente. Este campo poderá ser o mesmo para CPF e CNPJ.
Selecione o campo personalizado criado anteriormente que será responsável pelo CNPJ do cliente. Selecione o mesmo campo personalizado do CPF caso seja um campo único para ambos os números de documento (CPF/CNPJ).
Esta opção define que todos os serviços terão impostos aplicados, caso contrário a aplicação de imposto é selecionada de forma individual por serviço.
Selecione a informação que será exibida no campo de descrição da nota fiscal.
Exibe apenas o número da fatura vinculada a NFSe.
Exibe o nome de todos os serviços vinculados a fatura.
Exibe o número da fatura em uma linha e o nome de todos os serviços vinculados a fatura em outra linha.
Exibe o link da fatura juntamente com a descrição da NFSe na mensagem da nota.
Campo livre para informação adicional que será exibida no campo mensagem da nota fiscal.
Os produtos podem ter configurações de código de serviço individuais. É possível definir os códigos de serviços personalizado por produto em Addons -> NFE.io NFSe -> Código de Serviço
Para definir um código de serviço personalizado, localize o produto/serviço desejado e no campo Código do Serviço informe o código de serviço desejado, em seguida clique no botão Salvar Código.
Dica: para alterar um código basta alterar o desejado e clicar no botão
Salvar Códigoreferente.
Para excluir um código personalizado de um produto, e voltar a utilizar a configuração global, localize o produto desejado e clique no botão Excluir Código.
Dica: use o campo
Pesquisarlocalizado no canto superior da tabela para pesquisar os produtos desejados pelo nome ou ID.
É possível definir uma opção de emissão personalizada por cliente, esta opção de emissão sobrescreve a configuração global de emissão configurada.
Para inserir uma opção personalizada de emissão, acesse o perfil do cliente desejado e localize o campo Emitir nota fiscal quando e selecione uma das opções de emissão da lista, como exemplificado na imagem a seguir.
Para inserir um link da nota fiscal do PDF e XML, edite o arquivo viewinvoice.tpl da pasta do template do WHMCS, utilize o exemplo abaixo:
{if $status eq "Paid" || $clientsdetails.userid eq "6429"}<i class="fal fa-file-invoice" aria-hidden="true"></i> NOTA FISCAL <a href="/modules/addons/gofasnfeio/pdf.php?invoice_id={$invoiceid}" target="_blank" class="btn btn-link" tite="Nota Fiscal disponível 24 horas após confirmação de pagamento.">PDF</a> | <a href="/modules/addons/gofasnfeio/xml.php?invoice_id={$invoiceid}" target="_blank" class="btn btn-link" tite="Nota Fiscal disponível 24 horas após confirmação de pagamento.">XML</a>{/if}Este documento irá mostrar como atualizar e migrar com sucesso o Módulo Nota Fiscal para WHMCS via NFE.io para a versão 2.0. Ela irá guiar passo a passo por todo o processo de atualização e migração necessários.
Este documento visa auxiliar no processo de atualização do módulo da versão v1.4 para a versão v2.0
ATENÇÃO: Sempre realize um backup por segurança, tanto do seu WHMCS quanto do seu banco e dados antes de realizar qualquer migração.
A versão 2.0 do módulo possui uma nova estrutura de diretórios, o que possibilita uma ativação em paralelo a versão anterior permitindo assim uma migração rápida e transparente. Ao ativar a nova versão em paralelo, o módulo irá buscar todas as informações da versão anterior e irá importa-las automaticamente.
Então é crucial para que o processo de atualização e migração ocorra adequadamente a ativação em paralelo das duas versões do módulo.
Não desative o módulo antigo antes de concluir a migração/atualização.
Ao ativar a nova versão, todas as configurações globais do módulo serão automaticamente migradas. Configurações como API Key e ID da empresa já poderão ser visíveis como exemplificado na imagem a seguir.
As configurações migradas automaticamente da versão anterior serão:
- API Key
- ID da Empresa
- Código de Serviço Principal
- Informações de depuragem (debug)
- RPS (legado)
- Disparar e-mail com a nota
- Quando emitir NFE
- Quando emitir NFE
- Cancelar NFE Quando Cancelar Fatura
- Informações do campo personalizado para Campo Inscrição Municipal
- Informações do campo personalizado para Campo Personalizado CPF
- Informações do campo personalizado para Campo Personalizado CNPJ
- Aplicar Impostos em todos os produtos
- Descrição da NFSe
- Exibir Link da Fatura na NFSe
- Descrição Adicional
As demais configurações migradas poderão ser verificadas acessando o módulo em Addons -> NFE.io NFSe -> Configurações.
Ao ativar o novo módulo, as informações das notas fiscais emitidas a partir da versão anterior serão migradas automaticamente.
Todas as notas existentes estarão visíveis ao acessar o módulo em Addons -> NFE.io NFSe.
Os códigos de serviços personalizados serão migrados automaticamente e poderão ser verificados acessando o módulo em Addons -> NFE.io NFSe -> Códigos de Serviços.
As configurações personalizadas de emissão de notas para os clientes também será migrada e todas as rotinas existentes de emissão para seus clientes serão mantidas.
Por precaução, antes de desativar a versão antiga do módulo, faça uma verificação completa. Verifique se as configurações migradas estão corretas, verifique se as notas fiscais estão sendo listadas adequadamente e se os códigos dos serviços configurados condizem com os existentes na configuração do módulo antigo.
Fazendo esta verificação antes de seguir com a desativação e exclusão do módulo antigo ajudará a evitar problemas que não poderão ser revertidos após as próximas etapas.
Após conferir a configurações do módulo e as notas ficais, tudo parecendo certo, você poderá desativar o módulo.
Para desativar o módulo NFE.io v1.4.x vá para Configurações -> Módulos Addons no WHMCS v7.x ou Opções -> Módulos Addons no WHMCS v8.x.
Localize o módulo antigo, verifique a versão que deve ser desativada, você deverá desativar a versão v1.4.x (sendo x qualquer versão menor como 1.4.1, 1.4.4 etc). Veja a imagem a seguir.
Após desativar o módulo NFE.io v1.4.x, será necessário remover o diretório gofasnfeio existente dentro de modules/addons como última etapa da atualização para a versão 2.0.
Para isso, utilize seu cliente FTP preferido para acessar o WHMCS, navegue até o diretório seu_whmcs/modules/addons para visualizar os módulos adicionais existentes em seu WHMCS e localize o diretório nomeado gofasnfeio como demonstrado na imagem a seguir.
Após localizar o diretório, exclua-o.
Pronto! Seu módulo de emissão de notas fiscais no WHMCS via NFE.io está atualizado para a versão 2.0!
Este processo de atualização, por segurança, não exclui ou manipula as tabelas no banco de dados utilizado pela versão anterior. A versão 2.0 copia todas as informações para novas tabelas e mantém as originais intactas, e a desativação do módulo não aciona nenhuma ação de exclusão. Então caso você tenha tido algum problema e precise voltar o módulo para uma versão anterior a atualização, basta desativar a versão 2.0 e reenviar os arquivos da versão originalmente em uso.
Veja a lista a seguir das tabelas do banco de dados usadas pela versão anterior, caso você desejar fazer um backup manual ou exclui-las no futuro.
gofasnfeio: todos os registros de notas fiscais já emitidas pelo módulo.mod_nfeio_custom_configs: contém todos os registros das configurações personalizadas de emissão de notas para os clientes.tblproductcode: possui todos os registros de códigos de serviços personalizados associados aos produtos/serviços.
tblproductcodepossui um nome muito similar as tabelas padrões do WHMCS, mas ela é uma tabela personalizada e nenhum componente ou função nativas do WHMCS dependem dela.