# Guia: NFS-e Nacional — Utilização e Operação
#### Escopo e Público - **Aplica-se a:** emissão, consulta, cancelamento e reenvio de NFS-e Nacional pelo painel admin do WHMCS - **Não cobre:** instalação do módulo (ver página de Configuração), obrigações fiscais do prestador, regras tributárias municipais - **Público-alvo:** administradores do WHMCS com perfil de acesso ao addon NFS-e Nacional
---
#### Contexto O addon **NFS-e Nacional** integra o WHMCS à API SEFIN do governo federal para emissão automática ou manual de Notas Fiscais de Serviço Eletrônicas (NFS-e) conforme o padrão nacional. A comunicação usa mTLS com certificado digital ICP-Brasil A1.
--- #### Objetivo Descrever de forma clara e prática como operar o módulo NFS-e Nacional no dia a dia: emitir notas, acompanhar status, cancelar, reenviar e-mails, configurar o comportamento por cliente e interpretar erros comuns.
--- #### Pré-requisitos - Módulo instalado e configurado conforme a página de Configuração - Ambiente definido (`homologacao` ou `producao`) nas configurações do addon - Certificado A1 válido com caminho e senha configurados - Perfil admin com permissão no campo **Perfis com Permissão Manual de NFS-e**
--- #### Passos ##### 1. Acessar o painel NFS-e Nacional Acesse **Admin → Addons → NFS-e Nacional**. O painel exibe: badge de ambiente, totais por status (Autorizadas, Canceladas, Erros), listagem das notas recentes com links para detalhe e fatura, e botão **Ver Todas** para filtros avançados. [![image.png](https://oraculo.gk2.cloud/uploads/images/gallery/2026-04/scaled-1680-/j32image.png)](https://oraculo.gk2.cloud/uploads/images/gallery/2026-04/j32image.png) **Figura 1** - Dashboard módulo ##### 2. Emitir uma NFS-e manualmente 1. Abra a fatura no admin: **Billing → Invoices → \[número da fatura\]** 2. No painel lateral **NFS-e Nacional**, clique em **Emitir NFS-e** 3. Confirme no modal de confirmação clicando em **OK** 4. Aguarde o retorno — a página recarrega com o resultado: `AUTORIZADA` (sucesso) ou `ERRO` (veja seção Problema/Solução) [![image.png](https://oraculo.gk2.cloud/uploads/images/gallery/2026-04/scaled-1680-/ucKimage.png)](https://oraculo.gk2.cloud/uploads/images/gallery/2026-04/ucKimage.png) **Figura 2** - Emitindo nota fiscal manualmente **Atenção:** a emissão manual só é bloqueada quando o campo *Emitir NFS-e (Nacional)* do cliente estiver explicitamente como `1- Nao Emitir NFS-e`. Campo vazio no cliente (que herda a política global do módulo) ou política global configurada como "Não Emitir" **não bloqueiam** a emissão manual pelo admin. ##### 3. Emissão automática — política global do módulo e por cliente A emissão automática tem dois níveis de configuração: - **Política global do módulo** — definida em **Admin → Addons → NFS-e Nacional → Configurar → Seção 5 → Emissão Automática de NFS-e**. É o comportamento padrão aplicado a todos os clientes que não têm configuração individual. - **Política individual por cliente** — definida no custom field **Emitir NFS-e (Nacional)** no perfil do cliente. Quando preenchido, **sobrescreve** completamente a política global do módulo para aquele cliente.
Valor do campo no clienteComportamento
*(vazio)*Herda a **política global do módulo** (campo *Emissão Automática de NFS-e* nas configurações do addon)
`1- Nao Emitir NFS-e`Nunca emite automaticamente; bloqueia também a emissão manual pelo admin
`2- Fatura Gerada`Emite ao criar a fatura (hook InvoiceCreated), independente da política global do módulo
`3- Fatura Paga`Emite após pagamento confirmado (hook InvoicePaid), independente da política global do módulo
**Exemplo prático:** se a política global do módulo for `Não Emitir` e um cliente específico tiver o campo vazio, nenhuma nota será emitida automaticamente para ele. Para emitir automaticamente apenas para clientes selecionados, mantenha a política global como `Não Emitir` e configure individualmente cada cliente que deve receber NFS-e. [![image.png](https://oraculo.gk2.cloud/uploads/images/gallery/2026-04/scaled-1680-/xG0image.png)](https://oraculo.gk2.cloud/uploads/images/gallery/2026-04/xG0image.png) **Figura 3** - Política de emissão individual ##### 4. Consultar status de uma NFS-e Acesse a fatura no admin e localize o painel **NFS-e Nacional**. Ou acesse **Addons → NFS-e Nacional → Ver Todas** e use os filtros por status, fatura, cliente ou data. Clique no ID da nota para ver detalhe completo: chave de acesso, número, XML de retorno, links de DANFS-e e XML. [![image.png](https://oraculo.gk2.cloud/uploads/images/gallery/2026-04/scaled-1680-/57Kimage.png)](https://oraculo.gk2.cloud/uploads/images/gallery/2026-04/57Kimage.png) **Figura 4** - Listagem de notas fiscais ##### 5. Baixar DANFS-e e XML Na página de detalhe da nota (ou no painel da fatura), clique em **Ver DANFS-e** ou **Baixar XML**. Os documentos são obtidos via proxy mTLS do módulo — o cliente recebe o arquivo sem precisar de certificado próprio. [![image.png](https://oraculo.gk2.cloud/uploads/images/gallery/2026-04/scaled-1680-/SnOimage.png)](https://oraculo.gk2.cloud/uploads/images/gallery/2026-04/SnOimage.png) **Figura 5** - Opções de ver DANFS-e e baixar XML ##### 6. Cancelar uma NFS-e 1. Abra a fatura no admin 2. No painel **NFS-e Nacional**, clique em **Cancelar NFS-e** 3. Confirme no modal — o módulo envia o evento de cancelamento (código 101101) ao SEFIN 4. Se aprovado, o status muda para `CANCELADA` O prazo para cancelamento é parametrizado pelo município emissor. Após o prazo, o SEFIN retorna erro E0822. [![image.png](https://oraculo.gk2.cloud/uploads/images/gallery/2026-04/scaled-1680-/P4gimage.png)](https://oraculo.gk2.cloud/uploads/images/gallery/2026-04/P4gimage.png) **Figura 6** - Cancelar nota fiscal ##### 7. Reenviar e-mail com a NFS-e Na página de detalhe ou no painel da fatura, clique em **Reenviar E-mail**. O e-mail *NFS-e Nacional* será reenviado ao cliente com os links de DANFS-e e XML. ##### 8. Tratar notas com erro Acesse **Addons → NFS-e Nacional → Ver Todas** e filtre por status `ERRO`. Clique no ID para ver a mensagem retornada pela API. Após corrigir a causa, use **Excluir Registro** na nota e emita novamente. ##### 9. Resolver CEP com código IBGE inválido (E0240) Se o SEFIN rejeitar com E0240 (CEP não pertence ao município informado), corrija o CEP do cliente no WHMCS para um CEP válido, ou adicione uma entrada manual em `modules/addons/nfsenacional/data/cep_ibge.json`: ``` { "87160": "4114203" } ``` A chave pode ser o CEP exato (8 dígitos) ou o prefixo de 5 dígitos. O valor é o código IBGE. Para encontrar o IBGE de um CEP: `https://viacep.com.br/ws/SEU_CEP/json/` — campo `ibge`.
--- #### Dicas - Use o ambiente `homologacao` para treinar a equipe e testar novos cenários — as notas não têm validade fiscal - Para clientes que não devem receber NFS-e, configure o campo individual como `1- Nao Emitir NFS-e` - Para emitir só para clientes selecionados: mantenha a **política global do módulo** como `Não Emitir` e configure individualmente cada cliente desejado - Notas com status `PROCESSANDO` por mais de 10 minutos indicam timeout — exclua e emita novamente - O campo **verAplic** (identificador da aplicação na NFS-e) é configurável nas configurações do módulo — máximo 20 caracteres. Acesse Seção 4 → *Nome da Aplicação (verAplic)* - O Activity Log do WHMCS (**Utilities → Activity Log**) registra todas as falhas de comunicação — primeira fonte de diagnóstico - Os nomes de clientes na listagem são links que abrem o perfil do cliente em nova aba
--- #### Problema/Solução
Problema / ErroCausaSolução
E0120<IM> enviado mas município não tem IM no CNC NFS-eDeixe o campo Inscrição Municipal vazio nas configurações do addon
E0166regApTribSN ausente para Simples NacionalPreencha Apuração Simples Nacional nas configurações (1=Competência, 2=Caixa)
E0240CEP do tomador não pertence ao município informadoCorrija o CEP do cliente ou adicione entrada em data/cep\_ibge.json
E0314Código de tributação municipal inválidoDeixe o campo cTribMun vazio ou corrija com a prefeitura
E0316Código NBS não existe na tabela RFBDeixe o campo Código de Serviço NBS vazio nas configurações
E0812CNPJ do autor não corresponde ao certificadoConfirme que o CNPJ configurado é o mesmo do certificado A1
E0822Prazo de cancelamento expiradoPrazo definido pelo município — após o prazo não há cancelamento pela API
HTTP 496mTLS ausente — certificado não configuradoVerifique o caminho e senha do .pfx nas configurações do addon
HTTP 502 no DANFS-eAPI ADN do governo instávelAguarde e tente novamente. Veja Activity Log para detalhes do erro
E-mail Sending FailedTemplate com tipo errado ou ID incorretoConfirme tipo general e id=clientId no template do módulo
Emissão automática não disparaPolítica global do módulo ou campo do cliente mal configuradoVerifique o campo do cliente — se vazio, herda a política global do módulo (*Emissão Automática de NFS-e* nas configurações)
#### FAQ (Perguntas frequentes)
Campo vazio em "Emitir NFS-e (Nacional)" significa que a nota não será emitida? Não. Campo vazio significa que o cliente herda a **política global configurada no módulo** (campo *Emissão Automática de NFS-e* em Addons → NFS-e Nacional → Configurar → Seção 5). Se o global for "Fatura Paga", a nota será emitida automaticamente ao pagar. Somente o valor `1- Nao Emitir NFS-e` bloqueia a emissão para aquele cliente.
Posso emitir manualmente para um cliente cuja política global do módulo é "Não Emitir"? Sim. A política global do módulo em "Não Emitir" só bloqueia a emissão automática. A emissão manual pelo admin só é bloqueada quando o campo individual do cliente está explicitamente como `1- Nao Emitir NFS-e`. Se o campo do cliente estiver vazio (herdando o global), a emissão manual continua disponível.
Como confirmar que uma nota foi realmente cancelada no SEFIN? O módulo só marca CANCELADA quando o SEFIN retorna sucesso. Confirme externamente no Portal Público NFS-e (https://www.nfse.gov.br/ConsultaPublica/) com a chave de acesso, ou verifique o Activity Log do WHMCS buscando por NfseNacional.
O cliente precisa estar logado para acessar o DANFS-e pelo link do e-mail? Não. O link contém um token HMAC assinado que permite o acesso sem login. Se o cliente estiver logado, o módulo verifica adicionalmente que a nota pertence ao cliente.
Como mudar o nome da aplicação na NFS-e (verAplic)? Acesse Addons → NFS-e Nacional → Configurar → Seção 4 → campo *Nome da Aplicação (verAplic)*. Padrão: WHMCS-NfseNac-1.0. Máximo 20 caracteres.
O que acontece com as notas de homologação ao mudar para produção? Os registros de homologação ficam no banco com ambiente=homologacao e não aparecem no painel. Não é necessário cancelá-los. Notas de homologação não têm validade fiscal.
---
#### Contatos de suporte
- GK2.CLOUD — [Whatsapp](https://gk2.cloud/whatsapp)
---
#### Controle de Mudanças
Informações de controle de versão - **Última revisão** 13-04-2026 - **Próxima revisão** 13-10-2026 - **Autor** GK2 Cloud - **Revisor** — - **Versão** 1.0.1
---
#### Notas adicionais - O Activity Log do WHMCS (Utilities → Activity Log) é o principal canal de diagnóstico — todas as falhas de comunicação com o SEFIN e ViaCEP são registradas lá. - A listagem de NFS-e exibe o nome do cliente como link para o perfil do cliente no admin (abre em nova aba). - O painel NFS-e aparece também na tela de edição de cada fatura com botões de ação contextuais. --- #### Referências - Portal Público NFS-e: https://www.nfse.gov.br/ConsultaPublica/ - ViaCEP: https://viacep.com.br/ - API SEFIN Nacional — Swagger em docs/API NFS-e - Sefin Nacional (v1).json dentro do módulo