iptuapi

IPTU API - JavaScript/TypeScript SDK

SDK oficial para integração com a IPTU API - Dados de IPTU de São Paulo e Belo Horizonte.

Instalação

npm install iptuapi
# ou
yarn add iptuapi
# ou
pnpm add iptuapi

Cidades Suportadas

Cidade	Código	Identificador
São Paulo	sao_paulo	Número SQL
Belo Horizonte	belo_horizonte	Índice Cadastral

Uso Rápido

import { IPTUClient } from 'iptuapi';

const client = new IPTUClient('sua_api_key');

// Consulta por endereço (São Paulo - endpoint legado)
const resultado = await client.consultaEndereco('Avenida Paulista', '1000');
console.log(resultado);

// Consulta por SQL (Starter+)
const dados = await client.consultaSQL('100-01-001-001');

Consulta Multi-Cidade (Novo!)

import { IPTUClient, Cidade } from 'iptuapi';

const client = new IPTUClient('sua_api_key');

// São Paulo - busca por endereço
const resultadosSP = await client.consultaIPTU('sao_paulo', 'Avenida Paulista', 1000, 2024);
for (const imovel of resultadosSP) {
  console.log(`SQL: ${imovel.sql}, Valor Venal: R$ ${imovel.valor_venal.toLocaleString()}`);
}

// Belo Horizonte - busca por endereço
const resultadosBH = await client.consultaIPTU('belo_horizonte', 'Afonso Pena', undefined, 2024);
for (const imovel of resultadosBH) {
  console.log(`Índice: ${imovel.sql}, Valor Venal: R$ ${imovel.valor_venal.toLocaleString()}`);
}

// Busca por identificador único
// São Paulo (SQL)
const dadosSP = await client.consultaIPTUSQL('sao_paulo', '00904801381');

// Belo Horizonte (Índice Cadastral)
const dadosBH = await client.consultaIPTUSQL('belo_horizonte', '007028 005 0086');

Avaliação de Mercado (Pro+)

const avaliacao = await client.valuationEstimate({
  area_terreno: 250,
  area_construida: 180,
  bairro: 'Pinheiros',
  zona: 'ZM',
  tipo_uso: 'Residencial',
  tipo_padrao: 'Médio',
  ano_construcao: 2010,
});
console.log(`Valor estimado: R$ ${avaliacao.valor_estimado.toLocaleString()}`);

Tratamento de Erros

import { IPTUClient, NotFoundError, RateLimitError } from 'iptuapi';

const client = new IPTUClient('sua_api_key');

try {
  const resultado = await client.consultaIPTU('sao_paulo', 'Rua Inexistente');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Imóvel não encontrado');
  } else if (error instanceof RateLimitError) {
    console.log('Limite de requisições excedido');
  }
}

Tipos TypeScript

O SDK inclui tipos TypeScript completos:

import type {
  Cidade,
  ConsultaEnderecoResult,
  ConsultaIPTUResult,
  ConsultaSQLResult,
  ValuationParams,
  ValuationResult,
} from 'iptuapi';

Documentação

Acesse a documentação completa em iptuapi.com.br/docs