NFEConsulta 1.0.1

NFEConsulta é uma biblioteca .NET moderna para consulta de NF-e e serviços fiscais. Além de verificar a situação da NF-e (autorizada, cancelada e outros eventos), permite consultar dados de CNPJ, obter informações e situação cadastral da empresa, validar certificados digitais A1/A3 e verificar sua data de expiração, oferecendo uma API simples, rápida e pronta para integração em aplicações fiscais.

Diferenciais

• Status oficial da SEFAZ via NFeStatusServico4, em vez de ping ou teste de rede.
• Resolucao conservadora de endpoints por UF: consultas inferem a UF pela chave quando omitida; status e cadastro usam SP como fallback.
• CorrelationId opcional para rastrear jobs, lotes e logs.
• Validacao de XML contra XSD oficial incluso no pacote.
• Contratos tipados para separar retorno fiscal de falha tecnica.
• Suporte para biblioteca, CLI e API REST interna.

Documentacao

• Pagina inicial da documentacao
• Guia inicial
• Uso da biblioteca
• Referencia da API
• Solucao de problemas
• Integracao interna
• Contribuindo
• Historico de alteracoes

Instalacao

dotnet add package NFEConsulta

Exemplo rapido

using System.Security.Cryptography.X509Certificates;
using NFEConsulta.Infrastructure;
using NFEConsulta.Models;
using NFEConsulta.Services;

using X509Certificate2 certificado = CertificadoProvider.ObterPorPem(
    "certs/cert.pem",
    "certs/key.pem");

NFeConsultaOptions options = new()
{
    Ambiente = TipoAmbiente.Producao,
    CorrelationId = "job-20260619-001"
};

// Sem Uf explicita, a consulta infere o estado pelos dois primeiros digitos da chave.

using NFeConsultaClient client = NFeConsultaClient.CriarComCertificado(certificado, options);
ConsultaNFeResult resultado = await client.ConsultarChaveAsync("99999999999999999999999999999999999999999999");

Extraindo dados do Certificado

Biblioteca C#

using NFEConsulta.Infrastructure;

CertificadoInfo info = certificado.ExtrairInfo();
Console.WriteLine($"CNPJ: {info.Cnpj}");
Console.WriteLine($"Vencimento: {info.DataExpiracao}");

CLI

nfeconsulta certificado --cert-pem cert.pem --key-pem key.pem
# Ou com saida em JSON:
nfeconsulta certificado --cert-pem cert.pem --key-pem key.pem --json

Consultando CNPJ / Cadastro de Contribuinte na SEFAZ

Você pode consultar a situação fiscal e cadastral de um CNPJ, CPF ou Inscrição Estadual (IE) diretamente junto aos webservices estaduais da SEFAZ usando o método NFeCadastroClient.

using NFEConsulta.Models;
using NFEConsulta.Services;

NFeConsultaOptions options = new()
{
    Ambiente = TipoAmbiente.Producao,
    Uf = UfNFe.SP // Define a UF da consulta
};

using NFeCadastroClient client = NFeCadastroClient.CriarComCertificado(certificado, options);
CadastroConsultaResult resultado = await client.ConsultarCadastroAsync("12345678901234"); // CNPJ, CPF ou IE

if (resultado.Sucesso)
{
    foreach (var cad in resultado.Contribuintes)
    {
        Console.WriteLine($"Nome: {cad.Nome}");
        Console.WriteLine($"IE: {cad.IE}");
        Console.WriteLine($"Situação: {cad.Situacao}"); // Ex: "Habilitado"
        Console.WriteLine($"Endereço: {cad.Endereco?.Logradouro}, {cad.Endereco?.Numero} - {cad.Endereco?.NomeMunicipio}/{cad.UF}");
    }
}

O que esta incluso

• Validacao de chave de acesso de 44 digitos.
• Extracao de chave a partir de XML de NF-e.
• Validacao XML contra XSD oficial.
• Consulta de NF-e por chave.
• Consulta do status oficial da SEFAZ.
• Consulta de cadastro de contribuinte (CNPJ, CPF ou IE) via SEFAZ (CadConsultaCadastro4).
• Extração de dados e metadados de certificados digitais (CNPJ, nome, datas).
• Suporte para biblioteca, CLI e API interna.

Projetos

• src/NFEConsulta.Core: biblioteca principal publicada no NuGet como NFEConsulta.
• src/NFEConsulta.Cli: CLI publicada como NFEConsulta.Cli.
• src/NFEConsulta.Api: API REST interna.

Pacote e versao

A versao publica atual e 0.4.2.

🔗 Projetos relacionados

Ferramentas CLI

• NFEEmissor.Cli (se houver) / ferramentas do ecossistema.
• NFEDanfe.Cli → Geração de DANFE pela linha de comando.
• NFeSchemaDownloader.Cli → Automação de download de Schemas.

Fluxo recomendado

NFeSchemaDownloader (Mantém XSDs atualizados)
   │
   ▼
NFEEmissor (Gera o XML da NF-e)
   │
   ▼
NF-e XML
   │
   ▼
NFEConsulta (Valida XML via XSD e consulta SEFAZ)
   │
   ▼
NFEDanfe (Gera o PDF final)

Autor

Fabyo Guimaraes Oliveira

• LinkedIn: https://www.linkedin.com/in/fabyo-guimaraes/
• GitHub: https://github.com/fabyo

Licenca

MIT.