iptuapi

IPTU API - JavaScript/TypeScript SDK

SDK oficial JavaScript/TypeScript para integracao com a IPTU API. Acesso a dados de IPTU de Sao Paulo, Belo Horizonte e Recife.

Instalacao

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

Uso Rapido

import { IPTUClient } from 'iptuapi';

const client = new IPTUClient('sua_api_key');

// Consulta por endereco
const resultado = await client.consultaEndereco('Avenida Paulista', '1000');
console.log(resultado);

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

Configuracao

Cliente Basico

import { IPTUClient } from 'iptuapi';

const client = new IPTUClient('sua_api_key');

Configuracao Avancada

import { IPTUClient, ClientConfig, RetryConfig } from 'iptuapi';

const retryConfig: RetryConfig = {
  maxRetries: 5,
  initialDelayMs: 1000,
  maxDelayMs: 30000,
  backoffFactor: 2.0,
  retryableStatuses: [429, 500, 502, 503, 504]
};

const config: ClientConfig = {
  baseUrl: 'https://iptuapi.com.br/api/v1',
  timeout: 60000,
  retryConfig,
  logger: console // ou seu logger customizado
};

const client = new IPTUClient('sua_api_key', config);

Logging Customizado

import { IPTUClient, Logger } from 'iptuapi';

const customLogger: Logger = {
  debug: (msg, meta) => console.debug(`[IPTU] ${msg}`, meta),
  info: (msg, meta) => console.info(`[IPTU] ${msg}`, meta),
  warn: (msg, meta) => console.warn(`[IPTU] ${msg}`, meta),
  error: (msg, meta) => console.error(`[IPTU] ${msg}`, meta)
};

const client = new IPTUClient('sua_api_key', { logger: customLogger });

Endpoints da API

Consultas (Todos os Planos)

// Consulta por endereco
const resultado = await client.consultaEndereco('Avenida Paulista', '1000', 'sp');

// Consulta por CEP
const resultado = await client.consultaCEP('01310-100', 'sp');

// Consulta por coordenadas (zoneamento)
const resultado = await client.consultaZoneamento(-23.5505, -46.6333);

Consultas Avancadas (Starter+)

// Consulta por numero SQL
const resultado = await client.consultaSQL('100-01-001-001', 'sp');

// Historico de valores IPTU
const historico = await client.dadosIPTUHistorico('100-01-001-001', 'sp');

// Consulta CNPJ
const empresa = await client.dadosCNPJ('12345678000100');

// Correcao monetaria IPCA
const corrigido = await client.dadosIPCACorrigir(100000, '2020-01', '2024-01');

Valuation (Pro+)

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

// Buscar comparaveis
const comparaveis = await client.valuationComparables({
  bairro: 'Pinheiros',
  areaMin: 150,
  areaMax: 250,
  cidade: 'sp',
  limit: 10
});

Batch Operations (Enterprise)

// Valuation em lote (ate 100 imoveis)
const imoveis = [
  { area_terreno: 250, area_construida: 180, bairro: 'Pinheiros' },
  { area_terreno: 300, area_construida: 200, bairro: 'Moema' }
];
const resultados = await client.valuationBatch(imoveis);

Tratamento de Erros

import {
  IPTUClient,
  IPTUAPIError,
  AuthenticationError,
  ForbiddenError,
  NotFoundError,
  RateLimitError,
  ValidationError,
  ServerError,
  TimeoutError,
  NetworkError
} from 'iptuapi';

const client = new IPTUClient('sua_api_key');

try {
  const resultado = await client.consultaEndereco('Rua Teste', '100');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.log('API Key invalida');
  } else if (error instanceof ForbiddenError) {
    console.log(`Plano nao autorizado. Requer: ${error.requiredPlan}`);
  } else if (error instanceof NotFoundError) {
    console.log('Imovel nao encontrado');
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limit excedido. Retry em ${error.retryAfter}s`);
  } else if (error instanceof ValidationError) {
    console.log('Parametros invalidos:', error.errors);
  } else if (error instanceof ServerError) {
    console.log('Erro no servidor (retryable)');
  } else if (error instanceof TimeoutError) {
    console.log(`Timeout apos ${error.timeoutMs}ms`);
  } else if (error instanceof NetworkError) {
    console.log('Erro de conexao');
  } else if (error instanceof IPTUAPIError) {
    console.log(`Erro: ${error.message}, Request ID: ${error.requestId}`);
  }
}

Propriedades dos Erros

try {
  const resultado = await client.consultaEndereco('Rua Teste', '100');
} catch (error) {
  if (error instanceof IPTUAPIError) {
    console.log(`Status Code: ${error.statusCode}`);
    console.log(`Request ID: ${error.requestId}`);
    console.log(`Retryable: ${error.isRetryable}`);
  }
}

Rate Limiting

// Verificar rate limit apos requisicao
const rateLimit = client.getRateLimitInfo();
if (rateLimit) {
  console.log(`Limite: ${rateLimit.limit}`);
  console.log(`Restantes: ${rateLimit.remaining}`);
  console.log(`Reset em: ${new Date(rateLimit.reset * 1000)}`);
}

// ID da ultima requisicao (util para suporte)
console.log(`Request ID: ${client.getLastRequestId()}`);

Tipos TypeScript

import type {
  ClientConfig,
  RetryConfig,
  RateLimitInfo,
  PropertyData,
  ValuationParams,
  ValuationResult,
  ComparableProperty,
  ZoningInfo,
  IPTUHistoryItem
} from 'iptuapi';

// Exemplo de uso com tipos
const config: ClientConfig = {
  timeout: 30000
};

const params: ValuationParams = {
  area_terreno: 250,
  area_construida: 180,
  bairro: 'Pinheiros'
};

const resultado: ValuationResult = await client.valuationEstimate(params);

Browser Support

O SDK funciona tanto em Node.js quanto em browsers modernos:

<script type="module">
  import { IPTUClient } from 'https://unpkg.com/iptuapi@latest/dist/browser.js';

  const client = new IPTUClient('sua_api_key');
  const resultado = await client.consultaEndereco('Avenida Paulista', '1000');
  console.log(resultado);
</script>

Testes

# Rodar testes
npm test

# Watch mode
npm run test:watch

# Coverage
npm run test:coverage

Cidades Suportadas

Codigo	Cidade
sp	Sao Paulo
bh	Belo Horizonte
recife	Recife

Licenca

MIT License - veja LICENSE para detalhes.

Links

• Documentacao
• API Reference
• Portal do Desenvolvedor