API para baixar o XML da NF-e pela chave de acesso (com certificado)

POST /api/consultar-nfe-xml devolve o XML completo e assinado (nfeProc) de uma NF-e a partir da chave de acesso de 44 dígitos, usando o certificado digital A1 (e-CNPJ ou e-CPF) de quem participou da nota, e só cobra quando o XML volta: 3 consultas por nota nos planos Lite, Starter e Pro, ou R$ 0,025 por nota no Enterprise.

O certificado não é armazenado (zero custódia): é usado só no momento da consulta e descartado em seguida. A nota só é devolvida quando o titular do certificado é participante (emitente, destinatário, transportador ou autorizado no XML). Sem certificado? Veja XML de NF-e sem certificado.

Resumo

Quanto custa cada chamada

Valores pela franquia de cada plano. Contas com preço negociado contam cada nota como 1 consulta. Na recarga, a NF-e tem preço próprio, informado no painel. Veja Planos e limites.

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

Baixar o XML pela chave com o certificado A1

# 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\":\"35261012345678000195550010000001231123456784\",\"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: "35261012345678000195550010000001231123456784",
      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": "35261012345678000195550010000001231123456784",
        "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' => '35261012345678000195550010000001231123456784',
    '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 = "35261012345678000195550010000001231123456784",
    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. Sem evento: tenta obter o XML com o mesmo certificado sem registrar nenhuma manifestação. Se conseguir, entrega o XML e nada é registrado na SEFAZ.
2. Confirmação da Operação (evento 210200, aceito em até 180 dias): se o XML não foi liberado no passo anterior, 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, depois da manifestação, a SEFAZ estiver limitando as consultas do certificado (cStat 656, "consumo indevido"), a FiscalAPI ainda tenta entregar o XML na mesma requisição. Se não conseguir, a consulta volta somente_resumo e a SEFAZ mantém o bloqueio do certificado por cerca de 1 hora.

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": "35261012345678000195550010000001231123456784",
      "status": "ok",
      "cstat": "138",
      "mensagem": "Documento localizado.",
      "from_cache": false,
      "manifestacao": null,
      "xml": "<nfeProc versao=\"4.00\" ...>...</nfeProc>"
    }
  ]
}

Códigos de erro

Integração com ERPs

A chamada é um POST com corpo JSON e o header X-API-Key, em geral na entrada da nota (recebimento de mercadoria), quando o fornecedor não mandou o XML. Não existe conector pronto.

Perguntas frequentes

Existe API para baixar o XML da NF-e pela chave?

Sim. POST /api/consultar-nfe-xml recebe a chave de acesso e o certificado A1 de um participante da nota e devolve o XML completo e assinado (nfeProc). Sem certificado, há a consulta sem certificado, que devolve uma cópia para leitura, sem assinatura.

Quanto custa baixar o XML pela chave?

Só cobra quando o XML volta: 3 consultas por nota no Lite, Starter e Pro (R$ 2,01, R$ 0,30 e R$ 0,195 pela franquia) e R$ 0,025 por nota no Enterprise. Nota não encontrada, fora do prazo ou com erro não é cobrada.

Preciso ser emitente ou destinatário da nota?

O titular do certificado precisa ser participante da nota: emitente, destinatário, transportador ou autorizado no XML. Se não for, a chave volta nao_autorizado, sem cobrança.

A FiscalAPI guarda o meu certificado?

Não. O certificado e a senha são usados só durante a consulta e descartados em seguida.

XML da NF-e pela chave de acesso · Planos e preços