Consultar Saldo

Consulte a qualquer momento quantas consultas e quantas notas fiscais o saldo da conta ainda paga, e configure um alerta de consumo por e-mail.

GET /api/saldo

Retorna o saldo restante da conta em duas formas: quantas consultas (inscrição estadual, CNPJ, certidões etc.) e quantas notas fiscais (XML de NF-e) ele ainda paga. São os mesmos números que aparecem no topo do painel.

As duas formas dividem o mesmo saldo: gastar notas também reduz as consultas restantes, e vice-versa.

Esta chamada não consome saldo e responde normalmente mesmo com o saldo zerado. O saldo é da conta: com várias API Keys, qualquer uma delas devolve o mesmo valor.

Autenticação

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

Resposta

Campo	Tipo	Descrição
`consultas_restantes`	integer	Quantas consultas o saldo ainda paga.
`notas_restantes`	integer	Quantos XML de NF-e o saldo ainda paga.

{
  "consultas_restantes": 1500,
  "notas_restantes": 500
}

Exemplos de código

curl -X GET "https://api.fiscalapi.com.br/api/saldo" \
  -H "X-API-Key: fapi_sua_chave_aqui"

const response = await fetch("https://api.fiscalapi.com.br/api/saldo", {
  headers: { "X-API-Key": "fapi_sua_chave_aqui" },
});
const saldo = await response.json();
console.log(saldo.consultas_restantes, saldo.notas_restantes);

import requests

response = requests.get(
    "https://api.fiscalapi.com.br/api/saldo",
    headers={"X-API-Key": "fapi_sua_chave_aqui"},
)
saldo = response.json()
print(saldo["consultas_restantes"], saldo["notas_restantes"])

Limite de chamadas

Até 60 chamadas por minuto, contadas à parte: consultar o saldo não gasta o rate limit das suas consultas.

Erros

Status	Código	Quando
403	`API_KEY_ERROR`	API Key ausente, inválida ou revogada.
403	`ACESSO_NEGADO`	Chave demo: ela só vale para a rota de consulta.
429	`RATE_LIMIT_EXCEEDED`	Mais de 60 chamadas no mesmo minuto.

Alerta de consumo por e-mail

Em vez de consultar o saldo periodicamente, você pode receber um aviso por e-mail. No painel, em Configurações › Alerta de consumo, defina:

Consultas: quantas consultas no ciclo disparam o aviso, contadas como no plano (a consulta de CNPJ ao vivo na Receita conta 3);
Notas (NF-e): quantas notas no ciclo disparam o aviso;
E-mails: até 10 endereços que recebem o aviso.

Os dois limites são independentes: o e-mail sai quando qualquer um deles é atingido, uma vez por ciclo para cada um. Deixe um campo vazio para desligar aquele aviso. Consultas recusadas pela fonte não são cobradas e não entram na contagem.

O ciclo acompanha o plano: começa na ativação ou na renovação. Em conta sem plano mensal, o ciclo é o mês corrente.

Planos e preços

Esta pagina foi util?