Como consultar NFS-e pela chave de acesso via API

Para consultar uma NFS-e pela chave de acesso, chame GET /api/consultar-nfse?chave=<50 dígitos> com a sua chave de API: a FiscalAPI devolve a nota em JSON (emitente, tomador, serviço, ISSQN, tributos federais e tipo de geração) e, com danfse=true, o PDF do DANFSe. Não precisa de certificado digital, e quem consulta não precisa ser o emitente nem o tomador.

• Custo por nota entregue: de R$ 0,05 (Enterprise) a R$ 2,01 (Lite). Chave inválida, nota não encontrada e falha não são cobradas.
• Uso típico: o contas a pagar confere a nota de serviço recebida (valores, retenções e ISS) sem pedir PDF ou XML ao prestador.
• Comece: crie a conta e a chave de API. A consulta sai pela API ou no painel da FiscalAPI, sem programar.

Resumo

Quanto custa cada chamada

É o mesmo preço do XML de NF-e sem certificado. O plano Lite não tem recarga. Veja Planos e limites.

Cobrança

• Só a resposta 200 é cobrada, com ou sem o PDF do DANFSe. Pedir o PDF não muda o preço.
• Pela API, a resposta do cache também cobra (cached: true). O resultado de cada chave fica guardado por até 24 horas, e qualquer consulta à mesma chave nesse período volta na hora e é cobrada pelo mesmo preço.
• No painel, repetir a mesma chave em até 24 horas na mesma conta não cobra de novo.
• Não cobra: chave inválida (400), nota não encontrada (404), saldo, termos ou limite (402, 409, 429) e falha (500, 502, 503, 504).
• A chave é validada antes de qualquer cobrança: tamanho, só números e dígito verificador.
• Pela API, pede plano ou saldo. Sem eles, a resposta é 402. As 10 consultas grátis do mês valem só no painel.

Limites e tempo

• Uma chave por requisição. Para várias notas, faça uma requisição por chave.
• Até 2 consultas de NFS-e em andamento por conta ao mesmo tempo. A terceira recebe 429 CONSULTAS_SIMULTANEAS (Retry-After: 5).
• Por minuto: 5 no Lite, 20 no Starter e 30 no Pro e no Enterprise, contados à parte das outras rotas.
• Tempo: em geral, 30 a 60 s numa nota ainda não consultada; com nova tentativa, até cerca de 90 s. Configure o timeout do seu cliente HTTP para pelo menos 100 segundos: a consulta é encerrada em 95.
• Cache: a mesma chave consultada de novo em até 24 horas volta na hora, com cached: true (veja Cobrança). Uma chave que deu 404 volta 404 na hora por 6 horas.
• PDF depois: se a primeira consulta foi sem o PDF, pedir de novo com danfse=true também é rápido.

Autenticação

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

Parâmetros de consulta

Exemplos

Os exemplos usam uma chave fictícia, com dígito verificador válido: 35503082211222333000181000000000012326100000045676. Troque pela chave da sua nota.

Consultar a NFS-e pela chave

curl --max-time 100 \
  "https://api.fiscalapi.com.br/api/consultar-nfse?chave=35503082211222333000181000000000012326100000045676" \
  -H "X-API-Key: fapi_sua_chave_aqui"

// Node.js 18+ (fetch nativo)
const params = new URLSearchParams({
  chave: "35503082211222333000181000000000012326100000045676",
});
const response = await fetch(
  `https://api.fiscalapi.com.br/api/consultar-nfse?${params}`,
  {
    headers: { "X-API-Key": "fapi_sua_chave_aqui" },
    signal: AbortSignal.timeout(100_000),
  }
);
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const nota = await response.json();
console.log(nota.situacao?.descricao, nota.tributacao_municipal?.valor_issqn);

import requests

response = requests.get(
    "https://api.fiscalapi.com.br/api/consultar-nfse",
    headers={"X-API-Key": "fapi_sua_chave_aqui"},
    params={"chave": "35503082211222333000181000000000012326100000045676"},
    timeout=100,
)
response.raise_for_status()
nota = response.json()
print((nota.get("situacao") or {}).get("descricao"))
print((nota.get("tributacao_municipal") or {}).get("valor_issqn"))

<?php
$url = 'https://api.fiscalapi.com.br/api/consultar-nfse?' . http_build_query([
    'chave' => '35503082211222333000181000000000012326100000045676',
]);
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['X-API-Key: fapi_sua_chave_aqui'],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 100,
]);
$corpo = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status !== 200) {
    throw new RuntimeException("FiscalAPI respondeu HTTP $status: $corpo");
}
$nota = json_decode($corpo, true);
echo $nota['situacao']['descricao'] ?? '';

Consultar e salvar o PDF do DANFSe

# Precisa do jq para extrair o campo do JSON
curl --max-time 100 -s \
  "https://api.fiscalapi.com.br/api/consultar-nfse?chave=35503082211222333000181000000000012326100000045676&danfse=true" \
  -H "X-API-Key: fapi_sua_chave_aqui" \
  | jq -r '.danfse_pdf_base64 // empty' | base64 --decode > danfse.pdf

import { writeFile } from "node:fs/promises";

const params = new URLSearchParams({
  chave: "35503082211222333000181000000000012326100000045676",
  danfse: "true",
});
const response = await fetch(
  `https://api.fiscalapi.com.br/api/consultar-nfse?${params}`,
  {
    headers: { "X-API-Key": "fapi_sua_chave_aqui" },
    signal: AbortSignal.timeout(100_000),
  }
);
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const nota = await response.json();
if (nota.danfse_pdf_base64) {
  await writeFile("danfse.pdf", Buffer.from(nota.danfse_pdf_base64, "base64"));
} else {
  console.log(nota.aviso);
}

import base64
import requests

response = requests.get(
    "https://api.fiscalapi.com.br/api/consultar-nfse",
    headers={"X-API-Key": "fapi_sua_chave_aqui"},
    params={
        "chave": "35503082211222333000181000000000012326100000045676",
        "danfse": "true",
    },
    timeout=100,
)
response.raise_for_status()
nota = response.json()
if nota.get("danfse_pdf_base64"):
    with open("danfse.pdf", "wb") as f:
        f.write(base64.b64decode(nota["danfse_pdf_base64"]))
else:
    print(nota.get("aviso"))

<?php
$url = 'https://api.fiscalapi.com.br/api/consultar-nfse?' . http_build_query([
    'chave' => '35503082211222333000181000000000012326100000045676',
    'danfse' => 'true',
]);
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['X-API-Key: fapi_sua_chave_aqui'],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 100,
]);
$corpo = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status !== 200) {
    throw new RuntimeException("FiscalAPI respondeu HTTP $status: $corpo");
}
$nota = json_decode($corpo, true);
if (!empty($nota['danfse_pdf_base64'])) {
    file_put_contents('danfse.pdf', base64_decode($nota['danfse_pdf_base64']));
} else {
    echo $nota['aviso'] ?? '';
}

Resposta

Campo que não aparece na nota volta null. Valores em reais e alíquotas são números (aliquota: 2.0 = 2%). Datas vêm em ISO 8601, com o fuso (2026-10-15T14:32:10-03:00), quando o formato é reconhecido; senão, como constam na nota.

Campos de nível superior

emitente

servico

tributacao_municipal

tributacao_federal

Exemplo de resposta

Dados fictícios. Os textos (como tributacao_issqn e retencao) vêm como estão na nota e podem variar de uma nota para outra.

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "chave": "35503082211222333000181000000000012326100000045676",
  "numero_nfse": "123",
  "codigo_municipio_emissor": "3550308",
  "data_geracao": "2026-10-15T14:32:10-03:00",
  "versao": "1.01",
  "dps": {
    "numero": "123",
    "serie": "00001",
    "data_emissao": "2026-10-15T14:32:02-03:00"
  },
  "situacao": { "codigo": "100", "descricao": "NFS-e Gerada" },
  "emitente": {
    "razao_social": "EMPRESA EXEMPLO SERVICOS LTDA",
    "cpf_cnpj": "11222333000181",
    "inscricao_municipal": "1234567",
    "situacao_simples_nacional": "Microempresa ou Empresa de Pequeno Porte (ME/EPP)",
    "regime_especial_tributacao": "Nenhum",
    "endereco": {
      "logradouro": "RUA EXEMPLO",
      "numero": "100",
      "complemento": null,
      "bairro": "CENTRO",
      "cep": "01001000",
      "municipio": "São Paulo",
      "uf": "SP"
    }
  },
  "tomador": {
    "cpf_cnpj": "99888777000166",
    "inscricao_municipal": null,
    "nome": "CLIENTE EXEMPLO S.A."
  },
  "intermediario": null,
  "servico": {
    "pais": "Brasil",
    "municipio": "São Paulo/SP",
    "codigo_tributacao_nacional": "010401",
    "descricao_codigo": "Elaboração de programas de computadores, inclusive de jogos eletrônicos, independentemente da arquitetura construtiva da máquina em que o programa será executado, incluindo tablets, smartphones e congêneres.",
    "item_nbs": null,
    "descricao": "Licenciamento de software - outubro/2026"
  },
  "tributacao_municipal": {
    "tributacao_issqn": "1 - Operação Tributável",
    "municipio_incidencia": "São Paulo/SP",
    "valor_servico": 1500.0,
    "desconto_incondicionado": 0.0,
    "deducoes": 0.0,
    "beneficio_municipal": 0.0,
    "base_calculo": 1500.0,
    "aliquota": 2.0,
    "valor_issqn": 30.0,
    "retencao": "1 - Não Retido"
  },
  "tributacao_federal": {
    "situacao_pis_cofins": "Não informado",
    "base_calculo_pis_cofins": 0.0,
    "aliquota_pis": 0.0,
    "valor_pis": 0.0,
    "aliquota_cofins": 0.0,
    "valor_cofins": 0.0,
    "irrf": 0.0,
    "contribuicoes_sociais_retidas": 0.0,
    "contribuicao_previdenciaria_retida": 0.0
  },
  "total_tributos": [
    {
      "descricao": "Valor percentual aproximado do total dos tributos da alíquota do Simples Nacional",
      "valor": 6.0
    }
  ],
  "informacoes_complementares": null,
  "ambiente_gerador": "2 - Sefin Nacional NFS-e",
  "cached": false,
  "danfse_pdf_base64": null,
  "aviso": null
}

Com danfse=true, danfse_pdf_base64 vem com o PDF (começa com JVBERi0, que é %PDF- em base64).

Estrutura da chave de acesso da NFS-e

A chave da NFS-e do padrão nacional tem 50 dígitos. Na chave fictícia dos exemplos:

A chave aparece no DANFSe e no XML da nota (atributo Id, depois do prefixo NFS). A API aceita a chave formatada, com espaços ou pontos, e com o prefixo NFS.

Cobertura

A consulta cobre NFS-e do padrão nacional: notas emitidas no Emissor Nacional ou compartilhadas com o Ambiente de Dados Nacional. Nota de município que usa sistema próprio e não compartilha com o padrão nacional pode voltar 404 NFSE_NAO_ENCONTRADA, mesmo que exista.

Notas com chave de 44 dígitos são NF-e, não NFS-e: use XML de NF-e sem certificado.

Códigos de erro

Os erros seguem o formato RFC 7807: o código fica no campo title. Nenhum deles é cobrado.

Integração com ERPs

A chamada é um GET com o header X-API-Key, em geral na entrada da nota de serviço ou na conferência do contas a pagar. Não existe conector pronto.

Perguntas frequentes

Como consultar uma NFS-e pela chave de acesso?

Chame GET https://api.fiscalapi.com.br/api/consultar-nfse?chave=<50 dígitos> com o header X-API-Key. A resposta traz emitente, tomador, serviço, ISSQN e tributos federais da nota em JSON. Sem programar, a mesma consulta sai no painel da FiscalAPI. Com danfse=true, vem também o PDF do DANFSe em base64.

Precisa de certificado digital para consultar NFS-e?

Não. Basta a chave de acesso de 50 dígitos. Quem consulta não precisa ser o emitente nem o tomador da nota.

Quanto custa consultar uma NFS-e por API?

Por nota entregue: R$ 2,01 no Lite, R$ 0,30 no Starter, R$ 0,195 no Pro e R$ 0,05 no Enterprise. Chave inválida, nota não encontrada e falha não são cobradas.

A API devolve o XML da NFS-e?

Não. A resposta é JSON com os dados da nota e, se pedido com danfse=true, o PDF do DANFSe em base64.

Quanto tempo leva a consulta de NFS-e?

Em geral, 30 a 60 s; com nova tentativa, até cerca de 90 s. Uma chave já consultada nas últimas 24 horas volta na hora. Configure o timeout do cliente HTTP para pelo menos 100 segundos.

Quantos dígitos tem a chave de acesso da NFS-e?

50 dígitos: código IBGE do município emissor (7), ambiente gerador (1), tipo de inscrição (1), CPF ou CNPJ do emitente (14), número da NFS-e (13), ano e mês de emissão (4), código numérico (9) e dígito verificador (1).

A consulta mostra se a NFS-e foi cancelada?

Não. O campo situacao traz o tipo de geração da nota: 100 gerada, 101 de substituição, 102 por decisão judicial, 103 avulsa. O campo situacao não indica cancelamento: cancelamento é um evento registrado à parte. Não use esse campo como prova de que a nota não foi cancelada.

A consulta funciona para NFS-e de qualquer município?

Funciona para NFS-e do padrão nacional: notas emitidas no Emissor Nacional ou compartilhadas com o Ambiente de Dados Nacional. Nota de município com sistema próprio que não compartilha com o padrão nacional pode voltar 404, e esse 404 não é cobrado.

Dá para consultar várias NFS-e de uma vez?

Faça uma requisição por chave. A conta pode ter até 2 consultas de NFS-e em andamento ao mesmo tempo, dentro do limite por minuto do plano.

Consulta de NFS-e pela chave de acesso · Planos e preços