Pular para o conteúdo principal
Ver como Markdown

Consulta SEFAZ

A Consulta SEFAZ é o caminho da NFE.io para você recuperar uma Nota Fiscal Eletrônica (NF-e) autorizada pela chave de acesso, consultando o portal público nacional da Receita Federal (nfe.fazenda.gov.br). Cobertura nacional, retorno em JSON estruturado, XML oficial, DANFE em PDF e histórico de eventos da nota (cancelamento, CC-e, manifestação).

Use quando precisar consultar a NF-e e seus eventos a partir da fonte pública oficial. Para uma alternativa via provedor oficial com maior previsibilidade, veja a Consulta Irrestrita. Para a referência REST completa, veja a Consulta de Nota Fiscal V2.

Fluxo da chamada​

Você chama a NFE.io. A NFE.io consulta o portal público nacional da Receita Federal e devolve o documento normalizado.

Contrato HTTP​

ItemValor
Hostnfe.api.nfe.io
MétodoGET
Path JSON/v2/productinvoices/{accessKey}
Path XML/v2/productinvoices/{accessKey}.xml
Path PDF/v2/productinvoices/{accessKey}.pdf
Path Eventos/v2/productinvoices/events/{accessKey}
accessKeystring com 44 dígitos numéricos (chave de acesso da NF-e)
Header AuthorizationSua Chave de Dados da NFE.io, enviada direto sem prefixo Bearer
Content-Type da respostaapplication/json (JSON e Eventos), application/xml (XML), application/pdf (PDF)

Detalhes da chave de autenticação em Chaves de Autenticação.

Como chamar​

A consulta expõe o mesmo recurso em três formatos. Apenas a URL muda — método, autenticação e parâmetros são idênticos.

# JSON estruturado (default)
curl -X GET \
  "https://nfe.api.nfe.io/v2/productinvoices/35200714200166000166550010000000071000000007" \
  -H "Authorization: SUA_CHAVE_DE_DADOS"

# XML oficial
curl -X GET \
  "https://nfe.api.nfe.io/v2/productinvoices/35200714200166000166550010000000071000000007.xml" \
  -H "Authorization: SUA_CHAVE_DE_DADOS" \
  -o nota.xml

# DANFE em PDF
curl -X GET \
  "https://nfe.api.nfe.io/v2/productinvoices/35200714200166000166550010000000071000000007.pdf" \
  -H "Authorization: SUA_CHAVE_DE_DADOS" \
  -o nota.pdf

Consultar eventos da nota​

A Consulta SEFAZ permite recuperar o histórico de eventos da NF-e (cancelamento, Carta de Correção, manifestação do destinatário), separadamente da consulta da nota em si.

curl -X GET \
  "https://nfe.api.nfe.io/v2/productinvoices/events/35200714200166000166550010000000071000000007" \
  -H "Authorization: SUA_CHAVE_DE_DADOS"

Use eventos para verificar se a nota foi cancelada, corrigida ou se o destinatário manifestou ciência da operação — informações que não vêm na resposta principal da nota.

Campos do retorno (JSON)​

Os campos abaixo aparecem na resposta 200 OK em JSON. O conteúdo é equivalente ao XML oficial (nfeProc), mas com nomes normalizados em camelCase para consumo por sistemas. Os nomes originais do XML (cStat, cUF, natOp, emit, dest etc.) não aparecem no JSON — use o sufixo .xml se precisar do schema oficial.

CampoDescrição
currentStatusSituação atual da NF-e. Valores: Authorized, Canceled, Unknown.
stateCodeUF do emitente (equivale a cUF no XML).
operationNatureNatureza da operação (natOp).
codeModel, serie, numberModelo, série e número da NF-e (mod, serie, nNF).
issuedOn, operationOnData/hora de emissão e da operação (dhEmi, dhSaiEnt).
environmentTypeAmbiente de emissão (Production ou Homologation).
issuerDados do emitente: federalTaxNumber (CNPJ), name, tradeName, stateTaxNumber (IE), codeTaxRegime, address.
buyerDados do destinatário: federalTaxNumber (CNPJ/CPF), name, address, stateTaxNumberIndicator.
items[]Itens da nota: code, description, ncm, cfop, unit, quantity, unitAmount, totalAmount, tax.
totals.icmsTotais da nota: productAmount, invoiceAmount, discountAmount, freightAmount, icmsAmount etc.
transportDados de transporte e volumes (freightModality, transportGroup, volume).
payment[]Formas de pagamento (paymentDetail[].method, paymentDetail[].amount).
protocolProtocolo de autorização: accessKey, protocolNumber, receiptOn, statusCode. statusCode == 100 = nota autorizada (equivale a cStat no XML).

Exemplo de resposta (recorte)​

{
  "currentStatus": "Authorized",
  "stateCode": 35,
  "operationNature": "Venda de Produção",
  "codeModel": 55,
  "serie": 1,
  "number": 7,
  "issuedOn": "2020-07-15T14:32:00-03:00",
  "environmentType": "Production",
  "xmlVersion": "4.00",
  "issuer": {
    "federalTaxNumber": 14200166000166,
    "name": "Empresa Emitente LTDA",
    "stateTaxNumber": "111222333444",
    "address": {
      "state": "SP",
      "city": { "code": "3550308", "name": "SAO PAULO" }
    }
  },
  "buyer": {
    "federalTaxNumber": 99887766000155,
    "name": "Empresa Destinatária SA"
  },
  "items": [
    {
      "code": "PROD-001",
      "description": "Produto exemplo",
      "ncm": "61143000",
      "cfop": 6102,
      "unit": "UN",
      "quantity": 1.0,
      "totalAmount": 13.52
    }
  ],
  "totals": {
    "icms": { "productAmount": 13.52, "invoiceAmount": 12.66 }
  },
  "protocol": {
    "environmentType": "Production",
    "accessKey": "35200714200166000166550010000000071000000007",
    "protocolNumber": "135200000000007",
    "statusCode": 100
  }
}

Status HTTP​

CódigoSignificadoO que fazer
200Nota encontrada e retornada.Leia protocol.statusCode. 100 = autorizada (ou currentStatus == "Authorized").
400accessKey inválida (formato fora dos 44 dígitos).Valide a chave antes de chamar.
401Chave de Dados ausente, incorreta ou com prefixo Bearer.Confira Chaves de Autenticação.
403Chave de Dados sem permissão para Consulta de NF-e.Solicite ativação no painel NFE.io.
404Chave válida em formato mas NF-e não localizada.Tratar como regra de negócio. A nota pode não estar disponível ainda.
5xxIndisponibilidade temporária.Nova tentativa em alguns minutos.

Armadilhas comuns​

  • Chamar sem validar a chave. Sempre confirme que accessKey tem exatamente 44 dígitos numéricos antes de chamar. Chaves inválidas geram 400 e poluem seu monitoramento.
  • Tratar HTTP 404 como erro de sistema. Não é. Significa que a NF-e ainda não está disponível ou aponta para nota inexistente. É regra de negócio, não falha.
  • Usar prefixo Bearer no header Authorization. A NFE.io aceita a Chave de Dados direto, sem Bearer. Com prefixo errado, retorno é HTTP 401.
  • Confiar no JSON sem checar protocol.statusCode. Uma nota pode estar na base sem estar autorizada (rejeitada ou denegada). Sempre verifique protocol.statusCode == 100 — equivalente ao cStat no XML. O campo currentStatus == "Authorized" é a forma textual do mesmo sinal.
  • Não consultar eventos quando precisa do estado atual. A resposta principal traz a nota autorizada inicialmente, mas eventos posteriores (cancelamento, CC-e) só aparecem em /events/{accessKey}. Para decisões de negócio críticas, valide eventos.
  • Não armazenar o XML. O JSON é conveniente para sistemas; o XML é o documento fiscal oficial. Para fins legais, guarde o .xml pelos 5 anos exigidos.

Como uma IA deve consumir esta API​

Esta seção é dirigida a agentes de IA construindo integrações ou respondendo perguntas sobre a Consulta SEFAZ da NFE.io.

Modelo mental. Trate a API como uma fonte fiscal nacional sobre NF-e autorizadas, com acesso ao histórico de eventos da nota. A chave de acesso é a única dimensão de consulta. O JSON retornado é equivalente, em conteúdo, ao XML oficial.

Plano de ação típico.

  1. Receba a chave de acesso da entrada do usuário (44 dígitos).
  2. Valide pelo regex ^[0-9]{44}$.
  3. Chame GET https://nfe.api.nfe.io/v2/productinvoices/{accessKey} com header Authorization: <Chave de Dados> — sem Bearer.
  4. Se 200, leia protocol.statusCode. 100 indica autorizada (equivale a cStat no XML). O campo currentStatus == "Authorized" é a forma textual do mesmo sinal.
  5. Para decisões críticas, consulte também /v2/productinvoices/events/{accessKey} para verificar cancelamento ou correções posteriores.
  6. Se 404, informe ao usuário que a nota não está disponível.
  7. Se 5xx, instrua nova tentativa em alguns minutos.

Dado autorizativo essencial. O campo protocol.statusCode == 100 na resposta principal é evidência de autorização inicial. Eventos posteriores podem alterar o estado da nota — consulte /events/ quando o caso de uso exigir estado atualizado.

Veja também​

NFE.io

A NFE.io é uma empresa de tecnologia que fornece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas. Com suas ferramentas, as empresas podem economizar tempo e reduzir erros, aumentando a eficiência e precisão do processo de emissão de notas fiscais.

Um dos principais cases de sucesso da NFE.io é a implementação da solução na empresa de transporte Rodonaves. Com a automatização da emissão e gestão de notas fiscais eletrônicas, a Rodonaves conseguiu reduzir em até 80% o tempo gasto nesse processo, o que se traduziu em uma significativa melhoria na eficiência operacional. Além disso, a empresa também conseguiu eliminar erros e atrasos na emissão de notas fiscais, o que melhorou a relação com seus clientes e aumentou a confiança dos órgãos fiscais.

Outro exemplo é a implementação da NFE.io na empresa de comércio eletrônico, a Loja Integrada. Com a automatização da emissão de notas fiscais, a Loja Integrada conseguiu aumentar a velocidade de emissão de notas em até 10 vezes, o que permitiu que a empresa atendesse a uma maior quantidade de clientes e, consequentemente, aumentar as suas vendas.

Além desses exemplos, a NFE.io também tem outros cases de sucesso com empresas de setores como indústria, construção, varejo e serviços, mostrando a versatilidade e eficácia da sua solução.

Em resumo, a NFE.io é uma empresa de tecnologia que oferece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas, ajudando as empresas a economizar tempo e reduzir erros, melhorando a eficiência e precisão do processo. Com cases de sucesso em diferentes setores, a NFE.io tem se destacado como uma empresa líder em automação fiscal.