README

DFe Broker

⚠️ Estado (setembro/2026): funciona de ponta a ponta contra um simulador da SEFAZ, mas nunca foi executado contra a SEFAZ real — o autor não tem certificado digital ICP-Brasil. Testado em Delphi (Win32/Win64) e FPC (Windows e Linux/Docker); o host console sobe e para limpo nos dois compiladores. Não use em produção sem validar com o seu certificado (em homologação primeiro) e, se puder, conte o que encontrou. As decisões de projeto estão registradas em docs/architecture.md.

Consulta a Distribuição de DFe da SEFAZ (NFe na v1; CTe e MDFe planejados) e publica cada documento e evento como uma mensagem numa fila AMQP. Qualquer sistema — Delphi, Python, Node, PHP, Java, C# — consome com um cliente AMQP comum, sem saber nada de SEFAZ, certificado ou ACBr. Auto-hospedado, open source (MIT), sem exigir infraestrutura de mensageria externa.

   SEFAZ ??????(certificado, NSU, 1 consulta/hora)?????????  DFe Broker  ?????????  broker AMQP embutido  ?????????  seus sistemas
                                                   (cursor, ACBr,      exchange "dfe"           (qualquer linguagem)
                                                    manifesta????o)      nfe.documento.rs.<cnpj>
                                                                       nfe.evento.cancelamento.rs.<cnpj>

O que um consumidor recebe (saída real do exemplo em Python, com dados sintéticos):

novo      nfe.documento.rs.11222333000181  cnpj=11222333000181 uf=rs
          resNFe  chave=35260998765432000110550010000000011000079198
          xNome=EMITENTE SINTETICO LTDA, dhEmi=2026-09-10T14:30:05-03:00, vNF=150.00
novo      nfe.evento.cancelamento.rs.11222333000181  cnpj=11222333000181 uf=rs
          resEvento  chave=35260998765432000110550010000000031000237570  tpEvento=110111

E o mesmo consumidor em Delphi (VCL, com o cliente AMQP do pascal-amqp-faa), recebendo os documentos e mandando uma ciência da operação — o resultado volta como o evento da última linha:

O fonte é o mesmo para Delphi e Lazarus: exemplos/consumidor.

Veja funcionando, sem certificado

Sem compilar nada (Windows x64): baixe o pacote da release v0.2.1 — traz os executáveis, o simulador, as DLLs, um certificado de teste e um LEIAME.md de 6 passos.

O projeto inclui um simulador da SEFAZ. O docs/guia-de-uso.md leva você, passo a passo, de "acabei de compilar" a ver documentos chegando numa fila, reproduzir o bloqueio de consumo indevido (656) em segundos e mandar uma manifestação do destinatário; a configuração da demo está em exemplos/demo-simulador/. Não conhece o vocabulário (NSU, cStat, resNFe…)? O guia tem um glossário, e há um FAQ.

Por quê

Automatizar a consulta de documentos fiscais que envolvem sua empresa (Distribuição de DFe) hoje significa, na prática, escolher entre pagar por um SaaS fechado ou implementar o fluxo inteiro (NSU, certificado, XML, manifestação) na unha dentro do próprio ERP. O DFe Broker propõe uma terceira via: uma ferramenta open source e auto-hospedada, que qualquer empresa ou dev roda com o próprio certificado digital, entregando os documentos como mensagens numa fila — para que qualquer sistema consuma via um cliente AMQP padrão, sem nenhum acoplamento com Object Pascal.

O que ele faz

• Poller por certificado — consulta periodicamente a Distribuição de DFe, respeitando o intervalo mínimo da SEFAZ (1 h), e mantém o cursor de NSU persistido com escrita atômica: é o ponto de maior risco (um cursor corrompido significa documento perdido ou reconsultado para sempre). O cursor só avança depois que o lote inteiro foi publicado e confirmado pelo broker — entrega pelo menos uma vez, então deduplique pela chave de acesso.
• Broker AMQP 0-9-1 embutido — do pascal-amqp-faa, dentro do próprio processo, durável por padrão. Não exige RabbitMQ, mas fala o protocolo padrão: dá para apontar para um externo.
• Contrato público de routing-key — exchange dfe (topic), routing-key <tipo>.<categoria>.<uf>.<cnpj>. Quem só quer cancelamentos assina nfe.evento.cancelamento.#. Consumidores de exemplo (Python e uma tela Delphi/Lazarus) em exemplos/consumidor/.
• Manifestação do destinatário — ciência, confirmação, desconhecimento e operação não realizada, por um comando na fila; o resultado (ou a rejeição da SEFAZ) volta como evento. Há modo automático por certificado, desligado por padrão (é um ato fiscal).
• Vários certificados (inclusive troca antes do vencimento) e recarga a quente do arquivo de configuração.
• Providers por tipo de documento — NFe na v1; CTe e MDFe entram sem tocar no core (ver CONTRIBUTING.md).
• Formas de rodar — console (Windows e Linux; sob systemd em produção no Linux) e Serviço Windows (Delphi).
• Simulador da SEFAZ — servidor HTTP com API de administração, relógio virtual, injeção de falhas e extensão em Pascal; serve também como ferramenta independente (simulador/LEIAME.md).
• Integração fiscal via ACBr — os componentes do projeto ACBr cuidam da comunicação com a SEFAZ, do certificado e do XML.

Detalhes de design — convenção de exchange/routing-key, contrato de provider, persistência do cursor, modelo de execução — estão em docs/architecture.md.

Nota técnica: os web services da SEFAZ exigem certificado digital ICP-Brasil real mesmo em homologação. Por isso, só o adaptador que fala com a SEFAZ depende de certificado; o restante é testado contra o simulador da SEFAZ do projeto, com o componente ACBr real, e a suíte automatizada não precisa de certificado nenhum. A fidelidade do simulador é a leitura que o projeto faz das Notas Técnicas — validar com um certificado real é exatamente o que falta (issue #1).

Compiladores suportados

Delphi e FPC/Lazarus, desde o início — mesmo padrão dual-compiler do pascal-amqp-faa. Onde o suporte do ACBr a Lazarus for uma limitação real, o limite fica documentado explicitamente.

Como compilar e rodar

Depende de submódulos em vendor/: o broker pascal-amqp-faa (~4 MB) e a pascal-common-faa que ele usa (o projeto fornece a cópia dela, como manda a regra de uma cópia por aplicação) e, só para o simulador, o Horse. O ACBr não é submódulo: tools/obter-acbr.sh baixa do SVN oficial do Projeto ACBr, numa revisão fixa, só as pastas que o projeto usa (~65 MB); precisa do cliente svn ou do Docker.

Windows: clone num caminho curto (ex.: C:\dev\). O ACBr tem pastas profundas, e um caminho longo pode estourar o limite de tamanho de caminho do Windows.

Estes comandos foram executados num clone limpo e funcionam (Git Bash no Windows, ou shell Linux):

git clone https://github.com/fabianoallex/pascal-dfe-broker
cd pascal-dfe-broker
git submodule update --init vendor/pascal-amqp-faa vendor/pascal-common-faa
sh tools/obter-acbr.sh                                           # ~2 min na 1a vez (svn ou Docker)

Broker (host console) com FPC/Lazarus:

lazbuild --add-package-link packages/pascal_dfe_broker.lpk       # uma vez por m??quina; sem isso: "Broken dependency"
lazbuild hosts/console/DFeBrokerConsole.lpi

Simulador da SEFAZ (para a demo e para testes):

git submodule update --init vendor/horse
lazbuild simulador/DFeSimulador.lpi

Delphi: abra PascalDfeBroker.groupproj e compile DFeBrokerConsole (Win64) e, se quiser, DFeSimulador.

Executar: DFeBrokerConsole --config dfe.ini (modelo comentado em hosts/console/dfe.exemplo.ini).

Dependências de execução — não vêm no repositório: OpenSSL 3 (libssl + libcrypto), libxml2 e os XSDs da NFe (estes vêm com o ACBr, pelo tools/obter-acbr.sh). Faltar algo só aparece em execução, por isso existe DFeBrokerConsole --config dfe.ini --verificar-ambiente: confere tudo e diz o que falta e como obter (docs/dependencias-runtime.md).

Mais: demo sintética tools/demo/DFeDemo · Serviço Windows em hosts/servico/LEIAME.md · Linux/systemd em docs/linux.md · testes em docs/testes.md.

Notas Técnicas de referência

Este projeto segue as seguintes versões das Notas Técnicas oficiais (cópias e citações literais em docs/referencias/):

Se a versão vigente no Portal Nacional da NF-e for mais recente que a listada aqui, esta tabela e docs/referencias/ estão desatualizados — trate como um bug e abra uma issue.

Antes de usar com o certificado de uma empresa

• Outro sistema já consulta a Distribuição de DFe desse CNPJ? (ERP, contador, outro serviço.) A NT 2014.002 (seção 3.11.4, p. 14) diz que aplicações diferentes consultando o mesmo CNPJ devem seguir a mesma sequência de NSU, senão a consulta vira uso indevido e o CNPJ (não o certificado) fica bloqueado por 1 hora — para todos que consultam. O bloqueio é automático e temporário, mas pode derrubar o sistema de quem já usa. Combine antes; em dúvida, use homologação ou um CNPJ que ninguém consulta.
• Manifestação do destinatário é um ato fiscal: registra evento na NF-e da empresa (ciência, confirmação, desconhecimento, operação não realizada). O padrão é ManifestacaoAutomatica=false; não a use em produção sem o aval de quem responde pelo fiscal.
• O certificado é a identidade digital (e assinatura com valor legal) da empresa: tenha autorização para usá-lo, guarde o .pfx e a senha como segredo (SenhaEnv, nunca no repositório) e leia a política interna.

Documentação

Licença

Este projeto é licenciado sob MIT. Os componentes ACBr usados como dependência são licenciados sob LGPLv3 — a integração é feita preservando a separação de licenciamento (o projeto não incorpora código-fonte ACBr sob a licença MIT deste repositório).

Contribuindo

Contribuições são muito bem-vindas, especialmente de devs brasileiros com experiência em SEFAZ, ACBr, AMQP ou Lazarus/FPC. A ajuda mais valiosa hoje é validar em homologação com um certificado real (issue #1). Dúvidas e ideias: Discussions; há issues abertas para quem quer começar. Antes de abrir um PR que adicione um novo tipo de documento (CTe, MDFe etc.), leia CONTRIBUTING.md — a uniformidade entre providers é um requisito do projeto, não um detalhe de estilo.