--- title: "Consulta Irrestrita" description: "Consulta nacional unificada de Notas Fiscais Eletrônicas (NF-e) pela chave de acesso, com retorno em JSON, XML e PDF." source_url: https://nfe.io/docs/documentacao/consultas/notas-fiscais/consulta-irrestrita last_updated: 2026-05-29 --- # 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](/desenvolvedores/rest-api/consulta-de-nota-fiscal-v2/). ## Fluxo da chamada ```mermaid flowchart LR A[Cliente] --> B[NFE.io] B --> C[Provedor oficial
de NF-e] C --> B B --> A ``` 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](/documentacao/nossa-plataforma/chaves-de-autenticacao/). ## 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. ```bash # 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) ```json { "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](/documentacao/nossa-plataforma/chaves-de-autenticacao/). | | `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: ` — 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](/documentacao/consultas/notas-fiscais/) - [Referência REST: Consulta de Nota Fiscal V2](/desenvolvedores/rest-api/consulta-de-nota-fiscal-v2/) - [Chaves de Autenticação NFE.io](/documentacao/nossa-plataforma/chaves-de-autenticacao/)