Instalação

Este documento irá mostrar como instalar com sucesso o Módulo Nota Fiscal para WHMCS via NFE.io. Ele irá guiar passo a passo por todo o processo de instalação.

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.

Requisitos

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

1. Download da última versão do módulo Nota Fiscal para WHMCS da NFE.io em https://github.com/nfe/whmcs-addon/releases/latest;
2. WHMCS versão 8 ou superior;
3. PHP 7.4 ou superior, com as extensões curl e json habilitadas;
4. Chave de acesso (API Key) da NFE.io;
5. Automação do WHMCS devidamente configurada (https://docs.whmcs.com/Automation_Settings);
6. Tarefas cron do sistema sendo executadas conforme recomendações do WHMCS (https://docs.whmcs.com/Crons#System_Cron).

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 NFS-e 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 Municipal é de criação obrigatória, mas de preenchimento opcional pelo cliente, sendo necessário para a emissão de notas para pessoa jurídica em municípios que exigem essa informação.

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.

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

Descompactar o zip

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

• modules
  • addons
    • NFEioServiceInvoices

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.

Atualizando de uma versão anterior

Ao atualizar o módulo (e não instalar pela primeira vez), remova o diretório modules/addons/NFEioServiceInvoices existente antes de enviar os novos arquivos. Reestruturações entre versões removeram arquivos que, se mantidos, podem causar conflito. Veja o guia de Atualização.

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.

Para ativar o módulo adicional no WHMCS 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.

A ativação cria as tabelas utilizadas pelo módulo no banco de dados do WHMCS (notas fiscais, códigos de serviço, alíquotas, emissores e associações de clientes) e, quando existirem dados de versões anteriores, executa as migrações necessárias. As tabelas usam o prefixo mod_nfeio_si_.

Configuração do addon

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

Chave de Acesso (API Key)

campo obrigatório

Chave de acesso privada gerada 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

Ambiente de Desenvolvimento

Emite as notas em modo de homologação, sem valor fiscal no lado da NFE.io.

Desmarque esta opção em produção

Esta opção vem marcada por padrão na primeira ativação do módulo. Em uma instalação de produção, desmarque-a antes de começar a emitir notas.

Além de definir o ambiente da emissão, esta opção filtra os callbacks recebidos da NFE.io: com ela marcada, o módulo aceita apenas atualizações de notas de Development; desmarcada, apenas de Production. Se o ambiente do módulo e o da nota não coincidirem, o callback é rejeitado e o status da nota não é atualizado.

Modo Depuração (Debug)

Grava informações de diagnóstico das chamadas à API no Log de Módulo do WHMCS (Utilitários → Logs → Log de Módulo).

Também vem marcada por padrão. Mantenha ativa durante a implantação e o diagnóstico de problemas; desative depois para reduzir o volume de logs.

Controle de Acesso

Escolha os grupos de administradores ou operadores que terão acesso ao módulo.

Dica: informe todos os grupos de operadores que necessitem acessar e operar o módulo.

Próximos passos

Após realizar a instalação e a configuração inicial, siga para as configurações detalhadas do módulo em Configuração.