BrasilNFe 3.0.0

Brasil NFe SDK (.NET)

SDK oficial em C# / .NET para integração com a API da Brasil NFe. Permite emitir, consultar, cancelar e gerenciar documentos fiscais eletrônicos (NF-e, NFC-e, CT-e, MDF-e, NFS-e, DC-e, NF3-e) e arquivos fiscais (SPED, Sintegra, FCI), de forma orientada a objetos com tipagem forte e serialização automática.

Equivalente em .NET aos pacotes brasilnfe (Node.js) e brasilnfe/brasilnfe-php-sdk (PHP).

Novidades na v3.0

• Compatível com .NET moderno - mira netstandard2.0, então roda em .NET Framework 4.6.1+, .NET Core 2.0+ e .NET 5/6/7/8/9/10. Quem está em net48 continua usando exatamente como antes; quem está em .NET 10 agora consegue instalar sem fricção.
• API assíncrona completa - todos os ~30 métodos públicos passaram a ter overload *Async com suporte a CancellationToken. Os métodos síncronos continuam disponíveis com a mesma assinatura.
• HTTP modernizado - a camada de requisição usa HttpClient (estático, reutilizado) em vez de HttpWebRequest. Mesmos headers, mesmo timeout (300s), mesmo comportamento observável.
• Desserialização unificada - tanto a serialização quanto a desserialização agora usam Newtonsoft.Json (antes a leitura era com JavaScriptSerializer).

Índice

• Novidades na v3.0
• Sobre a Brasil NFe
• Recursos
• Requisitos
• Instalação
• Configuração Inicial
• Uso síncrono e assíncrono
• Arquitetura do SDK
• Guia Rápido
• Exemplos
  • 1. Emitir NF-e (modelo 55)
  • 2. Emitir NFC-e (modelo 65)
  • 3. Emitir NF-e em lote
  • 4. Emitir NFS-e
  • 5. Emitir CT-e
  • 6. Emitir DC-e (Declaração de Conteúdo)
  • 7. Cancelar NF-e
  • 8. Carta de Correção (CC-e)
  • 9. Inutilizar numeração
  • 10. Manifestar NF-e de entrada
  • 11. Consultar status da SEFAZ
  • 12. Buscar notas por período
  • 13. Baixar XML / DANFE
  • 14. Gerar SPED e Sintegra
  • 15. Gestão de empresas e certificados
• Referência de Métodos
• Tratamento de Erros
• Tabelas de Referência
• Ambientes
• Como o SDK serializa o payload
• Utilitário BrasilNFeHelper
• Licença
• Suporte

Sobre a Brasil NFe

A Brasil NFe oferece uma API REST para emissão de notas fiscais e documentos eletrônicos, com foco em estabilidade, performance e conformidade com a legislação brasileira.

• Site oficial: https://www.brasilnfe.com.br
• Documentação da API: https://www.brasilnfe.com.br/docs

Recursos

O SDK cobre todos os módulos da API REST da Brasil NFe:

• Emissão de documentos fiscais

  • NF-e (modelo 55)
  • NFC-e (modelo 65)
  • NFS-e (nota fiscal de serviço)
  • CT-e (modelo 57)
  • MDF-e (modelo 58)
  • DC-e (Declaração de Conteúdo)
  • NF3-e / NF-e de Energia (NFEnerCom)
  • Nota Fiscal Complementar
  • Envio em lote

• Eventos

  • Cancelamento
  • Carta de Correção (CC-e)
  • Inutilização de numeração
  • Manifestação do Destinatário
  • Encerramento de MDF-e

• Consultas

  • Status SEFAZ
  • Consulta de Cadastro (IE/CNPJ)
  • Busca de notas por período
  • Pré-visualização de DANFE
  • Cálculo de impostos

• Arquivos fiscais

  • Download de XML e DANFE (byte[])
  • SPED Fiscal e Contribuições (individual e unificado)
  • Sintegra
  • FCI (Ficha de Conteúdo de Importação)
  • Arquivos por range de chaves

• Gestão

  • Cadastro e edição de empresas
  • Envio e verificação de certificados digitais A1

Requisitos

Qualquer runtime compatível com .NET Standard 2.0:

• .NET Framework 4.6.1+ (testado em 4.8)
• .NET / .NET Core 2.0+, incluindo .NET 5, 6, 7, 8, 9 e 10
• Mono 5.4+, Xamarin (versões modernas), Unity

Dependências:

• Newtonsoft.Json 13.0.3
• System.ComponentModel.Annotations 5.0.0
• Token de acesso válido do painel Brasil NFe

Instalação

Via .NET CLI (recomendado):

dotnet add package BrasilNFe

Via Package Manager Console:

Install-Package BrasilNFe

Via <PackageReference> no csproj SDK-style:

<PackageReference Include="BrasilNFe" Version="3.0.0" />

Via packages.config (projetos legados):

<package id="BrasilNFe" version="3.0.0" targetFramework="net48" />

Configuração Inicial

A classe principal é BrasilNFe. Com um Token você já tem acesso a todos os módulos fiscais. O UserToken é opcional e só é necessário para o módulo de gestão de empresas/certificados.

using BrasilNFePack;

var token     = "SEU_TOKEN_AQUI";   // Token da empresa (obrigatório)
var userToken = "SEU_USER_TOKEN";   // Token do usuário (opcional, p/ Empresa)

var bnfe = new BrasilNFe(token, userToken);

// Por padrão o SDK aponta para https://api.brasilnfe.com.br/services/
// Para sobrescrever (ex.: ambiente interno / sandbox específico):
var bnfeCustom = new BrasilNFe(token, userToken, "https://api.brasilnfe.com.br/services/");

A definição de produção x homologação não é feita pela URL: é controlada pelo campo TipoAmbiente (1 = Produção, 2 = Homologação) de cada requisição.

Uso síncrono e assíncrono

A partir da v3.0, todos os métodos públicos têm overload assíncrono com o sufixo Async e suporte a CancellationToken. A versão síncrona continua disponível com a mesma assinatura - escolha o estilo que combina com a sua aplicação.

// Sincrono (igual a v2.x - continua funcionando exatamente como antes)
var resp = bnfe.NotaFiscal.EnviarNotaFiscal(nf);

// Assíncrono (recomendado para ASP.NET Core, .NET 6+, apps com I/O intenso)
var resp = await bnfe.NotaFiscal.EnviarNotaFiscalAsync(nf);

// Com cancelamento (timeout, request abortada, etc.)
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
var resp = await bnfe.NotaFiscal.EnviarNotaFiscalAsync(nf, cancellationToken: cts.Token);

Os exemplos abaixo seguem o estilo síncrono para manter compatibilidade visual com a v2.x, mas qualquer chamada pode ser convertida adicionando Async ao nome do método e await antes da chamada.

Arquitetura do SDK

A instância BrasilNFe agrega cinco módulos públicos:

Estrutura de diretórios:

BrasilNFePack/
├── BrasilNFe.cs            # Classe agregadora e BrasilNFeHelper
├── BrasilNFeRequest.cs     # Camada HTTP (HttpClient async/sync) + headers
├── Methods/                # Módulos de alto nível
│   ├── NotaFiscal.cs
│   ├── Eventos.cs
│   ├── Consultas.cs
│   ├── Arquivos.cs
│   └── Empresa.cs
└── Models/                 # POCOs de envio e retorno
    ├── NotaFiscal/
    ├── Eventos/
    ├── Consultas/
    ├── Empresa/
    ├── Arquivos/
    └── Outros/

Guia Rápido

using BrasilNFePack;
using BrasilNFePack.Envio;

var bnfe = new BrasilNFe("SEU_TOKEN");

var req = new StatusSefazEnvio
{
    ModeloDocumento = 55,
    TipoAmbiente    = 2, // homologação
};

var resp = bnfe.Consultas.StatusSefaz(req);
Console.WriteLine(resp.StatusSefaz?.DsStatusRespostaSefaz ?? "indisponível");

Exemplos

1. Emitir NF-e (modelo 55)

using BrasilNFePack;
using BrasilNFePack.Envio;
using System.Collections.Generic;

var bnfe = new BrasilNFe("SEU_TOKEN");

var nf = new NotaFiscalEnvio
{
    TipoAmbiente     = 2,                        // 1 = Produção, 2 = Homologação
    ModeloDocumento  = 55,                       // NF-e
    Finalidade       = 1,                        // Normal
    NaturezaOperacao = "VENDA DE MERCADORIA",
    IndicadorPresenca = 1,
    ConsumidorFinal  = false,
    EnviarEmail      = true,

    Cliente = new Pessoa
    {
        CpfCnpj    = "00000000000191",
        NmCliente  = "EMPRESA EXEMPLO LTDA",
        IndicadorIe = 1, // Contribuinte ICMS
        Ie         = "123456789",
        Contato    = new Contato { Email = "financeiro@cliente.com.br" },
        Endereco   = new Endereco
        {
            Logradouro   = "Av. Industrial",
            Numero       = "500",
            Bairro       = "Distrito Industrial",
            CodMunicipio = "3550308",
            Municipio    = "São Paulo",
            Uf           = "SP",
            Cep          = "01000000",
        },
    },

    Produtos = new List<Produto>
    {
        new Produto
        {
            CodProdutoServico = "COD-100",
            NmProduto         = "PARAFUSADEIRA ELETRICA 220V",
            NCM               = "84672100",
            CFOP              = 5102,
            UnidadeComercial  = "UN",
            Quantidade        = 2,
            ValorUnitario     = 150.00m,
            ValorTotal        = 300.00m,
            OrigemProduto     = 0,
            Imposto = new Imposto
            {
                ICMS   = new ICMS   { CodSituacaoTributaria = "102", AliquotaICMS = 0 },
                PIS    = new PIS    { CodSituacaoTributaria = "99",  Aliquota     = 0 },
                COFINS = new COFINS { CodSituacaoTributaria = "99",  Aliquota     = 0 },
            },
        },
    },

    Pagamentos = new List<Pagamento>
    {
        new Pagamento { IndicadorPagamento = 0, FormaPagamento = "15", VlPago = 300.00m },
    },

    Transporte = new Transporte
    {
        ModalidadeFrete = 0, // CIF
        Volume = new Volume
        {
            QuantidadeVolume = 2,
            Especie          = "CAIXA",
            PesoBruto        = 5.500m,
            PesoLiquido      = 5.000m,
        },
    },
};

try
{
    var resp = bnfe.NotaFiscal.EnviarNotaFiscal(nf);

    if (resp.ReturnNF?.Ok == true)
    {
        Console.WriteLine("NF-e autorizada!");
        Console.WriteLine($"Chave:     {resp.ReturnNF.ChaveNF}");
        Console.WriteLine($"Protocolo: {resp.ReturnNF.Numero}");
        Console.WriteLine($"PDF:       {(resp.Base64File != null ? "recebido" : "não gerado")}");
    }
    else
    {
        Console.WriteLine($"Rejeitada: {resp.ReturnNF?.DsStatusRespostaSefaz}");
        if (resp.erros != null)
            foreach (var e in resp.erros)
                Console.WriteLine($" - [{e.codigo}] {e.descricao}");
    }
}
catch (System.ApplicationException ex)
{
    Console.Error.WriteLine($"Erro de comunicação: {ex.Message}");
}

2. Emitir NFC-e (modelo 65)

using BrasilNFePack.Envio;

var nfce = new NotaFiscalEnvio
{
    TipoAmbiente     = 2,
    ModeloDocumento  = 65,                  // NFC-e
    Finalidade       = 1,
    NaturezaOperacao = "VENDA AO CONSUMIDOR",
    IndicadorPresenca = 1,
    ConsumidorFinal  = true,                // obrigatório em NFC-e

    Cliente = new Pessoa
    {
        CpfCnpj = "12345678909",            // opcional em valores baixos
    },

    Produtos = new List<Produto>
    {
        new Produto
        {
            CodProdutoServico = "REFRI-LATA",
            NmProduto         = "REFRIGERANTE LATA 350ML",
            NCM               = "22021000",
            CFOP              = 5102,
            UnidadeComercial  = "UN",
            Quantidade        = 1,
            ValorUnitario     = 5.00m,
            ValorTotal        = 5.00m,
            OrigemProduto     = 0,
            Imposto = new Imposto
            {
                ICMS   = new ICMS   { CodSituacaoTributaria = "102", AliquotaICMS = 0 },
                PIS    = new PIS    { CodSituacaoTributaria = "99",  Aliquota     = 0 },
                COFINS = new COFINS { CodSituacaoTributaria = "99",  Aliquota     = 0 },
            },
        },
    },

    Pagamentos = new List<Pagamento>
    {
        new Pagamento
        {
            IndicadorPagamento = 0,
            FormaPagamento     = "03",      // Cartão de crédito
            VlPago             = 5.00m,
            BandeiraOperadora  = "01",      // Visa
        },
    },
};

var resp = bnfe.NotaFiscal.EnviarNotaFiscal(nfce);

3. Emitir NF-e em lote

using BrasilNFePack.Envio;

var lote = new NotaFiscalLoteEnvio
{
    TipoAmbiente    = 2,
    ModeloDocumento = 55,
    nFInfos = pedidos.Select(pedido => new NotaFiscalEnvio
    {
        TipoAmbiente     = 2,
        ModeloDocumento  = 55,
        Finalidade       = 1,
        NaturezaOperacao = "VENDA DE MERCADORIA",
        Cliente   = /* ... */,
        Produtos  = /* ... */,
        Pagamentos = /* ... */,
    }).ToList(),
};

var resp = bnfe.NotaFiscal.EnviarNotaFiscalLote(lote);
Console.WriteLine($"Chave da 1ª nota: {resp.ReturnNF?.ChaveNF}");

4. Emitir NFS-e

using BrasilNFePack.NFS.Envio;

var nfse = new NotaFiscalServicoEnvio
{
    TipoAmbiente = 2,
    // ... preencha tomador, serviço, valores conforme sua prefeitura
};

var resp = bnfe.NotaFiscal.EnviarNotaFiscalServico(nfse);

5. Emitir CT-e

using BrasilNFePack.CTe;

var cte = new CTeEnvio
{
    TipoAmbiente     = 2,
    ModeloDocumento  = 57,
    TipoCte          = 0,                 // 0 = Normal
    NaturezaOperacao = "PRESTAÇÃO DE SERVIÇO DE TRANSPORTE",
    // preencha Remetente, Destinatário, Tomador, Serviço, Carga, Modal, Imposto...
};

var resp = bnfe.NotaFiscal.EnviarConhecimentoTransporte(cte);
Console.WriteLine($"Chave CT-e: {resp.chave}");

6. Emitir DC-e (Declaração de Conteúdo)

using BrasilNFePack.DCe;

var dce = new DCeEnvio
{
    TipoAmbiente         = 2,
    TipoEmitente         = 3,            // 3 = Transportadora
    ModalidadeTransporte = 2,
    Remetente = new Pessoa
    {
        CpfCnpj  = "00000000000191",
        Nome     = "EMPRESA EXEMPLO LTDA",
        Endereco = new Endereco { Cep = "01000000", Uf = "SP", Municipio = "São Paulo" },
    },
    Destinatario = new Pessoa
    {
        CpfCnpj  = "12345678909",
        Nome     = "JOÃO DA SILVA",
        Endereco = new Endereco { Cep = "30130000", Uf = "MG", Municipio = "Belo Horizonte" },
    },
    Itens = new List<ItemDCe>
    {
        new ItemDCe
        {
            Descricao     = "Livros didáticos",
            NCM           = "4901",
            Quantidade    = 3,
            ValorUnitario = 80.00m,
            ValorTotal    = 240.00m,
        },
    },
    ValorTotal = 240.00m,
};

var resp = bnfe.NotaFiscal.EnviarDeclaracaoConteudo(dce);

7. Cancelar NF-e

using BrasilNFePack.Envio;

var cancel = new CancelarNotaFiscalEnvio
{
    ChaveNF          = "35230100000000000000550010000000011000000000",
    NumeroProtocolo  = "135230000000000",
    Justificativa    = "Erro de digitação no valor do produto",
    TipoAmbienteNFSe = 2,
};

var resp = bnfe.Eventos.CancelarNotaFiscal(cancel);
Console.WriteLine($"Status: {resp.Status}");

8. Carta de Correção (CC-e)

using BrasilNFePack.Envio;

var cce = new CartaCorrecaoEnvio
{
    TipoAmbiente     = 1,
    ChaveNF          = "35230100000000000000550010000000011000000000",
    Correcao         = "Correção na descrição do produto item 1",
    NumeroSequencial = 1,
};

bnfe.Eventos.EnviarCartaCorrecao(cce);

9. Inutilizar numeração

using BrasilNFePack.Envio;

var inut = new InutilizarNumeracaoEnvio
{
    TipoAmbiente     = 1,
    ModeloDocumento  = 55,
    Serie            = 1,
    NumeracaoInicial = 101,
    NumeracaoFinal   = 105,
    Justificativa    = "Falha no sistema durante emissão sequencial",
};

bnfe.Eventos.InutilizarNumeracao(inut);

10. Manifestar NF-e de entrada

using BrasilNFePack.Envio;

var evt = new ManifestarNotaFiscalEnvio
{
    Chave             = "35230100000000000000550010000000011000000000",
    TipoAmbiente      = 1,
    TipoManifestacao  = 1, // 1=Confirmação, 2=Ciência, 3=Desconhecimento, 4=Não realizada
};

bnfe.Eventos.ManifestarNotaFiscal(evt);

11. Consultar status da SEFAZ

using BrasilNFePack.Envio;

var req = new StatusSefazEnvio { TipoAmbiente = 2, ModeloDocumento = 55 };
var resp = bnfe.Consultas.StatusSefaz(req);
Console.WriteLine(resp.StatusSefaz?.DsStatusRespostaSefaz);

12. Buscar notas por período

using BrasilNFePack.Envio;

var busca = new BuscarNotaFiscalEnvio
{
    TipoDocumentoFiscal = 1,                                // 0 = Entradas, 1 = Saídas
    DtInicio = new DateTime(2026, 4, 1, 0, 0, 0),
    DtFim    = new DateTime(2026, 4, 18, 23, 59, 59),
};

var resp = bnfe.Consultas.BuscarNotaFiscal(busca);

13. Baixar XML / DANFE

using BrasilNFePack.Envio;
using System.IO;

var req = new PegarArquivoEnvio
{
    ChaveNF             = "35230100000000000000550010000000011000000000",
    FileType            = 2,        // 1 = XML, 2 = DANFE/Cupom
    TipoDocumentoFiscal = 1,        // 0 = Entrada, 1 = Saída
};

byte[] bytes = bnfe.Arquivos.PegarArquivo(req);   // já vem decodificado de base64
File.WriteAllBytes("danfe.pdf", bytes);

14. Gerar SPED e Sintegra

using BrasilNFePack.Envio;
using BrasilNFePack.Envio.Sped;

var sped = new SpedEnvio { /* período, tipo, finalidade... */ };
var respSped = bnfe.Arquivos.ObterArquivoSped(sped);

var sintegra = new SintegraEnvio { /* ... */ };
var respSintegra = bnfe.Arquivos.ObterArquivoSintegra(sintegra);

15. Gestão de empresas e certificados

Requer userToken no construtor de BrasilNFe.

using BrasilNFePack;
using BrasilNFePack.Envio;
using System.IO;

var bnfe = new BrasilNFe("TOKEN", "USER_TOKEN");

// Cadastro
var empresa = new EmpresaEnvio
{
    Cnpj     = "00000000000191",
    RzSocial = "EMPRESA EXEMPLO LTDA",
    Crt      = 1,                           // 1=Simples, 3=Regime Normal
};
bnfe.Empresa.AdicionarEmpresa(empresa);

// Certificado A1
var cert = new CertificadoEnvio
{
    Base64Certificado = Convert.ToBase64String(File.ReadAllBytes("certificado.pfx")),
    Senha             = "senha-do-pfx",
};
bnfe.Empresa.AlterarCertificado(cert);

// Listagem
var empresas = bnfe.Empresa.BuscarTodasEmpresas();

Referência de Métodos

NotaFiscal

Eventos

Consultas

Arquivos

Empresa

Tratamento de Erros

O SDK lança ApplicationException em dois casos:

1. Falha de comunicação (timeout, DNS, TLS, HTTP fora de 2xx).
2. Falha na desserialização do retorno.

Rejeições da SEFAZ não lançam exceção - elas vêm dentro do objeto de retorno. Sempre verifique ReturnNF?.Ok (e os campos Error / Avisos / erros nos retornos que herdam de Erros).

try
{
    var resp = bnfe.NotaFiscal.EnviarNotaFiscal(nf);

    if (resp.ReturnNF?.Ok != true)
    {
        Console.WriteLine($"Rejeitada [{resp.ReturnNF?.CodStatusRespostaSefaz}] " +
                          $"{resp.ReturnNF?.DsStatusRespostaSefaz}");

        if (!string.IsNullOrEmpty(resp.Error))
            Console.WriteLine($"Erro: {resp.Error}");

        if (resp.Avisos != null)
            foreach (var a in resp.Avisos)
                Console.WriteLine($"Aviso: {a}");

        return;
    }

    Console.WriteLine($"Autorizada: chave {resp.ReturnNF.ChaveNF}");
}
catch (System.ApplicationException ex)
{
    Console.Error.WriteLine($"Falha na integração Brasil NFe: {ex.Message}");
}

Tabelas de Referência

Modelos de documento

TipoAmbiente

Finalidade (NF-e)

IndicadorPresenca

IndicadorIe (destinatário)

ModalidadeFrete

FormaPagamento

TipoManifestacao

Crt (Empresa)

Ambientes

• Homologação: envie TipoAmbiente = 2 em cada requisição. Ideal para testes; nenhuma nota tem validade fiscal.
• Produção: TipoAmbiente = 1. A partir daqui a nota é real - o usuário e CNPJ precisam estar devidamente autorizados no painel Brasil NFe e com certificado digital A1 válido.

A URL base padrão é https://api.brasilnfe.com.br/services/ - a mesma para homologação e produção. O ambiente é sempre determinado pelo campo do payload.

Como o SDK faz as requisições

O SDK usa um HttpClient único (estático, reutilizado entre chamadas) configurado em BrasilNFeRequest:

• Tanto a serialização do payload quanto a desserialização do retorno usam Newtonsoft.Json (JsonConvert).

• As propriedades respeitam o casing esperado pela API (PascalCase na maioria dos módulos NF-e/Eventos).

• Todas as chamadas são POST para a URL base + nome do método.

• Datas seguem DateFormatHandling.IsoDateFormat com cultura pt-BR.

• Toda requisição envia os headers:

  Content-Type:    application/json; charset=utf-8
  Accept:          application/json
  Token:           <seu token>
  UserToken:       <user token, se houver>
  Package-Version: 3.0.0
  

• Timeout padrão: 300s (5 minutos).

• Arquivos binários (XML/DANFE) são devolvidos em byte[] - o SDK decodifica o base64 automaticamente em PegarArquivo / PegarArquivoAsync e PegarArquivoEvento / PegarArquivoEventoAsync.

• Métodos *Async aceitam CancellationToken opcional e propagam o cancelamento até a chamada HTTP subjacente.

Utilitário BrasilNFeHelper

A classe estática BrasilNFeHelper expõe um método de extensão Ratear<T> para distribuir valores proporcionalmente entre itens de uma List<T> (útil para distribuir frete, desconto ou seguro entre produtos da nota). O ajuste é aplicado por reflection na primeira propriedade decimal que casar com o seletor.

using BrasilNFePack;
using static BrasilNFePack.BrasilNFeHelper;

nf.Produtos.Ratear(
    valorTotal:        50.00m,                  // valor total a distribuir (ex.: frete)
    seletor:           p => p.ValorFrete,       // valor base a ajustar
    seletorProporcao:  p => p.ValorTotal,       // base de proporcionalidade
    tipoRateio:        TipoRateio.Somar         // Substituir | Somar | Subtrair
);

Tipos de rateio disponíveis:

Licença

Distribuído sob licença proprietária. Uso autorizado mediante contrato com a BRASIL NFE LTDA.

Suporte

• Site: https://www.brasilnfe.com.br
• E-mail: contato@brasilnfe.com.br
• WhatsApp: +55 (31) 9 7168-5947

Desenvolvido por BRASIL NFE LTDA - CNPJ 39.658.743/0001-99.