Gerador de DF-e Mockados (2026)

Projeto de geração de documentos fiscais eletrônicos mockados para testes de importação, indexação, busca, compatibilidade de parsers e validação funcional de sistemas que processam DF-e. O foco é produzir arquivos coerentes e realistas para desenvolvimento e QA, sem pretensão de autorização fiscal real.

Trata-se de uma aplicação CLI desenhada para gerar documentos mais completos e densos, tomando como referência XMLs reais e usando as bibliotecas AutoBogus + Bogus para geração dos diversos dados sintéticos que compõem os documentos: nomes, endereços, itens, contatos, descrições e valores.

Objetivo

O projeto existe para testar sistemas que:

• importam XMLs fiscais (DF-e);
• extraem participantes e metadados para banco relacional;
• indexam documentos para busca por múltiplas características;
• precisam validar suporte a CNPJ alfanumérico em todos os campos relevantes;
• precisam validar coexistência entre identificadores numéricos e alfanuméricos;
• precisam testar cenários de colisão e repetição controlada de participantes.

Modelos suportados

O gerador cobre NF-e (modelo 55), NFC-e (modelo 65), CT-e (modelo 57) e NFS-e no padrão nacional unificado.

NF-e modelo 55

Usada para mockar operações com destinatário pessoa jurídica, concentrando os cenários com maior variedade de campos de CNPJ. Os documentos gerados incluem os seguintes blocos:

• ide, emit, dest;
• múltiplos det com produto e imposto;
• total/ICMSTot;
• transp/transporta/vol;
• retirada, entrega, autXML;
• pag/detPag/card;
• infAdic e infRespTec.

Campos de participante contemplados: emit, dest, retirada, entrega, autxml, transporta e pag.

NFC-e modelo 65

Os mocks de NFC-e simulam venda a consumidor final, usando destinatário por CPF em vez de CNPJ. Os documentos gerados contemplam:

• ide com mod=65, tpImp=4, indFinal=1, indPres=1;
• emit com CNPJ e dest com CPF (consumidor final pessoa física);
• múltiplos itens em det;
• total, transp, pag;
• infAdic, infRespTec e infNFeSupl/qrCode.

Para vendas a pessoa jurídica, a estratégia do projeto é manter os mocks em NF-e modelo 55.

CT-e modelo 57

Os mocks de CT-e testam busca relacional e identificação de participantes logísticos e fiscais em múltiplos papéis. Os documentos gerados contemplam:

• ide completo com municípios inicial/final, modal e tipo de serviço;
• compl com observações operacionais;
• participantes emit, rem, exped, receb, dest, toma4;
• vPrest, imp, infCTeNorm, infCarga, infDoc, infModal;
• autXML, infRespTec e infCTeSupl.

NFS-e padrão nacional unificado

Os mocks de NFS-e refletem o padrão nacional unificado vigente desde 1º de janeiro de 2026, com estrutura baseada no novo fluxo centrado na DPS e nos grupos associados a IBS/CBS. Os documentos gerados incluem:

• infNFSe, emit, valores;
• DPS/infDPS;
• prest, toma, interm;
• serv, IBSCBS, dest;
• blocos de localidade, competência e valores tributários.

O grupo adq foi removido nessa revisão de layout, mantendo a identificação principal do tomador em toma.

CNPJ alfanumérico

O gerador foi desenhado para apoiar testes com CNPJ alfanumérico, cujo uso pela Receita Federal está previsto para novas inscrições a partir de julho de 2026, coexistindo com os CNPJs numéricos já existentes.

O projeto contempla:

• geração de CNPJ numérico e alfanumérico;
• cálculo de DV para CNPJ alfanumérico;
• geração de chaves de documentos compatíveis com caracteres alfanuméricos no trecho do CNPJ;
• mistura de CNPJs numéricos e alfanuméricos no mesmo lote.

Para testes adicionais ou comparação com identificadores fictícios oficiais, a Receita Federal disponibiliza o Simulador Nacional de CNPJ, próprio para desenvolvimento e validação de sistemas.

Massa orientada a busca relacional

O gerador não produz apenas XMLs isolados: ele monta massas com comportamento útil para persistência relacional e busca multiatributo.

Características implementadas:

• repetição de participantes entre documentos diferentes;
• repetição do mesmo identificador em papéis diferentes dentro do mesmo documento;
• reaproveitamento de pools de CNPJ;
• geração de índices auxiliares em CSV e JSON;
• cenários adequados para testes de JOIN, GROUP BY, filtros compostos e deduplicação.

Essa abordagem valida comportamentos como busca por qualquer participante do documento, busca por papel específico, contagem de documentos distintos versus ocorrências de participante, indexação textual e relacional, e prevenção de falso positivo em consultas com participantes repetidos.

Colisões controladas

O projeto inclui cenários de colisão proposital para exercitar consultas e regras de negócio mais sensíveis:

• mesmo CNPJ em dois papéis diferentes do mesmo documento;
• mesmo CNPJ repetido em vários documentos do mesmo modelo;
• coexistência de um participante comum em modelos distintos;
• casos mistos com identificadores numéricos e alfanuméricos.

Esses casos ajudam a validar deduplicação por documento e por participante, ranking de relevância em busca, agrupamentos por papel e por documento, e regras que não podem assumir unicidade indevida por CNPJ.

Artefatos gerados

Uma execução típica do gerador produzirá:

• xml/ com os documentos mockados;
• json/ com espelho estruturado de cada XML;
• indice.csv e indice.json com visão tabular por documento;
• matriz-casos.csv e matriz-casos.json com granularidade por participante/papel;
• config-utilizada.json com os parâmetros efetivos da geração.

Estrutura do projeto

DfeMockGenerator/
  README.md
  DfeMockGenerator.sln
  DfeMockGenerator/
    DfeMockGenerator.csproj
    Program.cs
    Application/
      Configuration/
        GeneratorConfig.cs
      Interfaces/
        IChecksumCalculator.cs
        IDocumentBuilder.cs
        IDocumentKeyFactory.cs
        IOutputWriter.cs
        IPartyFactory.cs
    Domain/
      Constants/
        FiscalCodes.cs
        MunicipalityPool.cs
        TaxRates.cs
      Entities/
        Item.cs
        MockDoc.cs
        Party.cs
      Enums/
        DocumentModel.cs
    Infrastructure/
      Builders/
        CteBuilder.cs
        NfceBuilder.cs
        NfeBuilder.cs
        NfseBuilder.cs
        Shared/
          XmlAddressHelper.cs
          XmlDetItemHelper.cs
          XmlPartyHelper.cs
          XmlRespTecHelper.cs
          XmlTaxTotalHelper.cs
          XmlUtils.cs
      Factories/
        DocumentKeyFactory.cs
        ItemFactory.cs
        PartyFactory.cs
      IO/
        OutputWriter.cs
      Orchestration/
        GeneratorOrchestrator.cs
      Validation/
        ChecksumCalculator.cs
    Presentation/
      Cli/
        CliParser.cs
exemplo-lote-gerado/
  xml/
  json/
  indice.csv
  indice.json
  matriz-casos.csv
  matriz-casos.json
  config-utilizada.json

Dependências

O projeto utiliza as bibliotecas:

• Bogus — geração de dados sintéticos (nomes, endereços, produtos, textos);
• AutoBogus — complemento do Bogus para popularização automática de objetos C#.

Execução local

dotnet run --project DfeMockGenerator.csproj -- `
  --output saida-lote `
  --quantidade 100 `
  --modelos nfe,nfce,cte,nfse `
  --serie 9000 `
  --percent-num 35 `
  --reuse-cnpjs `
  --reuse-pool 12 `
  --emit-cnpjs 12ABC34501DE35,00000000000191 `
  --min-itens 1 `
  --max-itens 6 `
  --seed 123

Parâmetros suportados

Parâmetro	Descrição
--output	Diretório de saída
--quantidade	Quantidade total de documentos a gerar
--modelos	Lista de modelos a gerar (nfe, nfce, cte, nfse)
--serie	Série usada nos documentos compatíveis
--percent-num	Percentual de identificadores puramente numéricos no lote
--reuse-cnpjs	Ativa reaproveitamento de pool de CNPJs
--reuse-pool	Tamanho do pool reutilizável
--emit-cnpjs	Lista de CNPJs (separados por vírgula, apenas dígitos ou alfanuméricos, sem pontuação) usados como pool exclusivo de emitentes dos documentos. CNPJs inválidos são descartados com aviso no stderr; se o pool resultar vazio, o emitente volta a seguir --reuse-cnpjs ou a geração dinâmica.
--min-itens	Quantidade mínima de itens por documento
--max-itens	Quantidade máxima de itens por documento
--seed	Semente para reprodutibilidade

Limites e premissas

Este gerador foi construído para mock, QA e desenvolvimento, não para emissão real nem para homologação autorizadora.

• Os XMLs são estruturados para teste funcional, e tentam manter o máximo de conformidade com todos os schemas da pasta DfeXmlSchemas.
• Não existem regras dinâmicas de autorização implementadas.
• Os campos de assinatura digital e protocolos reais não são reproduzidos.
• A NFS-e nacional está em fase de evolução documental e normativa; os mocks refletem a linha estrutural já consolidada, sem pretensão de cobertura exaustiva.
• A NFC-e é deliberadamente restrita a consumidor final pessoa física; cenários com destinatário pessoa jurídica deverão ser exercitados via NF-e.

Casos de uso recomendados

O projeto é adequado para testar:

• importação e leitura de XML fiscal;
• extração de participantes para tabelas relacionais;
• busca por CNPJ/CPF em múltiplos campos;
• suporte a CNPJ alfanumérico;
• montagem de índices invertidos e consultas full-text;
• cenários de colisão, repetição e deduplicação;
• compatibilidade entre documentos de modelos distintos.

Para quem estiver adaptando sistemas ao CNPJ alfanumérico, a Receita Federal mantém orientação pública e simulador oficial de inscrições fictícias, o que complementa bem o uso deste gerador nos testes internos.