nfe / whmcs-addon

Módulo Nota Fiscal para WHMCS via NFE.io. Automatiza a emissão de notas fiscais.
11 stars 8 forks source link
nfe nota-fiscal whmcs

Módulo Nota Fiscal para WHMCS via NFE.io

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.

Principais Recursos

Demais Recursos

Antes de começar

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.

Documentação

A documentação completa do módulo está disponível também em https://nfe.github.io/whmcs-addon/

Compatibilidade

WHMCS

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

PHP

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

Campos Personalizados

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.

Requisitos

Os requisitos a seguir são necessários para o funcionamento adequado do módulo e integração.

  1. WHMCS versão 8 ou superior;
  2. PHP 7.2 ou superior;
  3. Chave de API da NFE.io;
  4. Automação do WHMCS devidamente configurada (https://docs.whmcs.com/Automation_Settings);
  5. Tarefas cron do Sistema sendo executadas conforme recomendações do WHMCS https://docs.whmcs.com/Crons#System_Cron.

Instalação

Para instalar o módulo no WHMCS realize os seguintes passos.

Baixar o módulo

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

Descompactar o zip

Descompacte o zip baixado, o conteúdo do diretório extraído deve ser semelhante a este:

Enviar arquivos para o WHMCS

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ório modules você automaticamente carregará o diretório do módulo modules/addons/NFEioServiceInvoices.

Ativar o módulo addon

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.

WHMCS 8.X

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.

WHMCS 7.X

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.

Configuração do addon

Após ativar o Módulo Nota Fiscal para WHMCS via NFE.io as seguintes opções devem ser configuradas.

API Key

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

ID da Empresa

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/

Código do Serviço Principal

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

Ambiente de desenvolvimento

Emite as notas em modo "depuragem" sem valor real no lado da NFE.io, ative apenas em caso de necessidade ou homologação.

Debug

Marque essa opção para salvar informações de diagnóstico no Log de Módulo do WHMCS, ative apenas em caso de necessidade.

Controle de Acesso

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.

Configuração

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.

API Key

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

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 Principal

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.

RPS

Campo legado RPS.

Disparar e-mail com a nota

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.

Quando emitir NFE

Configuração global para emissão das nots ficais pelo WHMCS, as opções disponíveis são.

Quando a fatura é gerada

A NFSe será emitida assim que uma fatura seja publicada, ou seja, esteja disponível para o cliente.

Quando a fatura é paga

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.

Agendar Emissão

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.

Cancelar NFE Quando Cancelar Fatura

Marque esta opção para cancelar automaticamente uma nota quando a fatura associada é cancelada.

Inscrição Municipal

Selecione o campo personalizado criado anteriormente que será responsável por registrar o número de inscrição municipal do cliente.

Campo Personalizado CPF

Selecione o campo personalizado criado anteriormente que será responsável pelo CPF do cliente. Este campo poderá ser o mesmo para CPF e CNPJ.

Campo Personalizado 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).

Aplicar Impostos em todos os produtos

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.

Descrição da NFSe

Selecione a informação que será exibida no campo de descrição da nota fiscal.

Número da fatura

Exibe apenas o número da fatura vinculada a NFSe.

Nome dos serviços

Exibe o nome de todos os serviços vinculados a fatura.

Número da fatura + Nome dos Serviços

Exibe o número da fatura em uma linha e o nome de todos os serviços vinculados a fatura em outra linha.

Exibir Link da Fatura na NFSe

Exibe o link da fatura juntamente com a descrição da NFSe na mensagem da nota.

Descrição Adicional

Campo livre para informação adicional que será exibida no campo mensagem da nota fiscal.

Configurações dos Produtos/Serviços

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ódigo referente.

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 Pesquisar localizado no canto superior da tabela para pesquisar os produtos desejados pelo nome ou ID.

Emissão Personalizada por cliente

É 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.

Link da nota na fatura

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="https://github.com/nfe/whmcs-addon/blob/main/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="https://github.com/nfe/whmcs-addon/blob/main/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}

Atualização

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.

Ativando as versões em paralelo

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.

Configuraçã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:

As demais configurações migradas poderão ser verificadas acessando o módulo em Addons -> NFE.io NFSe -> Configurações.

Migrando as notas fiscais

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.

Migrando os códigos de serviços

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.

Migrando as definições dos usuários

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.

Verificando tudo

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.

Desativando a versão anterior (1.4)

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.

Excluindo o módulo anterior (v1.4)

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!

Tabelas do Banco de Dados

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.

tblproductcode possui 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.