Consultar NF-e por chave

POST /api/consultar-nfe-xml

Retorna o XML completo (nfeProc assinado) de uma NF-e a partir da chave de acesso de 44 dígitos, usando o certificado digital do cliente (e-CPF ou e-CNPJ A1) enviado na requisição. Uma chave por requisição.

O certificado não é armazenado (zero custódia): ele é usado apenas no momento da consulta e descartado em seguida. Só é retornada a nota quando o titular do certificado é participante (emitente, destinatário, transportador ou autorizado no XML).

Cobrança: 3 créditos quando a chave retorna XML. Sem retorno (não encontrada, fora do prazo, erro) não cobra. Em R$ por nota, pela franquia de cada plano: Lite R$ 2,00 · Starter R$ 0,30 · Pro R$ 0,195 · Enterprise R$ 0,075. Contas com preço negociado (exclusivo) debitam 1 crédito por nota.

Autenticação

Envie sua chave no header X-API-Key. Veja Autenticação para detalhes.

Corpo da requisição

Envie um JSON (Content-Type: application/json) com os campos abaixo.

Exemplos de código

# codifica o certificado em base64 e envia
CERT=$(base64 -w0 certificado.pfx)
curl -X POST "https://api.fiscalapi.com.br/api/consultar-nfe-xml" \
  -H "X-API-Key: fapi_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d "{\"chave\":\"43260689677595000128550030006074891411409127\",\"certificado\":\"$CERT\",\"senha\":\"sua-senha\"}"

import { readFileSync } from "node:fs";

const certificado = readFileSync("certificado.pfx").toString("base64");

const response = await fetch(
  "https://api.fiscalapi.com.br/api/consultar-nfe-xml",
  {
    method: "POST",
    headers: {
      "X-API-Key": "fapi_sua_chave_aqui",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      chave: "43260689677595000128550030006074891411409127",
      certificado,
      senha: "sua-senha",
    }),
  }
);
const data = await response.json();
console.log(data.resultados[0]);

import base64
import requests

with open("certificado.pfx", "rb") as f:
    certificado = base64.b64encode(f.read()).decode()

response = requests.post(
    "https://api.fiscalapi.com.br/api/consultar-nfe-xml",
    headers={"X-API-Key": "fapi_sua_chave_aqui"},
    json={
        "chave": "43260689677595000128550030006074891411409127",
        "certificado": certificado,
        "senha": "sua-senha",
    },
)
data = response.json()
print(data["resultados"][0])

$certificado = base64_encode(file_get_contents('certificado.pfx'));

$response = Http::withHeaders([
    'X-API-Key' => 'fapi_sua_chave_aqui',
])->post('https://api.fiscalapi.com.br/api/consultar-nfe-xml', [
    'chave' => '43260689677595000128550030006074891411409127',
    'certificado' => $certificado,
    'senha' => 'sua-senha',
]);
$data = $response->json();

var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "fapi_sua_chave_aqui");

var certificado = Convert.ToBase64String(File.ReadAllBytes("certificado.pfx"));
var payload = new
{
    chave = "43260689677595000128550030006074891411409127",
    certificado,
    senha = "sua-senha",
};
var content = new StringContent(
    System.Text.Json.JsonSerializer.Serialize(payload),
    System.Text.Encoding.UTF8,
    "application/json"
);
var response = await client.PostAsync(
    "https://api.fiscalapi.com.br/api/consultar-nfe-xml", content
);
var data = await response.Content.ReadAsStringAsync();

Resposta

Campos de nível superior

Campos de cada resultado (resultados[])

Valores de status

Ciência da Operação automática

Quando o certificado é do destinatário e ele ainda não se manifestou, a SEFAZ devolve apenas o resumo da nota. Nesse caso a FiscalAPI registra a Ciência da Operação (evento 210210) com o próprio certificado e consulta de novo, entregando o XML completo na mesma requisição. O evento é assinado com o certificado enviado e fica registrado na SEFAZ em nome do destinatário.

A Ciência da Operação só é aceita pela SEFAZ em até 10 dias da autorização da NF-e (cStat 596). Passado esse prazo, a FiscalAPI segue nesta ordem:

1. Portal da NF-e: tenta o download do XML pelo portal nacional com o mesmo certificado. Não registra nenhum evento. Se o portal estiver indisponível no momento (falha transitória), a consulta volta somente_resumo e pede nova tentativa — nenhum evento é registrado nesse caso.
2. Confirmação da Operação (evento 210200, aceito em até 180 dias): se o portal respondeu e não liberou o download, a FiscalAPI registra a Confirmação com o certificado do destinatário e consulta de novo. A Confirmação declara que a operação ocorreu e impede o emitente de cancelar a NF-e. Ela só é enviada quando a Ciência foi recusada por prazo (ou a nota já tem mais de dois meses), nunca em outro tipo de rejeição.

Se a SEFAZ estiver limitando as consultas do certificado (cStat 656, "consumo indevido"), a manifestação é registrada normalmente e o XML é buscado pelo portal, que não tem esse limite.

O campo manifestacao informa o que aconteceu:

Registrar a Ciência da Operação não impede o destinatário de registrar depois Confirmação, Desconhecimento ou Operação não Realizada. A Confirmação da Operação é definitiva: depois dela não é possível registrar Desconhecimento.

Notas com mais de 180 dias da autorização não aceitam mais nenhuma manifestação: a consulta volta somente_resumo e nenhum evento é enviado. Nota cancelada ou denegada também não recebe evento (status = cancelada ou erro).

Exemplo de resposta

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "total": 1,
  "com_dado": 1,
  "creditos_cobrados": 3,
  "resultados": [
    {
      "chave": "43260689677595000128550030006074891411409127",
      "status": "ok",
      "cstat": "138",
      "mensagem": "Documento localizado.",
      "from_cache": false,
      "manifestacao": null,
      "xml": "<nfeProc versao=\"4.00\" ...>...</nfeProc>"
    }
  ]
}

Códigos de erro