Módulo Nota Fácil para WHMCS
Automatização e simplificação na emissão de notas fiscais da sua empresa
&
✓ Compatível com PHP 7.4 e PHP 8.1;
Principais funcionalidades
✓ Emissão automática de notas fiscais. Cria notas fiscais (NFS-e) automaticamente quando uma fatura é gerada ou paga no WHMCS;
✓ Emissão manual de notas fiscais. Adiciona botões de ação na página de edição das faturas que permitem emitir, editar e visualizar as NFS-es de cada fatura do WHMCS;
✓ Painel administrativo de notas fiscais. Fornece uma interface visual intuitiva e fácil de usar no painel administrativo do WHMCS, com a lista de todas as notas fiscais criadas via integração, onde é possível verificar a situação de cada NFS-e e diversas informações relacionadas às notas, faturas e clientes, além de poder executar ações como, sincronizar, emitir, reenviar à prefeitura, editar, visualizar etc;
✓ Notas fiscais na área do cliente. Adiciona uma sessão exclusiva ao front end do WHMCS + um item no menu, onde seus clientes podem acessar todas as notas fiscais geradas para sua conta, além de verificar diversas informações, em uma interface semelhante a página de faturas da área do cliente, sem interferir no design do template do seu WHMCS;
✓ Diversos CNAEs. Permite definir o código CNAE "geral" + um código CNAE específico para cada serviço do WHMCS;
✓ Diversos códigos de serviço. Permite definir o código de serviço "geral" + um código de serviço específico para cada serviço do WHMCS;
✓ NFS-e apenas para clientes específicos. Ao selecionar essa opção nas configurações o módulo emite notas fiscais apenas para clientes que possuam o campo personalizado "Emitir NFE" ativado no perfil;
✓ Suporte a todos os campos. O módulo detecta automaticamente CPF, CNPJ, Inscrição Estadual, Complemento e Número nos custom fields de cliente do WHMCS. Você não precisa configurar nada mais e o melhor: apenas o campo CPF ou CNPJ são obrigatórios, caso os endereços no seu WHMCS sigam o padrão "Nome da rua, nº", o módulo também vai detectar automaticamente;
✓ Reenvio de NFS-e por e-mail. Fornece um botão de ação na página de edição da fatura para realizar o reenvio da nota fiscal ao cliente por e-mail .
✓ Reenvio automático à prefeitura. Escolha quantas vezes o módulo deve tentar novamente realizar a emissão junto à prefeitura de uma nota já cadastrada no Nota Fácil. Contorna erros comuns de comunicação entre a API Nota Fácil e o webservice do município.
Documentação
Configurações do Nota Fácil
Para que o módulo funcione sua conta Nota Fácil deve estar apta a emitir notas fiscais, para isso há algumas configurações essenciais que devem ser verificadas antes de configurar o módulo:
Repita os passos a seguir no ambiente produção e de testes:
- Configurar um certificado digital;
- Completar as informações da empresa (webhook não é necessário);
- Crie um usuário com a regra Softhouse Usuario e salve o nome de usuário e senha para a seguir adicionar à configuração do módulo.
Repita os passos acima nos dois ambientes, produção e testes:
Ambiente de Produção: https://app.notafacil.io/
Ambiente de Testes: https://staging.app.notafacil.io/
Instalação do módulo no WHMCS
- Copie a pasta
/modules/addons/gofasnotafacil/para dentro do diretório padrão de módulos addons do WHMCS:/whmcs/modules/addons/. - Ative o Addon em
Opções > Módulos Addons;
Configuração do módulo no WHMCS
- Chave de licença: Obtida ao adquirir o módulo;
Ambiente de Produção (app.notafacil.io)
- Login: O nome de usuário do Softhouse Usuario criado nos passos anteriores (Configuração Nota Fácil) ;
- Senha: A senha definida para o usuário Softhouse Usuario;
- Secret Key: Secret key gerada ao criar a conta Nota Fácil;
Ambiente de Testes (staging.app.notafacil.io)
- Login: O nome de usuário do Softhouse Usuario criado nos passos anteriores (Configuração Nota Fácil) ;
- Senha: A senha definida para o usuário Softhouse Usuario;
- Secret Key: Secret key gerada ao criar a conta Nota Fácil;
- Sandbox: Ative essa opção para gerar cobranças em modo de testes;
- Debug: Marque essa opção para salvar informações de diagnóstico no Log de Módulo;
- Emitir NFS-e: Escolha emitir as notas fiscais automaticamente quando a fatura é gerada ou quando a fatura é paga;
- Emitir NFE para: Todos os clientes ou Clientes selecionados via campo personalizado do perfil (custom field). Para a opção Emitir NFE para: clientes selecionados funcionar é obrigatório existir um campo personalizado do tipo checkbox (Caixa de Opções) com o nome "Emitir NFE" ativado nas contas que terão NFEs emitidas automaticamente;
- Tipo de local de prestação do serviço: Informar qual o tipo do local de prestação do serviço. Ao escolher Endereço Emitente o campo local onde o serviço foi prestado é preenchido com o endereço da empresa cadastrado no painel Nota Fácil. Caso a opção selecionada seja Endereço Destinatário o campo local onde o serviço foi prestado é preenchido com o endereço do cliente cadastrado no WHMCS;
- RPS: Numeração do RPS da última nota emitida junto à prefeitura para manter a mesma sequência de emissão. Não altere depois que as emissões via WHMCS iniciarem;
- Série do RPS: Consulte a prefeitura, seu contador ou o suporte Nota Fácil caso não saiba a série do RPS;
- Máximo de tentativas de emissão: Número máximo de vezes que o módulo deve tentar emitir uma nota fiscal previamente cadastrada no Nota Fácil e associada à uma fatura do WHMCS. Após serem cadastradas o módulo processa a emissão das notas junto à API a cada 5 minutos via cron do WHMCS. Mensagens de erro retornadas pelo Nota Fácil ou pela Prefeitura são gravadas no Log de Atividade do Sistema. Todos os dados enviados e retornados são gravados no Log de Módulo do WHMCS;
- Código do Município: Código de tributação de serviço do município;
- CNAE: Código da atividade principal;
- Código de Serviço: Código de serviço da atividade principal;
Vincular CNAE e Código de Serviço a cada respectivo serviço do WHMCS
Após as últimas configurações acima onde você define o Código de Serviço e CNAE padrão que serão definidos em todas as notas fiscais emitidas através das faturas do WHMCS, o módulo irá exibir uma lista com todos os produtos/serviços do WHMCS com campos Código de Serviço e CNAE individuais para cada item da lista, permitindo definir configurações diferentes para cada serviço cadastrado no seu sistema.
Deixe em branco os serviços do WHMCS que utilizam o mesmo código (definido nas duas opções anteriores);
- Controle de Acesso: Escolha os grupos de administradores ou operadores que terão permissão para acessar esse módulo;
Gerenciamento de notas fiscais no WHMCS
Após a ativação do módulo acesse no painel administrativo do WHMCS o menu Opções > Módulos Addons > Gofas Nota Fácil;
Nessa página são exibidas todas as NFS-es emitidas via integração, com informações sobre as respectivas faturas e clientes aos quais as notas fiscais pertencem.
As ações disponíveis podem variar de acordo com o status das notas fiscais, na captura de tela a seguir é possível entender cada opção de gerenciamento.
Informações importantes
- Versão mínima do WHMCS:
8.6; - Versão mínima do PHP:
7.1; Lista de Prefeituras que possuem integração com o Bling para emissão de NFS-e:
https://ajuda.bling.com.br/hc/pt-br/articles/360039971653-Lista-de-Prefeituras-que-possuem-integra%C3%A7%C3%A3o-com-o-Bling-para-emiss%C3%A3o-de-NFS-e
- Campo personalizado CPF/CNPJ: É necessário criar um campo personalizado de cliente nas configurações do WHMCS para CPF ou CNPJ. Você pode criar apenas um campo onde o cliente pode preencher com CPF ou CNPJ, ou então criar dois campos distintos, um para cada documento. O módulo identifica automaticamente os campos personalizados pelos seus respectivos nomes;
- Endereço: Endereços devem ser preenchidos no formato padrão do WHMCS, com logradouro e nº na mesma linha (campo "endereço 1"[address 1]), exemplo:
"Avenida Brasil, 1234"; - Campo personalizado Número: O número do endereço do cliente pode ser preenchido em um campo personalizado individual. O módulo detecta o campo pelo nome;
- Campo personalizado Inscrição estadual: Não é obrigatório na maioria dos casos. Para preencher o valor "Inscrição Estadual" do cliente nas notas fiscais crie um campo personalizado com o nome "Inscrição estadual" (exatamente assim). O módulo detecta o campo pelo nome;
- Erro ao enviar NFS-e à prefeitura: Indica que alguma configuração na sua conta Bling está incompleta ou há alguma autorização de acesso pendente junto à prefeitura, como por exemplo, o cadastramento do certificado digital. Tente enviar as notas fiscais manualmente para obter a mensagem de erro retornada pela prefeitura e entre em contato com o suporte Bling. Veja aqui como enviar notas de serviço à prefeitura.
Histórico de atualizações
Fixed bugs:
- Evita erros de compatibilidade com módulos de pagamento #2
* This Changelog was automatically generated by github_changelog_generator