Guia: NFS-e Nacional — Utilização e Operação

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

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)
   
   

   

   
   
   

   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.

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

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.

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

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.

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