Configuração: NFS-e Nacional - v1.0 - Produção e Homologação

Objetivo

Descrever o processo de instalação, configuração e ativação do addon NFS-e Nacional no WHMCS, permitindo a emissão, consulta e cancelamento de NFS-e via API SEFIN/ADN do governo federal (sefin.nfse.gov.br).

Versão da ferramenta

Pré-requisitos

• Acesso SSH ao servidor com permissão para instalar dependências via Composer
• Composer 2.x instalado no servidor
• Certificado digital ICP-Brasil A1 (.pfx / .p12) válido e dentro da validade
• CNPJ do prestador idêntico ao CNPJ do certificado A1
• Acesso ao painel admin do WHMCS com permissão para gerenciar addons
• Servidor web com suporte a regras de bloqueio de acesso a arquivos sensíveis (Apache ou nginx)
• Código IBGE do município (7 dígitos), código de serviço LC 116 (6 dígitos) e CNAE definidos com o contador

Passos de configuração

Passo 1 — Upload dos arquivos

Copie a pasta nfsenacional para o diretório de addons do WHMCS:

modules/addons/nfsenacional/

Confirme que a estrutura contém ao menos: nfsenacional.php, hooks.php, cron.php, composer.json e a pasta src/.

Passo 2 — Instalar dependências via Composer

Acesse o diretório do módulo e execute:

cd /caminho/para/whmcs/modules/addons/nfsenacional
composer install --no-dev --optimize-autoloader

Isso instalará robrichards/xmlseclibs (assinatura XML RSA-SHA256) e guzzlehttp/guzzle (cliente HTTP). O diretório vendor/ será criado dentro do módulo.

Passo 3 — Permissões de arquivos

chown -R www-data:www-data /caminho/para/whmcs/modules/addons/nfsenacional
chmod -R 755 /caminho/para/whmcs/modules/addons/nfsenacional
chmod 644 /caminho/para/whmcs/modules/addons/nfsenacional/nfsenacional.php

O arquivo .nfse_enc_key (chave AES-256 para criptografia da senha do certificado) será criado automaticamente com permissão 0600 no primeiro acesso ao painel admin.

Passo 4 — Proteger o arquivo de chave de criptografia

Apache — crie modules/addons/nfsenacional/.htaccess:

<Files ".nfse_enc_key">
    <IfModule mod_authz_core.c>
        Require all denied
    </IfModule>
    <IfModule !mod_authz_core.c>
        Order allow,deny
        Deny from all
    </IfModule>
</Files>

nginx — adicione no bloco server {} do vhost:

location ~* /modules/addons/nfsenacional/\.nfse_enc_key {
    deny all;
    return 404;
}

Após editar o nginx, recarregue: nginx -t && systemctl reload nginx

Passo 5 — Certificado digital A1

Armazene o arquivo .pfx / .p12 em um caminho fora do webroot ou em diretório protegido. Exemplos:

/etc/ssl/certs/empresa/certificado.pfx
/var/www/certs/certificado.pfx

Ajuste as permissões:

chmod 640 /caminho/para/certificado.pfx
chown root:www-data /caminho/para/certificado.pfx

Passo 6 — Ativar o addon no WHMCS

1. Acesse Admin → Configurações → Apps & Integrações (ou Setup → Addon Modules)

   

   
   

   Figura 1 - Acessando as opções
   

   

   Figura n - Explicação da figura

2. Localize NFS-e Nacional e clique em Activate
3. Após ativar, o módulo cria automaticamente: tabela tblnfsenacional, template de e-mail NFS-e Nacional (tipo general) e custom fields de cliente (Emitir NFS-e (Nacional) e Reter ISS (Nacional))

Passo 7 — Configurar o addon

Acesse Admin → Addons → NFS-e Nacional → Configurar e preencha os campos organizados pelas seções abaixo.

Seção 1 — Tributação e Serviços

Seção 2 — Dados da Empresa (Prestador)

Seção 3 — Certificado Digital A1

Seção 4 — API NFS-e Nacional

Seção 5 — Configurações Operacionais

Seção 6 — IBS/CBS (Reforma Tributária)

Campos obrigatórios no XSD v1.01 a partir de 2026. Preencha conforme orientação do contador:

Passo 8 — Configurar comportamento por cliente

No perfil de cada cliente no admin, preencha o custom field Emitir NFS-e (Nacional). Este campo sobrescreve a política global configurada no módulo (campo Emissão Automática de NFS-e da Seção 5):

Atenção: campo vazio no cliente ≠ "Não Emitir". Quando vazio, o módulo usa a política global. A emissão manual pelo painel admin está disponível para qualquer cliente, exceto quando o campo está explicitamente como 1- Nao Emitir NFS-e.

Validação pós-configuração

• Acesse Admin → Addons → NFS-e Nacional e confirme que o painel carrega sem erros
• Verifique se o badge de ambiente exibe Homologação ou Produção
• Crie ou selecione uma fatura de teste e clique em Emitir NFS-e — o status deve retornar AUTORIZADA
• Teste o download do DANFS-e e do XML pela página de detalhe da nota
• Se o envio de e-mail estiver ativo, verifique o recebimento pelo cliente
• Confirme que o arquivo .nfse_enc_key foi criado com permissão 0600 e está inacessível via HTTP (retorna 404)

Considerações de segurança

• Chave AES-256: o arquivo .nfse_enc_key armazena a chave de criptografia da senha do certificado. Deve ser protegido por regra nginx/Apache e ter permissão 0600. Um dump de banco sozinho não expõe a senha do certificado.
• Certificado A1: jamais armazene o .pfx dentro do webroot público sem proteção. Use caminhos fora do public_html/.
• Tokens de ação: todos os botões destrutivos (emitir, cancelar, excluir) usam tokens HMAC-SHA256 gerados por instalação — resistentes a CSRF e timing attacks.
• Proxy mTLS: os links de DANFS-e e XML são servidos pelo proxy interno do módulo com certificado A1 — nunca expostos diretamente. Tokens HMAC impedem enumeração de IDs.
• Senha do certificado: armazenada criptografada (prefixo ENC:) em tbladdonmodules. Nunca logar ou exibir o valor bruto.

Backups/Rollback

Backup antes da instalação

• Faça backup do banco de dados do WHMCS antes de ativar o addon
• Guarde o arquivo .nfse_enc_key em local seguro após a primeira geração — sem ele, a senha do certificado armazenada no banco não pode ser descriptografada

Rollback

Passo 1

Desative o addon em Admin → Configurações → Apps & Integrações → NFS-e Nacional → Deactivate.

Passo 2

Remova a pasta modules/addons/nfsenacional/ do servidor.

Passo 3

Restaure o backup do banco caso necessário. A tabela tblnfsenacional e os custom fields criados podem ser removidos manualmente via SQL se necessário.

Passo 4

Remova as regras de bloqueio do nginx/Apache adicionadas para o .nfse_enc_key.

Notas Adicionais

• Mudar o ambiente de homologacao para producao não apaga registros anteriores — eles ficam no banco com ambiente='homologacao' e não aparecem no painel.
• O campo Inscrição Municipal deve ser deixado vazio se o município ainda não tem IM cadastrado no CNC NFS-e (evita erro E0120).
• O campo Código NBS deve ser deixado vazio se não tiver certeza do código correto (evita erro E0316).
• O CEP do endereço do tomador deve pertencer ao município informado em cMun — caso contrário o SEFIN retorna erro E0240. Configure fallback manual em data/cep_ibge.json quando necessário.

Referências

• API SEFIN Nacional — Swagger em docs/API NFS-e - Sefin Nacional (v1).json dentro do módulo
• XSD oficial v1.01 — docs/nfse-esquemas_xsd-prodrest-v1-01-*/Schemas/1.01/
• Portal público de consulta: https://www.nfse.gov.br/ConsultaPublica/
• ViaCEP (consulta IBGE por CEP): https://viacep.com.br/