Documentação da API

Guia completo para integrar a IPTU API em sua aplicação.

Autenticação

Todas as requisições devem incluir sua API Key no header X-API-Key.

curl -X GET "http://localhost:8000/api/v1/consulta/endereco?logradouro=paulista" \
  -H "X-API-Key: SUA_API_KEY"

URL Base

http://localhost:8000/api/v1

Endpoints

GET/consulta/endereco

Busca dados de IPTU por endereço

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`logradouro`	string	Sim	Nome da rua
`numero`	string	Não	Número do imóvel

Exemplo

curl -X GET "http://localhost:8000/api/v1/consulta/endereco?logradouro=paulista&numero=1000" \
  -H "X-API-Key: SUA_API_KEY"

Resposta

{
  "sql": "100-01-001-001",
  "logradouro": "AVENIDA PAULISTA",
  "numero": "1000",
  "bairro": "BELA VISTA",
  "cep": "01310-100",
  "area_terreno": 500.0,
  "area_construida": 1200.0,
  "tipo_uso": "Comercial",
  "zona": "ZC"
}

GET/consulta/sqlStarter+

Busca dados de IPTU por número SQL

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`sql`	string	Sim	Número SQL do imóvel

Exemplo

curl -X GET "http://localhost:8000/api/v1/consulta/sql?sql=100-01-001-001" \
  -H "X-API-Key: SUA_API_KEY"

Resposta

{
  "sql": "100-01-001-001",
  "ano": 2024,
  "valor_venal": 1500000.0,
  "valor_venal_terreno": 800000.0,
  "valor_venal_construcao": 700000.0,
  "iptu_valor": 15000.0,
  ...
}

POST/valuation/estimatePro+

Estima o valor de mercado do imóvel usando ML

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`area_terreno`	number	Sim	Área do terreno em m²
`area_construida`	number	Sim	Área construída em m²
`bairro`	string	Sim	Nome do bairro
`zona`	string	Sim	Zona de uso
`tipo_uso`	string	Sim	Tipo de uso
`tipo_padrao`	string	Sim	Padrão construtivo
`ano_construcao`	number	Não	Ano de construção

Exemplo

curl -X POST "http://localhost:8000/api/v1/valuation/estimate" \
  -H "X-API-Key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "area_terreno": 250,
    "area_construida": 180,
    "bairro": "Pinheiros",
    "zona": "ZM",
    "tipo_uso": "Residencial",
    "tipo_padrao": "Médio",
    "ano_construcao": 2010
  }'

Resposta

{
  "success": true,
  "valor_estimado": 1010464.81,
  "valor_minimo": 909418.31,
  "valor_maximo": 1111511.37,
  "valor_m2": 5613.69,
  "confianca": 0.7,
  "modelo_versao": "1.0.0"
}

Rate Limiting

Cada plano tem um limite mensal de requisições:

Plano	Limite/mês	Rate/min
Free	10	10
Starter	500	100
Pro	5.000	500
Enterprise	100.000	10.000

Códigos de Erro

Código	Descrição
`400`	Requisição inválida
`401`	API Key inválida ou expirada
`403`	Plano não autorizado para este recurso
`404`	Recurso não encontrado
`429`	Limite de requisições excedido
`500`	Erro interno do servidor

SDKs e Bibliotecas

Em breve disponibilizaremos SDKs oficiais para:

Python
JavaScript/TypeScript
Go
PHP

Suporte

Precisa de ajuda? Entre em contato:

📧 Email: suporte@iptu-api.com.br
📚 API Docs: http://localhost:8000/docs