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

<article id="bkmrk-objetivo-descrever-o"><section>#### 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`).

</section><section>---

#### Versão da ferramenta

<table><thead><tr><th>Nome</th><th>Versão/Build</th><th>Descrição curta</th><th>Responsável (owner)</th><th>Observações</th></tr></thead><tbody><tr><td>NFS-e Nacional (WHMCS Addon)</td><td>v1.0</td><td>Addon para emissão de NFS-e Nacional via API SEFIN com mTLS (certificado A1)</td><td>GK2 Cloud</td><td>XSD v1.01 — obrigatório bloco IBSCBS a partir de 2026</td></tr><tr><td>WHMCS</td><td>8.0+</td><td>Plataforma base de hospedagem/billing</td><td>Infra</td><td>—</td></tr><tr><td>PHP</td><td>8.1+</td><td>Runtime — extensões obrigatórias: openssl, curl, mbstring, zlib, json</td><td>Infra</td><td>—</td></tr></tbody></table>

---

</section><section>#### 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

</section><section>---

#### 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 **Setup → Addon Modules**[![image.png](https://oraculo.gk2.cloud/uploads/images/gallery/2026-04/scaled-1680-/l4Qimage.png)](https://oraculo.gk2.cloud/uploads/images/gallery/2026-04/l4Qimage.png)
    
      
    **Figura 1** - Acessando as opções
    
    [![image.png](https://oraculo.gk2.cloud/uploads/images/gallery/2026-04/scaled-1680-/jTAimage.png)](https://oraculo.gk2.cloud/uploads/images/gallery/2026-04/jTAimage.png)
    
      
    **Figura 2** - Acessando os módulos addon
2. Localize **NFS-e Nacional** e clique em **Activate**[![image.png](https://oraculo.gk2.cloud/uploads/images/gallery/2026-04/scaled-1680-/VzPimage.png)](https://oraculo.gk2.cloud/uploads/images/gallery/2026-04/VzPimage.png)
    
      
    **Figura 3** - Ativando o módulo
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.

[![image.png](https://oraculo.gk2.cloud/uploads/images/gallery/2026-04/scaled-1680-/JwLimage.png)](https://oraculo.gk2.cloud/uploads/images/gallery/2026-04/JwLimage.png)

  
**Figura 4** - Tela de configuração do módulo

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

<table><thead><tr><th>Campo</th><th>Obrigatório</th><th>Observação</th></tr></thead><tbody><tr><td>CNAE</td><td>Sim</td><td>Ex: `6209100` para TI</td></tr><tr><td>Código de Serviço LC 116 (cTribNac)</td><td>Sim</td><td>6 dígitos. Ex: `010700` para item 1.07</td></tr><tr><td>Código de Serviço NBS</td><td>Não</td><td>9 dígitos. Deixe vazio se não souber — evita erro E0316</td></tr><tr><td>Código de Tributação Municipal (cTribMun)</td><td>Não</td><td>Exatamente 3 dígitos. Deixe vazio se não souber — evita erro E0314</td></tr><tr><td>Exigibilidade do ISS</td><td>Sim</td><td>Para operações normais: `1-Exigível`</td></tr><tr><td>Alíquota ISS (%)</td><td>Não</td><td>Ex: `2.00`. Consulte a lei municipal</td></tr><tr><td>Retenção ISS (%)</td><td>Não</td><td>Deixe vazio se não houver retenção na fonte</td></tr></tbody></table>

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

<table><thead><tr><th>Campo</th><th>Obrigatório</th><th>Observação</th></tr></thead><tbody><tr><td>CNPJ do Prestador</td><td>Sim</td><td>14 dígitos — deve ser o mesmo CNPJ do certificado A1</td></tr><tr><td>Inscrição Municipal (IM)</td><td>Não</td><td>Deixe vazio se o município rejeitar — evita erro E0120</td></tr><tr><td>Código IBGE do Município</td><td>Sim</td><td>7 dígitos. Ex: `3550308` para São Paulo/SP</td></tr><tr><td>Regime Tributário</td><td>Sim</td><td>Conforme enquadramento da empresa</td></tr><tr><td>Optante pelo Simples Nacional</td><td>Sim</td><td>Marque se for ME ou EPP</td></tr><tr><td>Apuração Simples Nacional</td><td>Não</td><td>Obrigatório para optantes do Simples (evita erro E0166)</td></tr><tr><td>Regime Especial de Tributação</td><td>Não</td><td>0=Nenhum para a maioria dos casos</td></tr></tbody></table>

**Seção 3 — Certificado Digital A1**

<table><thead><tr><th>Campo</th><th>Obrigatório</th><th>Observação</th></tr></thead><tbody><tr><td>Caminho do Certificado A1</td><td>Sim</td><td>Caminho absoluto no servidor para o `.pfx`. Ex: `/etc/ssl/certs/empresa.pfx`</td></tr><tr><td>Senha do Certificado A1</td><td>Sim</td><td>Será criptografada com AES-256 automaticamente no banco ao salvar</td></tr></tbody></table>

**Seção 4 — API NFS-e Nacional**

<table><thead><tr><th>Campo</th><th>Obrigatório</th><th>Observação</th></tr></thead><tbody><tr><td>Ambiente</td><td>Sim</td><td>`homologacao` para testes (sem validade fiscal), `producao` para emissão real</td></tr><tr><td>Série da DPS</td><td>Não</td><td>Padrão: `1`. Não altere sem necessidade — muda a sequência numérica</td></tr><tr><td>Nome da Aplicação (verAplic)</td><td>Não</td><td>Identificador da aplicação emissora que aparece na NFS-e. Padrão: `WHMCS-NfseNac-1.0`. Máximo 20 caracteres</td></tr></tbody></table>

**Seção 5 — Configurações Operacionais**

<table><thead><tr><th>Campo</th><th>Obrigatório</th><th>Observação</th></tr></thead><tbody><tr><td>Campo CPF/CNPJ do Cliente</td><td>Sim</td><td>`taxid` usa o campo padrão do WHMCS; ou selecione um custom field</td></tr><tr><td>Emissão Automática de NFS-e **(política global do módulo)**</td><td>Sim</td><td>Define o comportamento padrão para todos os clientes que não têm configuração individual. Opções: `Não Emitir` / `Fatura Gerada` / `Fatura Paga`. Cada cliente pode sobrescrever essa política pelo custom field *Emitir NFS-e (Nacional)* no seu perfil.</td></tr><tr><td>Excluir Late Fee da Base de Cálculo</td><td>Não</td><td>Multas de atraso são excluídas do valor da NFS-e se habilitado</td></tr><tr><td>Faturas (Descontos)</td><td>Não</td><td>Deduz descontos da fatura da base de cálculo da NFS-e</td></tr><tr><td>Faturas (Fundos/Crédito)</td><td>Não</td><td>Deduz créditos aplicados na fatura da base de cálculo da NFS-e</td></tr><tr><td>Cancelar NFS-e ao Cancelar Fatura</td><td>Não</td><td>Cancelamento automático via API ao cancelar a fatura no WHMCS</td></tr><tr><td>Enviar NFS-e por E-mail</td><td>Não</td><td>Envia DANFS-e e XML ao cliente após autorização da nota</td></tr><tr><td>Perfis com Permissão Manual de NFS-e</td><td>Sim</td><td>IDs dos perfis admin autorizados a emitir manualmente (separados por vírgula). Vazio = todos os perfis</td></tr></tbody></table>

**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:

<table><thead><tr><th>Campo</th><th>Padrão</th><th>Observação</th></tr></thead><tbody><tr><td>Indicador de Operação (cIndOp)</td><td>`050101`</td><td>Para TI. Consulte tabela RFB</td></tr><tr><td>CST IBS/CBS</td><td>`000`</td><td>Tributação plena</td></tr><tr><td>Classificação Tributária (cClassTrib)</td><td>`000001`</td><td>Consulte tabela RFB</td></tr></tbody></table>

##### 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):

<table><thead><tr><th>Valor do campo</th><th>Comportamento</th></tr></thead><tbody><tr><td>*(vazio)*</td><td>Herda a política global definida nas configurações do módulo em *Emissão Automática de NFS-e*</td></tr><tr><td>`1- Nao Emitir NFS-e`</td><td>Nunca emite automaticamente; bloqueia também a emissão manual pelo admin</td></tr><tr><td>`2- Fatura Gerada`</td><td>Emite ao criar a fatura (hook InvoiceCreated), independente da política global</td></tr><tr><td>`3- Fatura Paga`</td><td>Emite somente após pagamento confirmado (hook InvoicePaid), independente da política global</td></tr></tbody></table>

**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`.

</section><section>---

#### 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)  
      
    [![image.png](https://oraculo.gk2.cloud/uploads/images/gallery/2026-04/scaled-1680-/zBLimage.png)](https://oraculo.gk2.cloud/uploads/images/gallery/2026-04/zBLimage.png)
    
      
    **Figura 5** - Listagem de notas fiscais

</section><section>---

#### 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.

</section><section>---

#### 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 &amp; 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`.

---

</section><section><section>#### Contexto de Ambiente

<table style="width: 100%;"><thead><tr><th>Ambiente-alvo</th><th>Objetivo neste ambiente</th><th>Descrição curta</th></tr></thead><tbody><tr><td>Homologação</td><td>Testar emissão, cancelamento e download sem validade fiscal</td><td>Endpoint: `sefin.producaorestrita.nfse.gov.br/SefinNacional`</td></tr><tr><td>Produção</td><td>Emissão real com validade jurídica e fiscal</td><td>Endpoint: `sefin.nfse.gov.br/SefinNacional`</td></tr></tbody></table>

---

</section></section><section><div><section>#### Controle de Mudanças

<details><summary>Informações de controle de versão</summary>

- **Última revisão** 13-04-2026
- **Próxima revisão** 13-10-2026
- **Autor** GK2 Cloud
- **Revisor** —
- **Versão** 1.0.0

</details></section>---

</div>#### 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.

</section><section>---

#### 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/](https://www.nfse.gov.br/ConsultaPublica/)
- ViaCEP (consulta IBGE por CEP): [https://viacep.com.br/](https://viacep.com.br/)

</section></article>