NFS-e Nacional - Módulo de Integração em HarbourMódulo robusto e independente em Harbour para comunicação com o Sistema Nacional de Nota Fiscal de Serviço eletrônica (NFS-e Nacional / Sefin Nacional). O projeto cobre todo o ciclo de vida do documento fiscal: desde a estruturação da DPS até o retorno oficial, gestão de eventos (como cancelamento) e renderização gráfica do DANFSe (Documento Auxiliar da NFS-e) em PDF.
Arquitetura dos MódulosO código é altamente modularizado para facilitar a incorporação em sistemas comerciais legados ou modernos em Harbour:
Arquivo / Módulo Descrição Técnican
fse_config.prg Gerenciamento de ambiente (TNfseConfig), URLs de Homologação e Produção, timeouts e credenciais de certificados digitais (arquivos PFX ou Windows Certificate Store).nfse_dps_gera.prgMontagem estruturada do XML da DPS (<DPS><infDPS>...</infDPS></DPS>), calculando o ID regulamentar e alimentando blocos de prestador, tomador, serviço e tributos municipais/federais.nfse_assina.prgAssinatura digital padrão XMLDSig com RSA-SHA256 exigida pelo leiaute nacional (canonicalização C14N, cálculo de digest, assinatura do hash e injeção do bloco <Signature>).
nfse_gzip.c.prg / nfse_gunzip.c.prg Rotinas nativas em C (sem dependência de DLLs ou zlib.lib externas) para compressão GZIP/DEFLATE no envio (dpsXmlGZipB64) e descompactação do XML de retorno (nfseXmlGZipB64).
nfse_http.prg Camada de transporte HTTP com suporte a mTLS (Mutual TLS via WinHttp) para requisições POST e GET autenticadas com segurança com os servidores da Sefin.
nfse_envio.prg Orquestração do envio síncrono da NFS-e (NfseEmiteNFSe) e despacho de evento (NfseRegistraEvento).
nfse_evento_gera.prg Montagem do XML de Pedido de Registro de Evento (<pedRegEvento><infPedReg>) para cancelamentos e manifestações.
nfse_consulta.prg Consultas detalhadas à API do Sefin Nacional por chave de acesso ou histórico de eventos.demo_emissao.prgHarness prático demonstrando o fluxo ponta a ponta de parametrização, montagem, envio em homologação e tratamento de retorno.
Exemplo de Uso:Geração, Assinatura e EnvioO trecho abaixo demonstra como configurar o ambiente, preencher os dados da DPS e realizar a emissão síncrona da NFS-e:Snippet de código#include "nfse_nacional.ch"
Código: Selecionar todos
#include "hbhash.ch"
PROCEDURE Main()
LOCAL oConfig, hDps, hRetorno
// 1. Configuração do Ambiente e Certificado Digital PFX
oConfig := TNfseConfig():New()
oConfig:UseProducaoRestrita() // Homologação (Sefin URL de testes)
oConfig:SetCertificadoPfx("C:\cert\certificado.pfx", "123456")
// 2. Montagem do Hash com os Dados da DPS
hDps := hb_Hash()
hb_HSet( hDps, "nTpAmb", NFSE_AMBIENTE_HOMOLOG )
hb_HSet( hDps, "cCnpjPrestador", "12329311000199" )
hb_HSet( hDps, "cImPrestador", "37925504" )
hb_HSet( hDps, "cRazaoPrestador", "EMPRESA EXEMPLO LTDA" )
hb_HSet( hDps, "cCodMunPrestacao", "3550308" ) // São Paulo/SP
hb_HSet( hDps, "nOpSimplesNacional", 3 ) // 1=Não optante, 2=MEI, 3=ME/EPP
// Tomador
hb_HSet( hDps, "cCnpjCpfTomador", "99567805000199" )
hb_HSet( hDps, "cRazaoTomador", "TOMADOR DE SERVICOS LTDA" )
// Serviço e Valores
hb_HSet( hDps, "cTribNac", "010401" )
hb_HSet( hDps, "cDescricaoServico", "Prestação de Serviços de Consultoria Técnica" )
hb_HSet( hDps, "nValorServico", 1000.00 )
hb_HSet( hDps, "nAliquota", 2.00 )
hb_HSet( hDps, "cSerie", "00001" )
hb_HSet( hDps, "nNumeroDps", 1 )
hb_HSet( hDps, "dCompetencia", Date() )
// 3. Emissão Síncrona (Gera XML -> Assina RSA-SHA256 -> GZIP -> POST JSON)
? "Enviando DPS para o Sefin Nacional..."
IF NfseEmiteNFSe( oConfig, hDps, @hRetorno )
? "Sucesso na Emissão!"
? "Chave de Acesso:", hb_HGet( hRetorno, "chaveAcesso" )
? "ID da DPS:", hb_HGet( hRetorno, "idDps" )
// Salva o XML oficial descomprimido retornado pelo Sefin
IF ! Empty( hb_HGet( hRetorno, "nfseXml" ) )
hb_memowrit("nfse_autorizada.xml", hb_HGet( hRetorno, "nfseXml" ))
ENDIF
ELSE
? "Erro na Emissão:", hb_HGet( hRetorno, "erro" )
ENDIF
RETURN
Cancelamento e Gestão de EventosPara realizar o cancelamento de uma NFS-e autorizada, a rotina encapsula a geração do evento regulamentar (e101101), aplicando a assinatura digital e o envio para a API:
Snippet de código
Código: Selecionar todos
LOCAL hRetornoCancela := hb_Hash()
LOCAL cChaveNfse := "3526071022931100018056000000000000001..."
LOCAL cCnpjAutor := "12329311000199"
IF NfseCancelaNFSe( oConfig, cChaveNfse, cCnpjAutor, 1, "Nota emitida com erro operacional", @hRetornoCancela )
? "NFS-e cancelada com sucesso! Evento ID:", hb_HGet( hRetornoCancela, "idPedidoRegistro" )
ELSE
? "Erro ao cancelar:", hb_HGetDef( hRetornoCancela, "erro", "Erro desconhecido" )
ENDIF
Após o retorno e salvamento do XML oficial (nfseXml), você pode utilizar a classe de impressão do DANFSe para gerar o arquivo PDF formatado para entrega ao cliente ou impressão direta.Parâmetros Principais da Função de Impressão (danfse.prg)cArquivoXml: Caminho completo do arquivo XML no disco ou string contendo diretamente o conteúdo do XML da NFS-e Nacional oficial.cFilePdf: (Opcional) Nome ou diretório do arquivo PDF de saída. Caso omitido ou em branco, a rotina gerará automaticamente como danfse_<chave_acesso>.pdf.
Estrutura Gráfica do DANFSe GeradoO relatório PDF gerado contempla rigorosamente os padrões estipulados pela legislação nacional:
Cabeçalho: Logotipo oficial, Chave de Acesso de 44 dígitos, Número da NFS-e, Número da DPS, Data de Competência, Tipo de Emissão e QR Code para consulta pública.Identificação dos Envolvidos: Blocos detalhados contendo CNPJ/CPF, Inscrição Municipal, Razão Social e Endereço do Prestador e do Tomador do Serviço.Detalhamento do Serviço: Códigos de Tributação (Nacional e Municipal), Código NBS, Local da Prestação e Descrição Completa do Objeto do Serviço.Tributação Municipal (ISSQN): Base de cálculo, Alíquota aplicável, Valor do imposto, Retenções e Descontos condicionados/incondicionados.Tributação Federal & Reforma Tributária: Demonstração de valores retidos (IRRF, CSLL, PIS, COFINS) e projeções regulamentares de IBS/CBS.
Observações ImportantesModelos de Emissão (tpEmis): O sistema suporta nativamente os dois modelos regulamentares da NFS-e Nacional:
1 — Emissão direta no modelo da NFS-e Nacional (gerada diretamente pelo ambiente Sefin).
2 — Emissão original em leiaute próprio do município com transcrição posterior para o ADN (Ambiente de Dados Nacional).
Sincronia de Horário (dhEmi):
O gerador da DPS aplica automaticamente uma margem preventiva de segurança de relógio para mitigar rejeições por divergência temporal com os servidores da Receita Federal.
Compatibilidade: Desenvolvido e otimizado para Harbour 3.2+ em conjunto com compiladores C modernos (BCC58/582 ou MSVC), utilizando chamadas nativas WinHTTP para conexões seguras mTLS.
Autor & LicençaProjeto distribuído sob a licença MIT. Sinta-se à vontade para contribuir com melhorias, issues e pull requests.Att.
Marcelo A. L. Carli
Marília/SP
Capital Nacional do Alimento ®
https://malc-informatica.ueniweb.com
Insta: @malcarli25
Email / Skype: marceloalcarli@gmail.com