iptuapi 1.0.0 → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +43 -4
- package/dist/index.d.mts +45 -1
- package/dist/index.d.ts +45 -1
- package/dist/index.js +40 -0
- package/dist/index.mjs +40 -0
- package/package.json +4 -2
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# IPTU API - JavaScript/TypeScript SDK
|
|
2
2
|
|
|
3
|
-
SDK oficial para integração com a IPTU API.
|
|
3
|
+
SDK oficial para integração com a IPTU API - Dados de IPTU de São Paulo e Belo Horizonte.
|
|
4
4
|
|
|
5
5
|
## Instalação
|
|
6
6
|
|
|
@@ -12,6 +12,13 @@ yarn add iptuapi
|
|
|
12
12
|
pnpm add iptuapi
|
|
13
13
|
```
|
|
14
14
|
|
|
15
|
+
## Cidades Suportadas
|
|
16
|
+
|
|
17
|
+
| Cidade | Código | Identificador |
|
|
18
|
+
|--------|--------|---------------|
|
|
19
|
+
| São Paulo | `sao_paulo` | Número SQL |
|
|
20
|
+
| Belo Horizonte | `belo_horizonte` | Índice Cadastral |
|
|
21
|
+
|
|
15
22
|
## Uso Rápido
|
|
16
23
|
|
|
17
24
|
```typescript
|
|
@@ -19,14 +26,44 @@ import { IPTUClient } from 'iptuapi';
|
|
|
19
26
|
|
|
20
27
|
const client = new IPTUClient('sua_api_key');
|
|
21
28
|
|
|
22
|
-
// Consulta por endereço
|
|
29
|
+
// Consulta por endereço (São Paulo - endpoint legado)
|
|
23
30
|
const resultado = await client.consultaEndereco('Avenida Paulista', '1000');
|
|
24
31
|
console.log(resultado);
|
|
25
32
|
|
|
26
33
|
// Consulta por SQL (Starter+)
|
|
27
34
|
const dados = await client.consultaSQL('100-01-001-001');
|
|
35
|
+
```
|
|
28
36
|
|
|
29
|
-
|
|
37
|
+
## Consulta Multi-Cidade (Novo!)
|
|
38
|
+
|
|
39
|
+
```typescript
|
|
40
|
+
import { IPTUClient, Cidade } from 'iptuapi';
|
|
41
|
+
|
|
42
|
+
const client = new IPTUClient('sua_api_key');
|
|
43
|
+
|
|
44
|
+
// São Paulo - busca por endereço
|
|
45
|
+
const resultadosSP = await client.consultaIPTU('sao_paulo', 'Avenida Paulista', 1000, 2024);
|
|
46
|
+
for (const imovel of resultadosSP) {
|
|
47
|
+
console.log(`SQL: ${imovel.sql}, Valor Venal: R$ ${imovel.valor_venal.toLocaleString()}`);
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
// Belo Horizonte - busca por endereço
|
|
51
|
+
const resultadosBH = await client.consultaIPTU('belo_horizonte', 'Afonso Pena', undefined, 2024);
|
|
52
|
+
for (const imovel of resultadosBH) {
|
|
53
|
+
console.log(`Índice: ${imovel.sql}, Valor Venal: R$ ${imovel.valor_venal.toLocaleString()}`);
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
// Busca por identificador único
|
|
57
|
+
// São Paulo (SQL)
|
|
58
|
+
const dadosSP = await client.consultaIPTUSQL('sao_paulo', '00904801381');
|
|
59
|
+
|
|
60
|
+
// Belo Horizonte (Índice Cadastral)
|
|
61
|
+
const dadosBH = await client.consultaIPTUSQL('belo_horizonte', '007028 005 0086');
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Avaliação de Mercado (Pro+)
|
|
65
|
+
|
|
66
|
+
```typescript
|
|
30
67
|
const avaliacao = await client.valuationEstimate({
|
|
31
68
|
area_terreno: 250,
|
|
32
69
|
area_construida: 180,
|
|
@@ -47,7 +84,7 @@ import { IPTUClient, NotFoundError, RateLimitError } from 'iptuapi';
|
|
|
47
84
|
const client = new IPTUClient('sua_api_key');
|
|
48
85
|
|
|
49
86
|
try {
|
|
50
|
-
const resultado = await client.
|
|
87
|
+
const resultado = await client.consultaIPTU('sao_paulo', 'Rua Inexistente');
|
|
51
88
|
} catch (error) {
|
|
52
89
|
if (error instanceof NotFoundError) {
|
|
53
90
|
console.log('Imóvel não encontrado');
|
|
@@ -63,7 +100,9 @@ O SDK inclui tipos TypeScript completos:
|
|
|
63
100
|
|
|
64
101
|
```typescript
|
|
65
102
|
import type {
|
|
103
|
+
Cidade,
|
|
66
104
|
ConsultaEnderecoResult,
|
|
105
|
+
ConsultaIPTUResult,
|
|
67
106
|
ConsultaSQLResult,
|
|
68
107
|
ValuationParams,
|
|
69
108
|
ValuationResult,
|
package/dist/index.d.mts
CHANGED
|
@@ -11,6 +11,8 @@
|
|
|
11
11
|
* const resultado = await client.consultaEndereco('Avenida Paulista', '1000');
|
|
12
12
|
* ```
|
|
13
13
|
*/
|
|
14
|
+
/** Cidades suportadas pela API */
|
|
15
|
+
type Cidade = 'sao_paulo' | 'belo_horizonte' | 'recife';
|
|
14
16
|
interface ConsultaEnderecoResult {
|
|
15
17
|
sql: string;
|
|
16
18
|
logradouro: string;
|
|
@@ -22,6 +24,32 @@ interface ConsultaEnderecoResult {
|
|
|
22
24
|
tipo_uso: string;
|
|
23
25
|
zona: string;
|
|
24
26
|
}
|
|
27
|
+
/** Resultado da consulta multi-cidade */
|
|
28
|
+
interface ConsultaIPTUResult {
|
|
29
|
+
sql: string;
|
|
30
|
+
ano: number;
|
|
31
|
+
logradouro: string;
|
|
32
|
+
numero: number | string | null;
|
|
33
|
+
complemento: string | null;
|
|
34
|
+
bairro: string | null;
|
|
35
|
+
cep: string;
|
|
36
|
+
area_terreno: number | null;
|
|
37
|
+
area_construida: number | null;
|
|
38
|
+
valor_terreno: number | null;
|
|
39
|
+
valor_construcao: number | null;
|
|
40
|
+
valor_venal: number;
|
|
41
|
+
valor_imovel?: number | null;
|
|
42
|
+
valor_iptu?: number | null;
|
|
43
|
+
finalidade: string | null;
|
|
44
|
+
tipo_construcao: string | null;
|
|
45
|
+
ano_construcao: number | null;
|
|
46
|
+
pavimentos?: number | null;
|
|
47
|
+
fracao_ideal?: string | null;
|
|
48
|
+
latitude?: number | null;
|
|
49
|
+
longitude?: number | null;
|
|
50
|
+
cidade: string;
|
|
51
|
+
fonte: string;
|
|
52
|
+
}
|
|
25
53
|
interface ConsultaSQLResult {
|
|
26
54
|
sql: string;
|
|
27
55
|
ano: number;
|
|
@@ -87,10 +115,26 @@ declare class IPTUClient {
|
|
|
87
115
|
* Busca dados de IPTU por número SQL (Starter+)
|
|
88
116
|
*/
|
|
89
117
|
consultaSQL(sql: string): Promise<ConsultaSQLResult>;
|
|
118
|
+
/**
|
|
119
|
+
* Busca dados de IPTU por endereço para qualquer cidade suportada
|
|
120
|
+
* @param cidade - Cidade ("sao_paulo", "belo_horizonte" ou "recife")
|
|
121
|
+
* @param logradouro - Nome da rua/avenida
|
|
122
|
+
* @param numero - Número do imóvel (opcional)
|
|
123
|
+
* @param ano - Ano de referência (default: 2025)
|
|
124
|
+
* @param limit - Limite de resultados (default: 20)
|
|
125
|
+
*/
|
|
126
|
+
consultaIPTU(cidade: Cidade, logradouro: string, numero?: number, ano?: number, limit?: number): Promise<ConsultaIPTUResult[]>;
|
|
127
|
+
/**
|
|
128
|
+
* Busca dados de IPTU pelo identificador único do imóvel
|
|
129
|
+
* @param cidade - Cidade ("sao_paulo", "belo_horizonte" ou "recife")
|
|
130
|
+
* @param identificador - Número SQL (SP), Índice Cadastral (BH) ou Contribuinte (Recife)
|
|
131
|
+
* @param ano - Ano de referência (opcional)
|
|
132
|
+
*/
|
|
133
|
+
consultaIPTUSQL(cidade: Cidade, identificador: string, ano?: number): Promise<ConsultaIPTUResult[]>;
|
|
90
134
|
/**
|
|
91
135
|
* Estima o valor de mercado do imóvel (Pro+)
|
|
92
136
|
*/
|
|
93
137
|
valuationEstimate(params: ValuationParams): Promise<ValuationResult>;
|
|
94
138
|
}
|
|
95
139
|
|
|
96
|
-
export { AuthenticationError, type ConsultaEnderecoResult, type ConsultaSQLResult, ForbiddenError, IPTUAPIError, IPTUClient, type IPTUClientOptions, NotFoundError, RateLimitError, type ValuationParams, type ValuationResult, IPTUClient as default };
|
|
140
|
+
export { AuthenticationError, type Cidade, type ConsultaEnderecoResult, type ConsultaIPTUResult, type ConsultaSQLResult, ForbiddenError, IPTUAPIError, IPTUClient, type IPTUClientOptions, NotFoundError, RateLimitError, type ValuationParams, type ValuationResult, IPTUClient as default };
|
package/dist/index.d.ts
CHANGED
|
@@ -11,6 +11,8 @@
|
|
|
11
11
|
* const resultado = await client.consultaEndereco('Avenida Paulista', '1000');
|
|
12
12
|
* ```
|
|
13
13
|
*/
|
|
14
|
+
/** Cidades suportadas pela API */
|
|
15
|
+
type Cidade = 'sao_paulo' | 'belo_horizonte' | 'recife';
|
|
14
16
|
interface ConsultaEnderecoResult {
|
|
15
17
|
sql: string;
|
|
16
18
|
logradouro: string;
|
|
@@ -22,6 +24,32 @@ interface ConsultaEnderecoResult {
|
|
|
22
24
|
tipo_uso: string;
|
|
23
25
|
zona: string;
|
|
24
26
|
}
|
|
27
|
+
/** Resultado da consulta multi-cidade */
|
|
28
|
+
interface ConsultaIPTUResult {
|
|
29
|
+
sql: string;
|
|
30
|
+
ano: number;
|
|
31
|
+
logradouro: string;
|
|
32
|
+
numero: number | string | null;
|
|
33
|
+
complemento: string | null;
|
|
34
|
+
bairro: string | null;
|
|
35
|
+
cep: string;
|
|
36
|
+
area_terreno: number | null;
|
|
37
|
+
area_construida: number | null;
|
|
38
|
+
valor_terreno: number | null;
|
|
39
|
+
valor_construcao: number | null;
|
|
40
|
+
valor_venal: number;
|
|
41
|
+
valor_imovel?: number | null;
|
|
42
|
+
valor_iptu?: number | null;
|
|
43
|
+
finalidade: string | null;
|
|
44
|
+
tipo_construcao: string | null;
|
|
45
|
+
ano_construcao: number | null;
|
|
46
|
+
pavimentos?: number | null;
|
|
47
|
+
fracao_ideal?: string | null;
|
|
48
|
+
latitude?: number | null;
|
|
49
|
+
longitude?: number | null;
|
|
50
|
+
cidade: string;
|
|
51
|
+
fonte: string;
|
|
52
|
+
}
|
|
25
53
|
interface ConsultaSQLResult {
|
|
26
54
|
sql: string;
|
|
27
55
|
ano: number;
|
|
@@ -87,10 +115,26 @@ declare class IPTUClient {
|
|
|
87
115
|
* Busca dados de IPTU por número SQL (Starter+)
|
|
88
116
|
*/
|
|
89
117
|
consultaSQL(sql: string): Promise<ConsultaSQLResult>;
|
|
118
|
+
/**
|
|
119
|
+
* Busca dados de IPTU por endereço para qualquer cidade suportada
|
|
120
|
+
* @param cidade - Cidade ("sao_paulo", "belo_horizonte" ou "recife")
|
|
121
|
+
* @param logradouro - Nome da rua/avenida
|
|
122
|
+
* @param numero - Número do imóvel (opcional)
|
|
123
|
+
* @param ano - Ano de referência (default: 2025)
|
|
124
|
+
* @param limit - Limite de resultados (default: 20)
|
|
125
|
+
*/
|
|
126
|
+
consultaIPTU(cidade: Cidade, logradouro: string, numero?: number, ano?: number, limit?: number): Promise<ConsultaIPTUResult[]>;
|
|
127
|
+
/**
|
|
128
|
+
* Busca dados de IPTU pelo identificador único do imóvel
|
|
129
|
+
* @param cidade - Cidade ("sao_paulo", "belo_horizonte" ou "recife")
|
|
130
|
+
* @param identificador - Número SQL (SP), Índice Cadastral (BH) ou Contribuinte (Recife)
|
|
131
|
+
* @param ano - Ano de referência (opcional)
|
|
132
|
+
*/
|
|
133
|
+
consultaIPTUSQL(cidade: Cidade, identificador: string, ano?: number): Promise<ConsultaIPTUResult[]>;
|
|
90
134
|
/**
|
|
91
135
|
* Estima o valor de mercado do imóvel (Pro+)
|
|
92
136
|
*/
|
|
93
137
|
valuationEstimate(params: ValuationParams): Promise<ValuationResult>;
|
|
94
138
|
}
|
|
95
139
|
|
|
96
|
-
export { AuthenticationError, type ConsultaEnderecoResult, type ConsultaSQLResult, ForbiddenError, IPTUAPIError, IPTUClient, type IPTUClientOptions, NotFoundError, RateLimitError, type ValuationParams, type ValuationResult, IPTUClient as default };
|
|
140
|
+
export { AuthenticationError, type Cidade, type ConsultaEnderecoResult, type ConsultaIPTUResult, type ConsultaSQLResult, ForbiddenError, IPTUAPIError, IPTUClient, type IPTUClientOptions, NotFoundError, RateLimitError, type ValuationParams, type ValuationResult, IPTUClient as default };
|
package/dist/index.js
CHANGED
|
@@ -132,6 +132,46 @@ var IPTUClient = class {
|
|
|
132
132
|
async consultaSQL(sql) {
|
|
133
133
|
return this.request("GET", "/consulta/sql", { sql });
|
|
134
134
|
}
|
|
135
|
+
/**
|
|
136
|
+
* Busca dados de IPTU por endereço para qualquer cidade suportada
|
|
137
|
+
* @param cidade - Cidade ("sao_paulo", "belo_horizonte" ou "recife")
|
|
138
|
+
* @param logradouro - Nome da rua/avenida
|
|
139
|
+
* @param numero - Número do imóvel (opcional)
|
|
140
|
+
* @param ano - Ano de referência (default: 2025)
|
|
141
|
+
* @param limit - Limite de resultados (default: 20)
|
|
142
|
+
*/
|
|
143
|
+
async consultaIPTU(cidade, logradouro, numero, ano = 2025, limit = 20) {
|
|
144
|
+
const params = {
|
|
145
|
+
logradouro,
|
|
146
|
+
ano: ano.toString(),
|
|
147
|
+
limit: limit.toString()
|
|
148
|
+
};
|
|
149
|
+
if (numero !== void 0) {
|
|
150
|
+
params.numero = numero.toString();
|
|
151
|
+
}
|
|
152
|
+
return this.request(
|
|
153
|
+
"GET",
|
|
154
|
+
`/dados/iptu/${cidade}/endereco`,
|
|
155
|
+
params
|
|
156
|
+
);
|
|
157
|
+
}
|
|
158
|
+
/**
|
|
159
|
+
* Busca dados de IPTU pelo identificador único do imóvel
|
|
160
|
+
* @param cidade - Cidade ("sao_paulo", "belo_horizonte" ou "recife")
|
|
161
|
+
* @param identificador - Número SQL (SP), Índice Cadastral (BH) ou Contribuinte (Recife)
|
|
162
|
+
* @param ano - Ano de referência (opcional)
|
|
163
|
+
*/
|
|
164
|
+
async consultaIPTUSQL(cidade, identificador, ano) {
|
|
165
|
+
const params = {};
|
|
166
|
+
if (ano !== void 0) {
|
|
167
|
+
params.ano = ano.toString();
|
|
168
|
+
}
|
|
169
|
+
return this.request(
|
|
170
|
+
"GET",
|
|
171
|
+
`/dados/iptu/${cidade}/sql/${encodeURIComponent(identificador)}`,
|
|
172
|
+
params
|
|
173
|
+
);
|
|
174
|
+
}
|
|
135
175
|
/**
|
|
136
176
|
* Estima o valor de mercado do imóvel (Pro+)
|
|
137
177
|
*/
|
package/dist/index.mjs
CHANGED
|
@@ -102,6 +102,46 @@ var IPTUClient = class {
|
|
|
102
102
|
async consultaSQL(sql) {
|
|
103
103
|
return this.request("GET", "/consulta/sql", { sql });
|
|
104
104
|
}
|
|
105
|
+
/**
|
|
106
|
+
* Busca dados de IPTU por endereço para qualquer cidade suportada
|
|
107
|
+
* @param cidade - Cidade ("sao_paulo", "belo_horizonte" ou "recife")
|
|
108
|
+
* @param logradouro - Nome da rua/avenida
|
|
109
|
+
* @param numero - Número do imóvel (opcional)
|
|
110
|
+
* @param ano - Ano de referência (default: 2025)
|
|
111
|
+
* @param limit - Limite de resultados (default: 20)
|
|
112
|
+
*/
|
|
113
|
+
async consultaIPTU(cidade, logradouro, numero, ano = 2025, limit = 20) {
|
|
114
|
+
const params = {
|
|
115
|
+
logradouro,
|
|
116
|
+
ano: ano.toString(),
|
|
117
|
+
limit: limit.toString()
|
|
118
|
+
};
|
|
119
|
+
if (numero !== void 0) {
|
|
120
|
+
params.numero = numero.toString();
|
|
121
|
+
}
|
|
122
|
+
return this.request(
|
|
123
|
+
"GET",
|
|
124
|
+
`/dados/iptu/${cidade}/endereco`,
|
|
125
|
+
params
|
|
126
|
+
);
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* Busca dados de IPTU pelo identificador único do imóvel
|
|
130
|
+
* @param cidade - Cidade ("sao_paulo", "belo_horizonte" ou "recife")
|
|
131
|
+
* @param identificador - Número SQL (SP), Índice Cadastral (BH) ou Contribuinte (Recife)
|
|
132
|
+
* @param ano - Ano de referência (opcional)
|
|
133
|
+
*/
|
|
134
|
+
async consultaIPTUSQL(cidade, identificador, ano) {
|
|
135
|
+
const params = {};
|
|
136
|
+
if (ano !== void 0) {
|
|
137
|
+
params.ano = ano.toString();
|
|
138
|
+
}
|
|
139
|
+
return this.request(
|
|
140
|
+
"GET",
|
|
141
|
+
`/dados/iptu/${cidade}/sql/${encodeURIComponent(identificador)}`,
|
|
142
|
+
params
|
|
143
|
+
);
|
|
144
|
+
}
|
|
105
145
|
/**
|
|
106
146
|
* Estima o valor de mercado do imóvel (Pro+)
|
|
107
147
|
*/
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "iptuapi",
|
|
3
|
-
"version": "1.
|
|
4
|
-
"description": "SDK oficial para a IPTU API - Dados de IPTU de São Paulo",
|
|
3
|
+
"version": "1.2.0",
|
|
4
|
+
"description": "SDK oficial para a IPTU API - Dados de IPTU de São Paulo, Belo Horizonte e Recife",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"module": "dist/index.mjs",
|
|
7
7
|
"types": "dist/index.d.ts",
|
|
@@ -16,6 +16,8 @@
|
|
|
16
16
|
"iptu",
|
|
17
17
|
"api",
|
|
18
18
|
"são paulo",
|
|
19
|
+
"belo horizonte",
|
|
20
|
+
"recife",
|
|
19
21
|
"imóveis",
|
|
20
22
|
"dados",
|
|
21
23
|
"typescript"
|