Consulta de Inscrição Estadual via API: Tutorial Completo + Comparativo 2026

Consultar Inscrição Estadual (IE) via API é uma chamada HTTP que retorna em segundos o status cadastral, razão social, CNAE e município de um CNPJ ou CPF de produtor rural em qualquer um dos 27 estados brasileiros. Substitui a consulta manual no SINTEGRA — um portal por estado, uma consulta por vez — por uma única requisição programática integrável ao seu ERP, sistema próprio ou pipeline de cadastro.

Este artigo mostra o tutorial completo da API FiscalAPI com exemplos em cURL, Node.js e Python, o tratamento de erros que toda integração precisa, e quando faz sentido migrar do SINTEGRA manual para uma API.

Por que API e não SINTEGRA manual#

A consulta manual no SINTEGRA ou nos portais SEFAZ trava em escala por 3 razões estruturais:

1. Um portal por estado. São 27 portais, cada um com endereço e formulário próprios, e uma consulta por vez.
2. Variação entre portais. Cada SEFAZ tem layout, formato de input e formato de resposta distintos — o resultado sai numa tela para leitura humana, não em dado estruturado.
3. Instabilidade. Portais estaduais entram em manutenção e oscilam. Quem consulta à mão precisa voltar e tentar de novo mais tarde.

API de provedor especializado resolve isso: 1 endpoint único, o mesmo formato de resposta para os 27 estados e cache inteligente que diminui consumo sem perder atualidade.

Tutorial — primeira consulta em 5 minutos#

1. Criar conta + gerar API key#

Acesse fiscalapi.com.br, assine o plano que melhor atende seu volume (a partir de R$ 19,99/mês), e gere a chave em Configurações → API Keys → Nova chave. Os planos disponíveis são:

Todos os planos incluem dashboard sem código + API + cobertura nos 27 estados.

2. Endpoint REST#

GET https://api.fiscalapi.com.br/api/consultar?uf={uf}&cnpj={cnpj}
Headers: X-API-Key: {API_KEY}

Parâmetros:

Informe um entre cnpj, cpf ou ie. Enviar mais de um retorna erro PARAMETRO_CONFLITANTE.

3. cURL#

curl -X GET "https://api.fiscalapi.com.br/api/consultar?uf=MT&cpf=12345678909" \
  -H "X-API-Key: SUA_API_KEY"

Resposta:

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "document": "12345678909",
  "document_type": "cpf",
  "uf": "MT",
  "cached": false,
  "results": [
    {
      "inscricao_estadual": "13.234.567-6",
      "razao_social": "JOAO DA SILVA FAZENDA SANTA MARIA",
      "situacao_ie": "Habilitado",
      "situacao_cadastral": "Ativo - HABILITADO",
      "uf_ie": "MT",
      "tipo_ie": "IE de Produtor Rural",
      "municipio": "RONDONOPOLIS",
      "cnae_codigo": "0111-3/01",
      "cnae_descricao": "CULTIVO DE ARROZ",
      "cpf_cnpj": "123.456.789-09"
    }
  ]
}

4. Node.js (fetch nativo, Node 22+)#

async function consultarIE({ uf, cnpj, cpf, ie }) {
  const url = new URL("https://api.fiscalapi.com.br/api/consultar");
  url.searchParams.set("uf", uf);
  if (cnpj) url.searchParams.set("cnpj", cnpj);
  else if (cpf) url.searchParams.set("cpf", cpf);
  else if (ie) url.searchParams.set("ie", ie);

  const res = await fetch(url, {
    headers: { "X-API-Key": process.env.FISCALAPI_KEY },
  });

  const data = await res.json();
  if (!res.ok) {
    throw new Error(`${data.error}: ${data.message}`);
  }
  return data;
}

const ie = await consultarIE({ uf: "SP", cnpj: "12345678000195" });
const primeiro = ie.results?.[0];
// situacao_ie: "Habilitado" ou "Não habilitado" (maiúsculas variam)
if (!primeiro || primeiro.situacao_ie.trim().toLowerCase() !== "habilitado") {
  console.warn(`IE irregular: ${primeiro?.situacao_ie ?? "nao localizada"}`);
}

5. Python#

import os
import requests

def consultar_ie(uf: str, *, cnpj: str | None = None, cpf: str | None = None, ie: str | None = None) -> dict:
    params = {"uf": uf}
    if cnpj:
        params["cnpj"] = cnpj
    elif cpf:
        params["cpf"] = cpf
    elif ie:
        params["ie"] = ie

    r = requests.get(
        "https://api.fiscalapi.com.br/api/consultar",
        params=params,
        headers={"X-API-Key": os.environ['FISCALAPI_KEY']},
        timeout=15,
    )
    r.raise_for_status()
    return r.json()

resp = consultar_ie("MT", cpf="12345678909")
primeiro = resp["results"][0] if resp["results"] else None
# situacao_ie: "Habilitado" ou "Não habilitado" (maiúsculas variam)
if not primeiro or primeiro["situacao_ie"].strip().casefold() != "habilitado":
    raise ValueError(f"IE irregular: {primeiro and primeiro['situacao_ie']}")

Estratégia de cache#

O campo cached na resposta indica se o resultado veio do cache interno da FiscalAPI. Vantagens:

• Latência menor.
• Não conta — em alguns casos — contra o limite do plano.

Boas práticas no seu lado:

Se você manteve um cache próprio do seu lado, a recomendação é TTL de 7 a 30 dias para CNPJs ativos. Para produtor rural com renovações sazonais e operação intermitente, prefira TTL menor (até 7 dias).

Tratamento de erros#

A API retorna respostas estruturadas em caso de erro, no formato:

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "error": "PARAMETRO_AUSENTE",
  "message": "Informe cpf, cnpj ou ie"
}

Códigos retornados:

Retry recomendado#

Para 502 e 503 (problemas do SEFAZ), retry com backoff exponencial até 3 tentativas:

async function consultarComRetry(args, tentativas = 3) {
  for (let i = 0; i < tentativas; i++) {
    try {
      return await consultarIE(args);
    } catch (err) {
      const transient = /502|503/.test(err.message);
      if (!transient || i === tentativas - 1) throw err;
      const espera = Math.min(2 ** i * 1000 + Math.random() * 500, 10000);
      await new Promise(r => setTimeout(r, espera));
    }
  }
}

Para 400 (parâmetro inválido), não tentar de novo — o input está errado.

Quando vale a pena migrar do SINTEGRA manual#

Faz sentido considerar API quando aparece pelo menos um destes:

• Volume recorrente — o operador manual perde mais tempo do que o plano Lite custa (R$ 19,99/mês, com 30 consultas).
• Necessidade de validação em tempo real no momento do cadastro (sistema próprio, ERP, marketplace).
• Operação multi-estado — cada estado tem portal, formulário e layout próprios.
• Compliance recorrente — verificar fornecedores ativos 1x por mês (LGPD, lei anticorrupção, lavagem de dinheiro).
• Validação de NF-e pré-emissão — rejeição NF-e por IE inválida (código 210) custa retrabalho e atraso na entrega da mercadoria.

Os três indicadores comuns de "passou da hora":

1. Você tem uma planilha "Excel — IEs a validar" que cresce mais rápido do que a equipe consegue limpar.
2. Sua equipe fiscal já perde tempo consultando portal por portal.
3. Sua área comercial ou crédito já fechou negócio sem validar IE — e o cliente bateu rejeição na primeira NF-e.

Boas práticas de integração#

1. Não armazene API key no front-end. Toda chamada deve ser feita pelo backend. Front-end que chama API direto vaza chave no DevTools.

2. Timeout client-side ≥ 15s. SEFAZ pode demorar. Timeout curto demais gera retries desnecessários.

3. Log estruturado. Salve request_id, cached e timestamp da consulta na sua base — útil para auditoria, troubleshooting e suporte.

4. Validação de input. CNPJ com dígito verificador errado, UF inválida, CPF de 10 dígitos — valide antes de chamar a API, economiza cota.

5. Trate `results` como array. Mesmo quando você espera 1 resultado, alguns CPFs de produtor rural retornam múltiplas IEs (propriedades em municípios diferentes do mesmo estado). Use results[0] defensivamente.

6. Use o dashboard para casos pontuais. Antes de codar a integração, valide o caso de uso no dashboard FiscalAPI — mesma API por trás, zero código.

Perguntas frequentes#

A API funciona para CPF de produtor rural? Sim. Use o parâmetro cpf em vez de cnpj. A resposta indica tipo_ie: "IE de Produtor Rural" quando o cadastro é dessa categoria.

Qual o limite de requisições por minuto? Usuários autenticados (com API key) seguem o rate limit do plano contratado. Usuários demo (sem API key) podem fazer no máximo 3 consultas por minuto por IP, e recebem dados parcialmente mascarados.

E se eu não souber a UF da empresa? A API exige uf. Para descobrir a UF a partir do CNPJ, faça primeiro uma consulta CNPJ na Receita Federal (ou pelo dashboard FiscalAPI) e use o estado da matriz ou filial relevante.

Existe SDK oficial? A API REST é simples o suficiente para integrar com o cliente HTTP nativo de qualquer linguagem. Os exemplos em Node.js e Python deste artigo são autocontidos.

Como migrar de outro provedor (SINTEGRA-WS, Infosimples, etc.)? A estrutura de query é parecida; o que muda são os nomes dos campos de resposta. Mapear results[0].situacao_ie → o equivalente no outro provedor costuma ser um trabalho curto.

A FiscalAPI revende dados ou usa para outros fins? Não. Dados consultados são exclusivos do cliente que fez a consulta. Para detalhes, ver os termos no site.

Próximo passo#

Conheça os planos da FiscalAPI — a partir de R$ 19,99/mês com dashboard sem código, API integrada para os 27 estados, documentação em PT-BR. Para começar a testar antes de assinar, use o demo público no dashboard (3 consultas/minuto por IP). Documentação técnica em docs.fiscalapi.com.br.

Artigos relacionados#

• Como Consultar Inscrição Estadual em 2026: Guia Definitivo
• Como integrar a API FiscalAPI em 5 minutos
• Situação Cadastral da Inscrição Estadual: o que cada status significa
• Consulta SINTEGRA: como consultar a Inscrição Estadual nos 27 estados
• Por que sua consulta de CNPJ está desatualizada (e como obter o dado ao vivo)