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. Figura 1 - Dashboard módulo 2. Emitir uma NFS-e manualmente Abra a fatura no admin: Billing → Invoices → [número da fatura] No painel lateral NFS-e Nacional , clique em Emitir NFS-e Confirme no modal de confirmação clicando em OK Aguarde o retorno — a página recarrega com o resultado: AUTORIZADA (sucesso) ou ERRO (veja seção Problema/Solução) 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 cliente Comportamento (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.   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. 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.   Figura 5 - Opções de ver DANFS-e e baixar XML 6. Cancelar uma NFS-e Abra a fatura no admin No painel NFS-e Nacional , clique em Cancelar NFS-e Confirme no modal — o módulo envia o evento de cancelamento (código 101101) ao SEFIN 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. 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 / Erro Causa Solução E0120 enviado mas município não tem IM no CNC NFS-e Deixe o campo Inscrição Municipal vazio nas configurações do addon E0166 regApTribSN ausente para Simples Nacional Preencha Apuração Simples Nacional nas configurações (1=Competência, 2=Caixa) E0240 CEP do tomador não pertence ao município informado Corrija o CEP do cliente ou adicione entrada em data/cep_ibge.json E0314 Código de tributação municipal inválido Deixe o campo cTribMun vazio ou corrija com a prefeitura E0316 Código NBS não existe na tabela RFB Deixe o campo Código de Serviço NBS vazio nas configurações E0812 CNPJ do autor não corresponde ao certificado Confirme que o CNPJ configurado é o mesmo do certificado A1 E0822 Prazo de cancelamento expirado Prazo definido pelo município — após o prazo não há cancelamento pela API HTTP 496 mTLS ausente — certificado não configurado Verifique o caminho e senha do .pfx nas configurações do addon HTTP 502 no DANFS-e API ADN do governo instável Aguarde e tente novamente. Veja Activity Log para detalhes do erro E-mail Sending Failed Template com tipo errado ou ID incorreto Confirme tipo general e id=clientId no template do módulo Emissão automática não dispara Política global do módulo ou campo do cliente mal configurado Verifique 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 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