ZaptVupt ZV-DELPHI-DFE-NFE-SDK • v1.0.0

ZaptVupt Delphi DFe / NF-e 4.00 & NFC-e 65 SDK - Motor Fiscal Clean-Room

SDK Clean-Room Delphi 10.3 ao 13.2 para NF-e 4.00 e NFC-e 65 sem dependencias externas: WinHTTP SOAP 1.2 mTLS A1/A3, XMLDSig WinCrypto, Chave Modulo 11, CC-e, Cancelamento e DANFE HTML/Canvas

Gates G0-G4: Aprovados | Testes automatizados: 80 passed, 0 failed | Bundle SHA-256: 8240f494ea060f9b...

ZaptVupt Delphi DFe / NF-e 4.00 & NFC-e 65 SDK (v1.0.0)

SKU: ZV-DELPHI-DFE-NFE-SDK

Categoria: SDKs & Componentes Delphi Clean-Room

Compatibilidade: Delphi 10.3 ao 13.2 (10.3 Rio, 10.4 Sydney, 11 Alexandria, 12 Athens, 13.2 Florence — Win32 e Win64)

Licença: Comercial Perpétua com Código-Fonte 100% Aberto (Uso e compilação em ERPs e PDVs ilimitados pelo adquirente)

---

Visão Geral de Engenharia

O ZaptVupt Delphi DFe / NF-e 4.00 & NFC-e 65 SDK é um motor fiscal completo escrito em Object Pascal moderno com arquitetura Clean-Room Nativa Windows/RTL, eliminando por completo a dependência de bibliotecas C externas de terceiros, pacotes pesados ou dezenas de DLLs em rede para distribuir no cliente final.

Toda a cadeia crítica de emissão fiscal eletrônica brasileira é executada por código Delphi auditável e APIs oficiais do próprio sistema operacional Windows:

  • Chave de Acesso 44 Dígitos (Módulo 11 SEFAZ): Montagem, validação matemática estrita, formatação visual em blocos e geração determinística de cNF.
  • NFC-e QR Code v2 Oficial: Geração da URL autenticada via SHA-1 com CSC (idToken + TokenCSC) e renderização vetorial em SVG ou matriz binária via DelphiZXIngQRCode.
  • Serializador XML Layout NF-e 4.00 / NFC-e 65: Construção estruturada de <NFe xmlns="http://www.portalfiscal.inf.br/nfe"> e <infNFe> com totalizadores automáticos de produtos, ICMS, descontos, PIS/COFINS e meios de pagamento (tPag=17 Pix Dinâmico, Cartão, Dinheiro).
  • Assinatura Digital XMLDSig Enveloped (SHA-1 RSA): Assinatura nativa via Windows CryptoAPI (crypt32.dll / advapi32.dll), suportando tanto certificados A1 (.PFX) em memória quanto A3 / Store Pessoal do Windows (MY) por thumbprint SHA-1, além de verificador de integridade (VerifySignedXmlDigest) e assinador determinístico isolado para testes unitários sem certificado real.
  • Transporte SOAP 1.2 SEFAZ 4.00 via WinHTTP Nativo (System.Net.HttpClient): Envelopes completos para os quatro serviços essenciais em Produção e Homologação nas 27 UFs (SP, MG, PR, RS, BA, GO, MT, MS, PE, AM, SVRS e SVAN):
  • NFeStatusServico4 (cStat 107)
  • NFeAutorizacao4 Síncrono e Assíncrono + consolidação automática <nfeProc> (cStat 100 / 150)
  • NFeConsultaProtocolo4
  • NFeRecepcaoEvento4 — Cancelamento (110111) e Carta de Correção Eletrônica CC-e (110110, cStat 135)
  • DANFE A4 (NF-e 55) & Cupom Térmico 80mm (NFC-e 65): Motor próprio em HTML5 + código de barras ITF-25 100% vetorial SVG + QR Code SVG nativo + pré-visualização rápida em VCL Canvas (TPaintBox / TCanvas) sem dependências de geradores comerciais de relatório.

---

Arquitetura de Pacotes & Módulos


ZV_Delphi_DFe_NFe_SDK/
├── src/
│   ├── Vendor_ZVCore/        # Nucleo compartilhado RTL + Http mTLS + QRCode pure Pascal
│   ├── Source/
│   │   ├── ZV.DFe.Types.pas          # Records fiscais, configuracao e tabela IBGE/Autorizadores
│   │   ├── ZV.DFe.ChaveAcesso.pas    # Chave 44 digitos Mod-11 + URL NFC-e QR Code v2
│   │   ├── ZV.DFe.XmlBuilder.pas     # XML NF-e 4.00, Eventos e Envelopes SOAP 1.2
│   │   ├── ZV.DFe.Signature.pas      # Assinatura XMLDSig A1 PFX / A3 WinCrypto & TestSigner
│   │   ├── ZV.DFe.SefazClient.pas    # Cliente SOAP 1.2 WinHTTP com mTLS e parsers protNFe
│   │   ├── ZV.DFe.DanfeRender.pas    # DANFE HTML + ITF-25 SVG + Cupom 80mm + VCL Canvas
│   │   └── ZV.DFe.Facade.pas         # Fachada TZVDFeManager de integracao rapida
│   └── Packages/
│       ├── ZV.DFeSDK.D12.dpk         # Pacote Delphi 12 runtime
│       └── ZV.DFeSDK.groupproj       # Project group completo
├── demo/
│   ├── ZV_DFeDemo.dpr                # Demonstrador CLI (offline + SOAP Mock)
│   ├── ZV_DFeDemo_VCL.dpr            # Aplicacao Desktop VCL interativa
│   └── seed_mock_server.py           # Mock SEFAZ SOAP 1.2 zero-dependencias
└── tests/
    └── ZV_DFe_Tests.dpr              # Suite automatizada Win32/Win64 (0 leaks)

---

Início Rápido (5 Linhas em Produção ou Homologação)


uses
  ZV.DFe.Types, ZV.DFe.Facade;

var
  Cfg: TZVSefazConfig;
  Mgr: TZVDFeManager;
  Doc: TZVNFeDocumento;
  Res: TZVSefazAutorizacaoResult;
begin
  Cfg := TZVSefazConfig.Create('MG', daHomologacao, dmNFe55);
  Cfg.CertPFXPath := 'C:\Certificados\empresa.pfx';
  Cfg.CertPFXPassword := 'SenhaDoCertificado';

  Mgr := TZVDFeManager.Create(Cfg);
  try
    Doc := TZVDFeManager.CreateSampleDocumento(dmNFe55, daHomologacao, 'MG');
    Res := Mgr.EmitirNFe(Doc, True);
    if Res.Autorizada then
      Memo1.Text := Mgr.GerarDanfeHtml(Doc, Res.Protocolo, Res.DataRecebimento);
  finally
    Mgr.Free;
  end;
end;

Guia de Instalação e Integração — ZaptVupt Delphi DFe SDK

1. Requisitos de Ambiente

  • IDE Embarcadero: Delphi 10.3 Rio ao 13.2 Florence (10.3 Rio, 10.4 Sydney, 11 Alexandria, 12 Athens, 13.2 Florence).
  • Plataformas Alvo: Windows 32 bits (Win32) e Windows 64 bits (Win64).
  • Sistema Operacional Runtime: Windows 10, Windows 11, Windows Server 2016/2019/2022/2025 com TLS 1.2/1.3 nativo habilitado no WinHTTP.
  • Dependências Externas: ZERO. Não requer distribuição de DLLs OpenSSL, XML ou motores externos junto ao seu executável. As únicas bibliotecas chamadas são DLLs nativas protegidas do sistema Windows (crypt32.dll, advapi32.dll, WinHTTP).

---

2. Configuração do Library Path (Sem precisar instalar componentes visuais)

Como todo o motor é orientado a classes, interfaces e records em código-fonte puro, a integração ao seu ERP leva menos de 2 minutos:

1. Extraia o pacote completo do SDK para uma pasta fixa do seu projeto, por exemplo:

C:\Libs\ZV_Delphi_DFe_NFe_SDK\

2. No Delphi IDE, abra Tools -> Options -> Language -> Delphi Options -> Library (ou adicione ao *Search Path* específico do .dproj do seu sistema).

3. Adicione os seguintes caminhos relativos ou absolutos:

  • $(ZV_DFE)\src\Source
  • $(ZV_DFE)\src\Vendor_ZVCore\src\Core
  • $(ZV_DFE)\src\Vendor_ZVCore\src\Http

4. Verifique se Namespace Prefixes contém System;Winapi;Vcl;Vcl.Imaging;System.Win.

---

3. Compilação via Linha de Comando (dcc32 / dcc64) & Testes

Para validar o SDK em sua estação antes de acoplar ao ERP:

Passo A — Iniciar o Mock SEFAZ Local (Opcional para testes HTTP)

Em um terminal Python 3 (sem instalar nenhuma biblioteca pip):


python demo\seed_mock_server.py --host 127.0.0.1 --port 18082

Passo B — Executar a Suite Unitária Completa


tests\ZV_DFe_Tests.exe http://127.0.0.1:18082

A saída esperada encerra com SUMMARY: XX passed, 0 failed e zero relatório de *Memory Leak* (ReportMemoryLeaksOnShutdown := True ativo).

Passo C — Executar o Demonstrador VCL

Abra demo\ZV_DFeDemo_VCL.dpr no Delphi e pressione F9. Utilize os botões à esquerda para gerar o XML assinado offline, consultar Status 107, autorizar NF-e 100 contra o Mock local, disparar Cancelamento 110111 e exportar a DANFE HTML com código de barras ITF-25 vetorial SVG.

---

4. Uso em Produção com Certificado Digital A1 ou A3

  • Certificado A1 (.PFX / .P12): Informe Cfg.CertPFXPath e Cfg.CertPFXPassword. O SDK importa o arquivo via PFXImportCertStore em armazenamento temporário em memória, assina os envelopes <infNFe> e <infEvento> e acopla o certificado cliente à sessão THTTPClient para mTLS na SEFAZ.
  • Certificado A3 (Token/Smartcard no Windows MY Store): Informe apenas Cfg.CertStoreThumbprint (os 40 hexadecimais do *Thumbprint SHA-1* do certificado instalado no usuário atual). O SDK localiza o certificado no store MY do Windows via CERT_FIND_SHA1_HASH sem expor a chave privada para fora do token criptográfico.

Referência de API — ZaptVupt Delphi DFe / NF-e 4.00 SDK

1. Tipos & Records (ZV.DFe.Types.pas)

Tipo / RecordDescrição
TZVDFeModeldmNFe55 (NF-e Modelo 55) ou dmNFCe65 (NFC-e Modelo 65).
TZVDFeAmbientedaProducao (1) ou daHomologacao (2).
TZVDFeRegimeTributariortSimplesNacional (CRT=1), rtSimplesExcesso (CRT=2), rtRegimeNormal (CRT=3).
TZVSefazConfigConfigura UF, Ambiente, Modelo, BaseUrlOverride (mock/proxy), CertPFXPath, CertPFXPassword, CertStoreThumbprint, TimeoutMs e MaxRetries.
TZVNFeDocumentoEstrutura completa do documento fiscal com Emitente, Destinatario, Itens, Pagamentos, ComputeTotais, AddItem e AddPagamento.
TZVDFeUFHelperConversão de sigla UF para código IBGE (GetCodigoIBGE), resolução do autorizador estadual (GetAutorizadorNFe) e enums XML.

---

2. Chave de Acesso & NFC-e (ZV.DFe.ChaveAcesso.pas)

  • TZVChaveAcessoHelper.CalcDVModulo11(ABase43: string): Integer

Calcula o dígito verificador oficial Módulo 11 (pesos cíclicos 2 a 9 da direita para esquerda).

  • TZVChaveAcessoHelper.BuildChave44(...)

Monta os 44 dígitos concatenando cUF + AAMM + CNPJEmitente + mod + serie + nNF + tpEmis + cNF + cDV.

  • TZVChaveAcessoHelper.ValidateChave44(AChave: string): Boolean

Valida tamanho exato e dígito verificador.

  • TZVChaveAcessoHelper.FormatChave44Display(AChave: string): string

Formata em 11 grupos de 4 dígitos separados por espaço para impressão no DANFE.

  • TZVChaveAcessoHelper.BuildNFCeQrCodeV2Url(...)

Gera a URL padrão QR Code v2 da NFC-e com assinatura HMAC/SHA-1 do CSC.

---

3. Construtor XML NF-e 4.00 & SOAP 1.2 (ZV.DFe.XmlBuilder.pas)

  • TZVDFeXmlBuilder.BuildNFeXml(var ADoc: TZVNFeDocumento): string

Gera o XML <NFe> na versão 4.00, populando automaticamente ADoc.ChaveAcesso44 e os totalizadores <ICMSTot>.

  • TZVDFeXmlBuilder.WrapSoap12StatusServico(...) / WrapSoap12Autorizacao(...) / WrapSoap12ConsultaProtocolo(...) / WrapSoap12RecepcaoEvento(...)

Empacotam os envelopes padrão SOAP 1.2 (http://www.w3.org/2003/05/soap-envelope) exigidos pelos Web Services NF-e 4.00 da SEFAZ.

  • TZVDFeXmlBuilder.BuildNFeProcXml(ASignedNFeXml, AProtNFeXml: string): string

Consolida o arquivo fiscal final <nfeProc versao="4.00"> após autorização cStat=100 ou 150.

---

4. Assinatura Digital XMLDSig (ZV.DFe.Signature.pas)

  • IZVDFeSigner: Interface de abstração criptográfica para permitir alternância transparente entre Certificado Real e Mock Determinístico em pipelines CI/CD.
  • TZVWinCryptoDFeSigner.CreateFromPFX(APfxPath, APfxPassword) / CreateFromWindowsStore(AThumbprint): Assinador RSA-SHA1 via Windows CryptoAPI nativo (crypt32.dll + advapi32.dll).
  • TZVDFeXmlSigner.SignXmlDocument(AXml, ATargetTag, AParentCloseTag, ASigner): Calcula SHA-1 Base64 de <infNFe> ou <infEvento>, constrói <SignedInfo>, assina e injeta <Signature> antes da tag de fechamento.
  • TZVDFeXmlSigner.VerifySignedXmlDigest(ASignedXml, ATargetTag): Boolean: Recalcula o resumo SHA-1 e compara com <DigestValue> para detectar qualquer adulteração pós-assinatura.

---

5. Cliente SOAP SEFAZ & DANFE (ZV.DFe.SefazClient.pas, ZV.DFe.DanfeRender.pas, ZV.DFe.Facade.pas)

  • TZVDFeManager.ConsultarStatus: Retorna TZVSefazStatusResult (CStat=107, TempoMedioSeg).
  • TZVDFeManager.EmitirNFe(Doc, True): Assina, transmite NFeAutorizacao4 e retorna TZVSefazAutorizacaoResult com Protocolo, NFeProcXml e Autorizada.
  • TZVDFeManager.ConsultarChave(Chave44): Consulta situação atual na SEFAZ.
  • TZVDFeManager.Cancelar(...) / CartaCorrecao(...): Gera e assina eventos 110111 e 110110 validando mínimo de 15 caracteres antes de chamar o web service.
  • TZVDFeManager.GerarDanfeHtml(...) / GerarNFCeCupomHtml(...): Produz HTML5 self-contained pronto para impressão A4/térmica 80mm ou conversão para PDF, incluindo código de barras ITF-25 SVG e QR Code SVG.

Matriz de Homologação e Cobertura — ZV-DELPHI-DFE-NFE-SDK

Versão: 1.0.0

Plataforma de Build Local (Gates): Delphi 12 Athens (Win32 e Win64) — Compatibilidade de Código-Fonte: Delphi 10.3 ao 13.2 (10.3 Rio a 13.2 Florence)

Última Verificação: 2026-11-15

Módulo / FuncionalidadeStatus AtualEvidência de Verificação
Cálculo e Validação Chave 44 Dígitos (Módulo 11)PRODUCTION_READY_VERIFIEDSuite ZV_DFe_Tests.dpr (Win32 & Win64, 0 failed)
Mapeamento 27 UFs IBGE + Autorizadores SEFAZ (AM/BA/GO/MG/MS/MT/PE/PR/RS/SP/SVRS/SVAN)PRODUCTION_READY_VERIFIEDUnit ZV.DFe.Types.pas + ZV.DFe.SefazClient.pas
Serialização XML NF-e 4.00 / NFC-e 65 (<infNFe>, <det>, <ICMSTot>, <pag>)PRODUCTION_READY_VERIFIEDSuite ZV_DFe_Tests.dpr verificando XML schema tags & totais
Assinatura Digital XMLDSig Enveloped (<SignedInfo>, <DigestValue>, <SignatureValue>)PRODUCTION_READY_VERIFIEDTZVWinCryptoDFeSigner (WinCrypto A1/A3) + TZVDeterministicTestSigner (CI)
Verificação Anti-Adulteração XML (VerifySignedXmlDigest)PRODUCTION_READY_VERIFIEDTeste negativo positivo para detecção de modificação pós-assinatura
NFeStatusServico4 (SOAP 1.2, cStat 107)MOCK_CONTRACT_VERIFIEDValidado em roundtrip HTTP SOAP contra seed_mock_server.py
NFeAutorizacao4 Síncrono + Consolidação <nfeProc> (cStat 100)MOCK_CONTRACT_VERIFIEDValidado em roundtrip HTTP SOAP + validação de protocolo
NFeConsultaProtocolo4 (cStat 100)MOCK_CONTRACT_VERIFIEDValidado em roundtrip HTTP SOAP
NFeRecepcaoEvento4 — Cancelamento 110111 & CC-e 110110 (cStat 135)MOCK_CONTRACT_VERIFIEDValidado em roundtrip HTTP SOAP + guarda >= 15 caracteres
DANFE NF-e Modelo 55 HTML + Código de Barras ITF-25 Vetorial SVGPRODUCTION_READY_VERIFIEDRenderização zero-dependências HTML + VCL TPaintBox Preview
Cupom NFC-e Modelo 65 (80mm) + QR Code v2 SHA-1 CSC + SVGPRODUCTION_READY_VERIFIEDDelphiZXIngQRCode + TZVChaveAcessoHelper.BuildNFCeQrCodeV2Url
Transmissão Direta com CNPJ Real em SEFAZ Homologação/ProduçãoCREDENTIALS_REQUIREDRequer Certificado ICP-Brasil A1/A3 ativo do contribuinte emissor

SBOM & Auditoria de Dependências (Clean-Room)

Produto: ZaptVupt Delphi DFe / NF-e 4.00 & NFC-e 65 SDK (ZV-DELPHI-DFE-NFE-SDK)

Modelo de Construção: Clean-Room RTL / WinAPI Nativo (Zero Dependências Comerciais ou DLLs Externas)

1. Inventário de Dependências

ComponenteOrigemLicençaJustificativa Técnica
Embarcadero RTL (System.SysUtils, System.Net.HttpClient, System.Hash, System.NetEncoding)IDE Delphi 10.3 ao 13.2Comercial Embarcadero (nativa do compilador)Transporte HTTP/TLS 1.2+, cálculo SHA-1, encoding Base64 e manipulação de strings/datas
Windows CryptoAPI (crypt32.dll, advapi32.dll)Sistema Operacional Windows (Nativo)Microsoft Windows OSImportação segura de certificados A1 (PFX) e assinatura RSA-SHA1 via tokens A3 sem redistribuíveis externos
Embarcadero VCL (Vcl.Graphics, Vcl.Controls, Vcl.StdCtrls, Vcl.ExtCtrls)IDE Delphi VCLComercial EmbarcaderoRenderização de pré-visualização DANFE no demo Desktop VCL (opcional para projetos Console/Serviço/DataSnap)
DelphiZXIngQRCode.pas (em Vendor_ZVCore)Porto Pascal puro ZXingApache License 2.0Geração matemática de matriz QR Code para NFC-e v2 sem uso de DLL ou internet

---

2. Ausência Total de Pacotes Terceiros ou Redistribuíveis (external_dlls_required: [])

  • Nenhuma DLL extra precisa ser empacotada no instalador do cliente final.
  • Zero dependências visuais comerciais obrigatórias.
  • 100% código-fonte Object Pascal compilável diretamente em aplicações Win32 e Win64.

Histórico de Versões (CHANGELOG)

v1.0.0 — 2026-11-15

  • Lançamento inicial Clean-Room do ZaptVupt Delphi DFe / NF-e 4.00 & NFC-e 65 SDK.
  • Implementação da engine completa de Chave de Acesso 44 dígitos (Módulo 11) e QR Code v2 NFC-e.
  • Serializador XML Layout NF-e 4.00 / NFC-e 65 + construtor de envelopes SOAP 1.2 SEFAZ.
  • Assinador digital XMLDSig nativo Windows CryptoAPI (crypt32.dll / advapi32.dll) para certificados A1 (PFX) e A3 (Windows Store) + assinador determinístico isolado para testes em CI.
  • Cliente SOAP SEFAZ (NFeStatusServico4, NFeAutorizacao4, NFeConsultaProtocolo4, NFeRecepcaoEvento4 — Cancelamento 110111 e CC-e 110110) com mapeamento de todas as 27 UFs e autorizadores (SVRS, SVAN, próprios).
  • Renderizador Clean-Room de DANFE A4 HTML + código de barras ITF-25 vetorial SVG, Cupom NFC-e 80mm e Canvas VCL Preview.
  • Suite de testes Win32 e Win64 verificada com zero memory leaks e Mock Server SEFAZ SOAP 1.2 em Python stdlib.