Consulta Irrestrita

A Consulta Irrestrita é a forma da NFE.io para você recuperar uma Nota Fiscal Eletrônica (NF-e) autorizada pela chave de acesso, sem depender de portais estaduais individuais. Você recebe o documento em JSON estruturado, XML oficial e DANFE em PDF chamando o mesmo endpoint com sufixos diferentes.

Use quando precisar de uma fonte nacional única que cubra qualquer UF (SP, RJ, CE, etc.) pela mesma chamada. Para a referência REST completa, veja a Consulta de Nota Fiscal V2.

Fluxo da chamada

Você chama a NFE.io. A NFE.io chama o provedor oficial autorizado pela autoridade federal e devolve o documento normalizado.

Contrato HTTP

Item	Valor
Host	nfe.api.nfe.io
Método	GET
Path JSON	/v2/productinvoices/serpro/{accessKey}
Path XML	/v2/productinvoices/serpro/{accessKey}.xml
Path PDF	/v2/productinvoices/serpro/{accessKey}.pdf
accessKey	string com 44 dígitos numéricos (chave de acesso da NF-e)
Header Authorization	Sua Chave de Dados da NFE.io, enviada direto sem prefixo Bearer
Content-Type da resposta	application/json (JSON), 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/serpro/35200714200166000166550010000000071000000007" \
  -H "Authorization: SUA_CHAVE_DE_DADOS"

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

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

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.

Campo	Descrição
currentStatus	Situação atual da NF-e. Valores: Authorized, Canceled, Unknown.
stateCode	UF do emitente (equivale a cUF no XML).
operationNature	Natureza da operação (natOp).
codeModel, serie, number	Modelo, série e número da NF-e (mod, serie, nNF).
issuedOn, operationOn	Data/hora de emissão e da operação (dhEmi, dhSaiEnt).
environmentType	Ambiente de emissão (Production ou Homologation).
issuer	Dados do emitente: federalTaxNumber (CNPJ), name, tradeName, stateTaxNumber (IE), codeTaxRegime, address.
buyer	Dados do destinatário: federalTaxNumber (CNPJ/CPF), name, address, stateTaxNumberIndicator.
items[]	Itens da nota: code, description, ncm, cfop, unit, quantity, unitAmount, totalAmount, tax.
totals.icms	Totais da nota: productAmount, invoiceAmount, discountAmount, freightAmount, icmsAmount etc.
transport	Dados de transporte e volumes (freightModality, transportGroup, volume).
payment[]	Formas de pagamento (paymentDetail[].method, paymentDetail[].amount).
protocol	Protocolo 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ódigo	Significado	O que fazer
200	Nota encontrada e retornada.	Leia protocol.statusCode. 100 = autorizada (ou currentStatus == "Authorized").
400	accessKey inválida (formato fora dos 44 dígitos).	Valide a chave antes de chamar.
401	Chave de Dados ausente, incorreta ou com prefixo Bearer.	Confira Chaves de Autenticação.
403	Chave de Dados sem permissão para Consulta de NF-e.	Solicite ativação no painel NFE.io.
404	Chave 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.
5xx	Indisponibilidade 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 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 Irrestrita da NFE.io.

Modelo mental. Trate a API como uma fonte fiscal nacional sobre NF-e autorizadas. 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/serpro/{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. Se 404, informe ao usuário que a nota não está disponível.
6. Se 5xx, instrua nova tentativa em alguns minutos.

Dado autorizativo essencial. O campo protocol.statusCode == 100 é a única evidência de autorização. Sem ela, a nota não tem valor fiscal mesmo aparecendo no JSON.

Veja também

• Consulta de Nota Fiscal Eletrônica — visão geral
• Referência REST: Consulta de Nota Fiscal V2
• Chaves de Autenticação NFE.io