HelpDanfe 1.0.2

📄 HelpDanfe

HelpDanfe é uma biblioteca .NET leve, moderna e de alto desempenho para leitura e extração de dados de Documentos Auxiliares da Nota Fiscal Eletrônica (DANFE). HelpDanfe é uma biblioteca .NET leve, moderna e de alto desempenho para leitura e extração de dados de Documentos Auxiliares da Nota Fiscal Eletrônica (DANFE).

Projetada com foco no Princípio da Responsabilidade Única (SRP) e Clean Code, a biblioteca é ideal para integração com ERPs, automação de processos fiscais e auditorias de notas de entrada.

🚀 Principais Recursos

• Dupla Leitura Unificada: Extraia dados tanto de arquivos PDF quanto de arquivos XML utilizando a mesma interface simples.
• Mapeamento Inteligente: Captura de Chave de Acesso (44 dígitos), Protocolo de Autorização, CNPJ/CPF, Razão Social e Endereços completos do Emitente e Destinatário.
• Detalhamento Fiscal: Extração de valores financeiros e tributários (Bases de cálculo ICMS/ICMS-ST, valores totais, IPI, frete, seguros, descontos e outras despesas).
• Itens e Produtos: Mapeamento em lista de todos os produtos ou serviços da nota (Código, Descrição, NCM, Quantidade, Valor Unitário e Valor Total).
• Alta Performance (Source Generators): Utilização das mais recentes APIs do .NET ([GeneratedRegex]) para processamento em tempo de compilação, reduzindo alocação de memória.
• Arquitetura Desacoplada: Separação clara entre serviços de extração, mappers específicos e utilitários de conversão, garantindo máxima performance e facilidade de testes unitários.

🏗️ Estrutura e Arquitetura do Projeto

O projeto é modularizado por responsabilidades de domínio, evitando o acoplamento de classes e facilitando a manutenção e expansão:

HelpDanfe
├── 📁 Enums
│   └── FileTypes.cs                  # Definições de tipos de arquivos suportados (PDF/XML)
├── 📁 Error
│   ├── Error.cs                      # Modelo padrão de resposta de erros
│   └── FileErrors.cs                 # Erros específicos de processamento e validação de arquivos
├── 📁 Interface
│   └── 📁 Services
│       └── IExtratorService.cs       # Contrato principal para extração de dados de NFe
├── 📁 Invoices
│   ├── 📁 Company
│   │   ├── RecipientCompanyEntity.cs # Entidade de representação do Destinatário
│   │   └── SendingCompanyEntity.cs   # Entidade de representação do Emitente
│   ├── 📁 Danfe
│   │   └── DanfeEntity.cs            # Entidade raiz agregadora dos dados da nota
│   ├── 📁 Services
│   │   └── ServicesOrProducts.cs     # Entidade para os itens (Produtos/Serviços) da nota
│   └── 📁 Tax
│       └── TaxCalculationEntity.cs   # Entidade com os totais de impostos e bases de cálculo
├── 📁 Mappers
│   ├── DanfePdfMapper.cs             # Mapeamento e extração via Regex a partir de arquivos PDF
│   └── DanfeXmlMapper.cs             # Mapeamento via navegação em nós de arquivos XML do SEFAZ
├── 📁 Request
│   └── FileImportRequest.cs          # Modelo de entrada para requisição de leitura de arquivo
├── 📁 Services
│   └── ExtratorService.cs            # Implementação da orquestração de extração
└── 📁 Utils
    └── Utils.cs                      # Utilitários gerais (parsers decimais, limpezas de strings)

🔍 Mapeamento por Expressões Regulares (Regex)

Para a leitura eficiente de arquivos PDF via DanfePdfMapper, o HelpDanfe utiliza o recurso de Source Generators ([GeneratedRegex]), que otimiza as expressões regulares no momento da compilação.

Abaixo estão documentadas todas as expressões utilizadas pela biblioteca e seus respectivos objetivos na raspagem do texto da DANFE:

Nota: As expressões que dependem do texto em português usam explicitamente a culture "pt-BR" e RegexOptions.IgnoreCase para garantir maior tolerância a variações de escaneamento, pontuação e fontes dos geradores de PDF.

📦 Instalação

Instale o pacote diretamente através do NuGet Package Manager ou pelo .NET CLI:

.NET CLI:

dotnet add package HelpDanfe

Package Manager Console:

Install-Package HelpDanfe

💡 Como Usar

Exemplo Básico via Injeção de Dependência

using HelpDanfe.Interface.Services;
using HelpDanfe.Enums;

public class ImportacaoNotaService
{
    private readonly IExtratorService _extratorService;

    public ImportacaoNotaService(IExtratorService extratorService)
    {
        _extratorService = extratorService;
    }

    public async Task ProcessarArquivoAsync(Stream arquivoStream, FileTypes tipoArquivo)
    {
        // A mesma interface processa tanto XML quanto PDF de acordo com o enum passado
        var danfe = await _extratorService.ExtrairDadosAsync(arquivoStream, tipoArquivo);

        if (danfe != null)
        {
            Console.WriteLine($"Nota Nº: {danfe.Numero} - Série: {danfe.Serie}");
            Console.WriteLine($"Chave: {danfe.ChaveAcesso}");
            Console.WriteLine($"Emitente: {danfe.Emitente.RazaoSocial}");
            Console.WriteLine($"Total da Nota: {danfe.Impostos.ValorTotalNota:C}");
        }
    }
}

🤝 Contribuindo

Contribuições são sempre bem-vindas! Sinta-se à vontade para abrir uma Issue com relatórios de bugs, solicitações de funcionalidades ou enviar um Pull Request para melhorar os parsers ou documentação.

📝 Licença

Distribuído sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.