iptuapi 2.0.2 → 2.1.0

package/dist/index.d.mts

@@ -1,338 +1,518 @@
 /**
- * IPTU API - JavaScript/TypeScript SDK
- *
- * SDK oficial para integração com a IPTU API.
- * Suporta retry automático, logging e rate limit tracking.
- *
- * @example
- * ```typescript
- * import { IPTUClient } from 'iptuapi';
- *
- * const client = new IPTUClient('sua_api_key');
- * const resultado = await client.consultaEndereco('Avenida Paulista', '1000');
- * console.log(resultado);
- * ```
- *
- * @example
- * ```typescript
- * // Com configuração customizada
- * const client = new IPTUClient('sua_api_key', {
- *   timeout: 60000,
- *   retries: 5,
- *   logger: console,
- * });
- * ```
+ * Tipos e interfaces para a IPTU API.
  */
-type Cidade = 'sp' | 'bh' | 'recife';
-declare const CidadeEnum: {
-    readonly SAO_PAULO: Cidade;
-    readonly BELO_HORIZONTE: Cidade;
-    readonly RECIFE: Cidade;
-};
+interface RetryConfig {
+    maxRetries: number;
+    initialDelay: number;
+    maxDelay: number;
+    backoffFactor: number;
+    retryableStatusCodes: number[];
+}
+interface ClientConfig {
+    baseUrl: string;
+    timeout: number;
+    retryConfig: RetryConfig;
+}
+interface ClientOptions {
+    baseUrl?: string;
+    timeout?: number;
+    retryConfig?: Partial<RetryConfig>;
+}
 interface RateLimitInfo {
     limit: number;
     remaining: number;
-    reset: number;
-    resetDate: Date;
+    resetAt: Date;
 }
-interface ConsultaEnderecoParams {
-    logradouro: string;
-    numero?: string;
-    complemento?: string;
-    cidade?: Cidade;
-    incluirHistorico?: boolean;
-    incluirComparaveis?: boolean;
-    incluirZoneamento?: boolean;
-}
-interface ConsultaEnderecoResult {
+interface Imovel {
     sql: string;
     logradouro: string;
-    numero?: string;
-    complemento?: string;
-    bairro?: string;
+    numero: string;
+    bairro: string;
     cep?: string;
-    area_terreno?: number;
-    area_construida?: number;
-    valor_venal_terreno?: number;
-    valor_venal_construcao?: number;
-    valor_venal_total?: number;
-    iptu_valor?: number;
-    ano_construcao?: number;
-    tipo_uso?: string;
+    areaTerreno?: number;
+    areaConstruida?: number;
+    valorVenal?: number;
+    valorVenalTerreno?: number;
+    valorVenalConstrucao?: number;
+    anoConstrucao?: number;
+    uso?: string;
+    padrao?: string;
+    testada?: number;
+    fracaoIdeal?: number;
+    quantidadePavimentos?: number;
+}
+interface Zoneamento {
+    zona: string;
+    usoPermitido: string;
+    coeficienteAproveitamento?: number;
+    taxaOcupacao?: number;
+    gabarito?: number;
+    recuoFrontal?: number;
+    legislacao?: string;
+}
+interface Valuation {
+    valorEstimado: number;
+    valorMinimo: number;
+    valorMaximo: number;
+    confianca: number;
+    valorM2: number;
+    metodologia: string;
+    dataReferencia: string;
+}
+interface ValuationParams {
+    areaTerreno: number;
+    areaConstruida: number;
+    bairro: string;
+    cidade?: string;
     zona?: string;
-    historico?: HistoricoItem[];
-    comparaveis?: ComparavelItem[];
-    zoneamento?: ZoneamentoResult;
+    tipoUso?: string;
+    tipoPadrao?: string;
+    anoConstrucao?: number;
 }
-interface ConsultaSQLResult {
+interface Comparavel {
     sql: string;
-    ano?: number;
-    valor_venal?: number;
-    valor_venal_terreno?: number;
-    valor_venal_construcao?: number;
-    valor_venal_total?: number;
-    iptu_valor?: number;
-    logradouro?: string;
-    numero?: string;
-    bairro?: string;
-    area_terreno?: number;
-    area_construida?: number;
+    logradouro: string;
+    bairro: string;
+    areaConstruida: number;
+    valorVenal: number;
+    valorM2: number;
+    distanciaKm?: number;
 }
-interface HistoricoItem {
-    ano: number;
-    valor_venal_terreno?: number;
-    valor_venal_construcao?: number;
-    valor_venal_total?: number;
-    iptu_valor?: number;
+interface ComparablesParams {
+    bairro: string;
+    areaMin: number;
+    areaMax: number;
+    cidade?: string;
+    limit?: number;
 }
-interface ComparavelItem {
-    sql?: string;
-    logradouro?: string;
-    numero?: string;
-    bairro?: string;
-    area_terreno?: number;
-    area_construida?: number;
-    valor_venal_total?: number;
-    distancia_metros?: number;
+interface ITBIStatus {
+    protocolo: string;
+    status: string;
+    dataSolicitacao: string;
+    valorTransacao: number;
+    valorVenalReferencia: number;
+    baseCalculo: number;
+    aliquota: number;
+    valorITBI: number;
+    dataAprovacao?: string;
 }
-interface ZoneamentoResult {
-    zona?: string;
-    zona_descricao?: string;
-    coeficiente_aproveitamento_basico?: number;
-    coeficiente_aproveitamento_maximo?: number;
-    taxa_ocupacao_maxima?: number;
-    gabarito_maximo?: number;
+interface ITBICalculo {
+    sql: string;
+    valorTransacao: number;
+    valorVenalReferencia: number;
+    baseCalculo: number;
+    aliquota: number;
+    valorITBI: number;
+    isencaoAplicavel: boolean;
+    fundamentacaoLegal: string;
 }
-interface ValuationParams {
-    area_terreno: number;
-    area_construida: number;
-    bairro: string;
-    zona: string;
-    tipo_uso: string;
-    tipo_padrao: string;
-    ano_construcao?: number;
-    cidade?: Cidade;
-}
-interface ValuationResult {
-    valor_estimado: number;
-    valor_minimo?: number;
-    valor_maximo?: number;
-    confianca?: number;
-    metodo?: string;
-    comparaveis_utilizados?: number;
-    data_avaliacao?: string;
-}
-interface BatchValuationResult {
-    resultados: ValuationResult[];
-    total_processados: number;
-    total_erros: number;
-    erros?: Array<{
-        index: number;
-        error: string;
-    }>;
+interface ITBICalculoParams {
+    sql: string;
+    valorTransacao: number;
+    cidade?: string;
 }
-declare class IPTUAPIError extends Error {
-    readonly statusCode?: number;
-    readonly requestId?: string;
-    readonly responseBody?: Record<string, unknown>;
-    constructor(message: string, statusCode?: number, requestId?: string, responseBody?: Record<string, unknown>);
-    get isRetryable(): boolean;
+interface ITBIHistorico {
+    protocolo: string;
+    dataTransacao: string;
+    tipoTransacao: string;
+    valorTransacao: number;
+    valorITBI: number;
 }
-declare class AuthenticationError extends IPTUAPIError {
-    constructor(message?: string, requestId?: string, responseBody?: Record<string, unknown>);
+interface ITBIAliquota {
+    cidade: string;
+    aliquotaPadrao: number;
+    aliquotaFinanciamentoSFH: number;
+    valorMinimoIsencao: number;
+    baseLegal: string;
+    vigencia: string;
 }
-declare class ForbiddenError extends IPTUAPIError {
-    readonly requiredPlan?: string;
-    constructor(message?: string, requiredPlan?: string, requestId?: string, responseBody?: Record<string, unknown>);
+interface ITBIIsencao {
+    tipo: string;
+    descricao: string;
+    requisitos: string[];
+    baseLegal: string;
 }
-declare class NotFoundError extends IPTUAPIError {
-    constructor(message?: string, requestId?: string, responseBody?: Record<string, unknown>);
+interface Pessoa {
+    nome: string;
+    documento: string;
+    email?: string;
 }
-declare class RateLimitError extends IPTUAPIError {
-    readonly retryAfter?: number;
-    readonly limit?: number;
-    readonly remaining?: number;
-    constructor(message?: string, retryAfter?: number, limit?: number, remaining?: number, requestId?: string, responseBody?: Record<string, unknown>);
-    get isRetryable(): boolean;
+interface ITBIGuiaParams {
+    sql: string;
+    valorTransacao: number;
+    comprador: Pessoa;
+    vendedor: Pessoa;
+    cidade?: string;
 }
-declare class ValidationError extends IPTUAPIError {
-    readonly errors?: Array<{
-        field: string;
-        message: string;
-    }>;
-    constructor(message?: string, errors?: Array<{
-        field: string;
-        message: string;
-    }>, requestId?: string, responseBody?: Record<string, unknown>);
+interface ITBIGuia {
+    protocolo: string;
+    codigoBarras: string;
+    linhaDigitavel: string;
+    dataEmissao: string;
+    dataVencimento: string;
+    valorITBI: number;
 }
-declare class ServerError extends IPTUAPIError {
-    constructor(message?: string, statusCode?: number, requestId?: string, responseBody?: Record<string, unknown>);
-    get isRetryable(): boolean;
+interface ITBIValidacao {
+    protocolo: string;
+    valido: boolean;
+    pago: boolean;
+    dataPagamento?: string;
+    valorPago?: number;
 }
-declare class TimeoutError extends IPTUAPIError {
-    readonly timeoutMs?: number;
-    constructor(message?: string, timeoutMs?: number);
-    get isRetryable(): boolean;
+interface ITBISimularParams {
+    valorTransacao: number;
+    cidade?: string;
+    tipoFinanciamento?: 'sfh' | 'nao_sfh';
+    valorFinanciado?: number;
 }
-declare class NetworkError extends IPTUAPIError {
-    readonly originalError?: Error;
-    constructor(message?: string, originalError?: Error);
-    get isRetryable(): boolean;
+interface ITBISimulacao {
+    valorTransacao: number;
+    valorFinanciado: number;
+    valorNaoFinanciado: number;
+    aliquotaSFH: number;
+    aliquotaPadrao: number;
+    valorITBIFinanciado: number;
+    valorITBINaoFinanciado: number;
+    valorITBITotal: number;
+    economiaSFH: number;
 }
-interface Logger {
-    debug?(message: string, ...args: unknown[]): void;
-    info?(message: string, ...args: unknown[]): void;
-    warn?(message: string, ...args: unknown[]): void;
-    error?(message: string, ...args: unknown[]): void;
+interface EvaluateParams {
+    /** Numero SQL do imovel (alternativa ao endereco) */
+    sql?: string;
+    /** Nome da rua/avenida (alternativa ao SQL) */
+    logradouro?: string;
+    /** Numero do imovel */
+    numero?: number;
+    /** Apartamento, sala, etc. */
+    complemento?: string;
+    /** Bairro */
+    bairro?: string;
+    /** Codigo da cidade (sp, bh) */
+    cidade?: string;
+    /** Incluir estimativa baseada em ITBI */
+    incluirItbi?: boolean;
+    /** Incluir lista de imoveis comparaveis */
+    incluirComparaveis?: boolean;
 }
-interface RetryConfig {
-    /** Maximum number of retry attempts (default: 3) */
-    maxRetries: number;
-    /** Initial delay in ms between retries (default: 500) */
-    initialDelay: number;
-    /** Maximum delay in ms between retries (default: 10000) */
-    maxDelay: number;
-    /** Backoff factor (default: 2) */
-    backoffFactor: number;
-    /** Status codes that trigger retry (default: [429, 500, 502, 503, 504]) */
-    retryableStatuses: number[];
+interface AVMEstimate {
+    /** Valor estimado em R$ */
+    valorEstimado: number;
+    /** Valor minimo do intervalo */
+    valorMinimo: number;
+    /** Valor maximo do intervalo */
+    valorMaximo: number;
+    /** Valor por m2 */
+    valorM2: number;
+    /** Nivel de confianca (0-1) */
+    confianca: number;
+    /** Versao do modelo */
+    modeloVersao: string;
 }
-interface IPTUClientOptions {
-    /** Base URL for the API (default: https://iptuapi.com.br/api/v1) */
-    baseUrl?: string;
-    /** Request timeout in milliseconds (default: 30000) */
-    timeout?: number;
-    /** Retry configuration */
-    retry?: Partial<RetryConfig>;
-    /** Logger instance for debugging */
-    logger?: Logger;
-    /** Enable request logging (default: false) */
-    logRequests?: boolean;
-    /** Enable response logging (default: false) */
-    logResponses?: boolean;
-    /** Custom User-Agent header */
-    userAgent?: string;
+interface ITBIMarketEstimate {
+    /** Valor estimado em R$ */
+    valorEstimado: number;
+    /** Valor minimo da faixa */
+    faixaMinima: number;
+    /** Valor maximo da faixa */
+    faixaMaxima: number;
+    /** Valor por m2 (mediana) */
+    valorM2Mediana: number;
+    /** Total de transacoes analisadas */
+    totalTransacoes: number;
+    /** Periodo considerado */
+    periodo: string;
+    /** Fonte dos dados */
+    fonte: string;
+}
+interface FinalValuation {
+    /** Valor estimado final */
+    estimado: number;
+    /** Valor minimo */
+    minimo: number;
+    /** Valor maximo */
+    maximo: number;
+    /** Metodo utilizado (blend_avm_itbi, avm_only, itbi_only) */
+    metodo: string;
+    /** Peso do AVM no calculo (0-1) */
+    pesoAvm: number;
+    /** Peso do ITBI no calculo (0-1) */
+    pesoItbi: number;
+    /** Nivel de confianca */
+    confianca: number;
+    /** Nota explicativa */
+    nota?: string;
 }
+interface PropertyEvaluation {
+    /** Se a avaliacao foi bem sucedida */
+    success: boolean;
+    /** Dados cadastrais do imovel */
+    imovel: Record<string, unknown>;
+    /** Avaliacao pelo modelo ML (AVM) */
+    avaliacaoAvm?: AVMEstimate;
+    /** Avaliacao por transacoes ITBI reais */
+    avaliacaoItbi?: ITBIMarketEstimate;
+    /** Valor final combinado */
+    valorFinal: FinalValuation;
+    /** Imoveis comparaveis */
+    comparaveis?: Record<string, unknown>;
+    /** Metadados da avaliacao */
+    metadata: {
+        processadoEm: string;
+        fontes: string[];
+        cidade: string;
+    };
+}
+type Cidade = 'sp' | 'bh' | 'recife' | 'poa' | 'fortaleza' | 'curitiba' | 'rj' | 'brasilia';
+
+/**
+ * Cliente principal para a IPTU API.
+ */
+
+/**
+ * Cliente para interagir com a IPTU API.
+ */
 declare class IPTUClient {
     private readonly apiKey;
-    private readonly baseUrl;
-    private readonly timeout;
-    private readonly retryConfig;
-    private readonly logger?;
-    private readonly logRequests;
-    private readonly logResponses;
-    private readonly userAgent;
-    private _rateLimit?;
-    private _lastRequestId?;
-    constructor(apiKey: string, options?: IPTUClientOptions);
-    /** Rate limit info from last request */
-    get rateLimit(): RateLimitInfo | undefined;
-    /** Request ID from last request (useful for support) */
-    get lastRequestId(): string | undefined;
-    private log;
+    private readonly config;
+    private _rateLimitInfo;
+    private _lastRequestId;
+    /**
+     * Cria uma nova instancia do cliente.
+     *
+     * @param apiKey - Chave de API para autenticacao
+     * @param options - Opcoes de configuracao
+     */
+    constructor(apiKey: string, options?: ClientOptions);
+    /**
+     * Retorna informacoes do rate limit da ultima requisicao.
+     */
+    get rateLimitInfo(): RateLimitInfo | null;
+    /**
+     * Retorna o ID da ultima requisicao.
+     */
+    get lastRequestId(): string | null;
+    /**
+     * Executa uma requisicao HTTP com retry.
+     */
+    private makeRequest;
+    /**
+     * Atualiza informacoes de rate limit a partir dos headers.
+     */
+    private updateRateLimitInfo;
+    /**
+     * Converte resposta HTTP em excecao apropriada.
+     */
+    private handleError;
+    /**
+     * Aguarda um tempo em milissegundos.
+     */
     private sleep;
-    private calculateDelay;
-    private extractRateLimit;
-    private handleErrorResponse;
-    private request;
     /**
-     * Busca dados de IPTU por endereço.
+     * Consulta imoveis por endereco.
      *
-     * @param params - Parâmetros da consulta
-     * @returns Dados do imóvel encontrado
-     * @throws {NotFoundError} Se o imóvel não for encontrado
-     * @throws {ValidationError} Se os parâmetros forem inválidos
-     * @throws {AuthenticationError} Se a API Key for inválida
-     * @throws {RateLimitError} Se exceder o limite de requisições
+     * @param logradouro - Nome da rua/avenida
+     * @param numero - Numero do imovel
+     * @param cidade - Codigo da cidade (sp, bh, recife)
+     * @returns Lista de imoveis encontrados
      */
-    consultaEndereco(params: ConsultaEnderecoParams): Promise<ConsultaEnderecoResult>;
-    consultaEndereco(logradouro: string, numero?: string, cidade?: Cidade): Promise<ConsultaEnderecoResult>;
+    consultaEndereco(logradouro: string, numero: string, cidade?: Cidade): Promise<Imovel[]>;
     /**
-     * Busca dados de IPTU por número SQL (contribuinte).
+     * Consulta imovel por numero SQL/Indice Cadastral.
+     * Requer plano Starter ou superior.
      *
-     * @param sql - Número SQL do imóvel
-     * @param cidade - Cidade da consulta
-     * @param options - Opções adicionais
-     * @returns Dados completos do imóvel
+     * @param sql - Numero SQL (SP), Indice Cadastral (BH) ou Sequencial (Recife)
+     * @param cidade - Codigo da cidade (sp, bh, recife)
+     * @returns Lista de imoveis encontrados
      */
-    consultaSQL(sql: string, cidade?: Cidade, options?: {
-        incluirHistorico?: boolean;
-        incluirComparaveis?: boolean;
-    }): Promise<ConsultaSQLResult>;
+    consultaSQL(sql: string, cidade?: Cidade): Promise<Imovel[]>;
     /**
-     * Busca imóveis por CEP.
+     * Consulta imoveis por CEP.
      *
-     * @param cep - CEP do imóvel
-     * @param cidade - Cidade da consulta
-     * @returns Lista de imóveis no CEP
+     * @param cep - CEP do endereco
+     * @param cidade - Codigo da cidade (sp, bh, recife)
+     * @returns Lista de imoveis encontrados
      */
-    consultaCEP(cep: string, cidade?: Cidade): Promise<ConsultaEnderecoResult[]>;
+    consultaCEP(cep: string, cidade?: Cidade): Promise<Imovel[]>;
     /**
      * Consulta zoneamento por coordenadas.
      *
      * @param latitude - Latitude do ponto
      * @param longitude - Longitude do ponto
-     * @returns Dados de zoneamento
+     * @returns Informacoes de zoneamento
+     */
+    consultaZoneamento(latitude: number, longitude: number): Promise<Zoneamento>;
+    /**
+     * Calcula estimativa de valor de mercado.
+     * Requer plano Pro ou superior.
+     *
+     * @param params - Parametros da avaliacao
+     * @returns Avaliacao de mercado
+     */
+    valuationEstimate(params: ValuationParams): Promise<Valuation>;
+    /**
+     * Busca imoveis comparaveis.
+     * Requer plano Pro ou superior.
+     *
+     * @param params - Parametros da busca
+     * @returns Lista de imoveis comparaveis
      */
-    consultaZoneamento(latitude: number, longitude: number): Promise<ZoneamentoResult>;
+    valuationComparables(params: ComparablesParams): Promise<Comparavel[]>;
     /**
-     * Estima o valor de mercado do imóvel usando ML.
-     * Disponível apenas para planos Pro e Enterprise.
+     * Avalia imovel por endereco OU SQL.
+     * Combina dados do modelo AVM (ML) com transacoes ITBI reais.
+     * Requer plano Pro ou superior.
      *
-     * @param params - Parâmetros do imóvel
-     * @returns Estimativa de valor
-     * @throws {ForbiddenError} Se o plano não permitir
+     * @param params - Parametros da avaliacao (sql OU logradouro+numero)
+     * @returns Avaliacao completa do imovel
      */
-    valuationEstimate(params: ValuationParams): Promise<ValuationResult>;
+    valuationEvaluate(params: EvaluateParams): Promise<PropertyEvaluation>;
     /**
-     * Valuation em lote (até 100 imóveis).
-     * Disponível apenas para plano Enterprise.
+     * Consulta status de transacao ITBI.
      *
-     * @param imoveis - Lista de imóveis para avaliar
-     * @returns Resultados de valuation para cada imóvel
+     * @param protocolo - Numero do protocolo ITBI
+     * @param cidade - Codigo da cidade (sp, bh, recife)
+     * @returns Status da transacao
      */
-    valuationBatch(imoveis: ValuationParams[]): Promise<BatchValuationResult>;
+    itbiStatus(protocolo: string, cidade?: Cidade): Promise<ITBIStatus>;
     /**
-     * Busca imóveis comparáveis para análise.
+     * Calcula valor do ITBI.
      *
-     * @param bairro - Nome do bairro
-     * @param areaMin - Área mínima em m²
-     * @param areaMax - Área máxima em m²
-     * @param options - Opções adicionais
-     * @returns Lista de imóveis comparáveis
+     * @param params - Parametros do calculo
+     * @returns Calculo do ITBI
      */
-    valuationComparables(bairro: string, areaMin: number, areaMax: number, options?: {
-        tipoUso?: string;
-        cidade?: Cidade;
-        limit?: number;
-    }): Promise<ComparavelItem[]>;
+    itbiCalcular(params: ITBICalculoParams): Promise<ITBICalculo>;
     /**
-     * Histórico de valores IPTU de um imóvel.
+     * Consulta historico de transacoes ITBI de um imovel.
+     * Requer plano Starter ou superior.
      *
-     * @param sql - Número SQL do imóvel
-     * @param cidade - Cidade da consulta
-     * @returns Lista com histórico anual
+     * @param sql - Numero SQL do imovel
+     * @param cidade - Codigo da cidade (sp, bh, recife)
+     * @returns Lista de transacoes historicas
      */
-    dadosIPTUHistorico(sql: string, cidade?: Cidade): Promise<HistoricoItem[]>;
+    itbiHistorico(sql: string, cidade?: Cidade): Promise<ITBIHistorico[]>;
     /**
-     * Consulta dados de empresa por CNPJ.
+     * Consulta aliquotas ITBI vigentes.
      *
-     * @param cnpj - CNPJ da empresa
-     * @returns Dados cadastrais
+     * @param cidade - Codigo da cidade (sp, bh, recife)
+     * @returns Aliquotas vigentes
      */
-    dadosCNPJ(cnpj: string): Promise<Record<string, unknown>>;
+    itbiAliquotas(cidade?: Cidade): Promise<ITBIAliquota>;
     /**
-     * Correção monetária pelo IPCA.
+     * Consulta isencoes ITBI disponiveis.
      *
-     * @param valor - Valor a corrigir
-     * @param dataOrigem - Data do valor original (YYYY-MM)
-     * @param dataDestino - Data destino (default: atual)
-     * @returns Valor corrigido e fator de correção
+     * @param cidade - Codigo da cidade (sp, bh, recife)
+     * @returns Lista de isencoes disponiveis
      */
-    dadosIPCACorrigir(valor: number, dataOrigem: string, dataDestino?: string): Promise<{
-        valor_corrigido: number;
-        fator: number;
-    }>;
+    itbiIsencoes(cidade?: Cidade): Promise<ITBIIsencao[]>;
+    /**
+     * Gera guia de pagamento ITBI.
+     * Requer plano Starter ou superior.
+     *
+     * @param params - Parametros da guia
+     * @returns Guia de pagamento gerada
+     */
+    itbiGuia(params: ITBIGuiaParams): Promise<ITBIGuia>;
+    /**
+     * Valida autenticidade de uma guia ITBI.
+     *
+     * @param protocolo - Numero do protocolo da guia
+     * @param cidade - Codigo da cidade (sp, bh, recife)
+     * @returns Resultado da validacao
+     */
+    itbiValidarGuia(protocolo: string, cidade?: Cidade): Promise<ITBIValidacao>;
+    /**
+     * Simula calculo de ITBI.
+     *
+     * @param params - Parametros da simulacao
+     * @returns Resultado da simulacao
+     */
+    itbiSimular(params: ITBISimularParams): Promise<ITBISimulacao>;
+}
+
+/**
+ * Excecoes customizadas para a IPTU API.
+ */
+interface ErrorDetails {
+    error: string;
+    message: string;
+    statusCode?: number;
+    requestId?: string;
+    retryable: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Excecao base para todos os erros da IPTU API.
+ */
+declare class IPTUAPIError extends Error {
+    readonly statusCode?: number;
+    readonly requestId?: string;
+    readonly responseData: Record<string, unknown>;
+    constructor(message: string, statusCode?: number, requestId?: string, responseData?: Record<string, unknown>);
+    isRetryable(): boolean;
+    toJSON(): ErrorDetails;
+}
+/**
+ * Erro de autenticacao (401). API Key invalida ou ausente.
+ */
+declare class AuthenticationError extends IPTUAPIError {
+    constructor(message?: string, requestId?: string);
+}
+/**
+ * Erro de autorizacao (403). Plano nao permite acesso ao recurso.
+ */
+declare class ForbiddenError extends IPTUAPIError {
+    readonly requiredPlan?: string;
+    constructor(message?: string, requiredPlan?: string, requestId?: string);
+    toJSON(): ErrorDetails;
+}
+/**
+ * Erro de recurso nao encontrado (404).
+ */
+declare class NotFoundError extends IPTUAPIError {
+    readonly resource?: string;
+    constructor(message?: string, resource?: string, requestId?: string);
+    toJSON(): ErrorDetails;
+}
+/**
+ * Erro de rate limit excedido (429).
+ */
+declare class RateLimitError extends IPTUAPIError {
+    readonly retryAfter: number;
+    constructor(message?: string, retryAfter?: number, requestId?: string);
+    isRetryable(): boolean;
+    toJSON(): ErrorDetails;
+}
+/**
+ * Erro de validacao de parametros (400, 422).
+ */
+declare class ValidationError extends IPTUAPIError {
+    readonly errors: Record<string, string[]>;
+    constructor(message?: string, errors?: Record<string, string[]>, statusCode?: number, requestId?: string);
+    toJSON(): ErrorDetails;
+}
+/**
+ * Erro interno do servidor (5xx). Retryable.
+ */
+declare class ServerError extends IPTUAPIError {
+    constructor(message?: string, statusCode?: number, requestId?: string);
+    isRetryable(): boolean;
+}
+/**
+ * Erro de timeout na requisicao.
+ */
+declare class TimeoutError extends IPTUAPIError {
+    readonly timeoutSeconds?: number;
+    constructor(message?: string, timeoutSeconds?: number, requestId?: string);
+    isRetryable(): boolean;
+    toJSON(): ErrorDetails;
+}
+/**
+ * Erro de conexao de rede.
+ */
+declare class NetworkError extends IPTUAPIError {
+    readonly originalError?: Error;
+    constructor(message?: string, originalError?: Error);
+    isRetryable(): boolean;
 }
 
-export { AuthenticationError, type BatchValuationResult, type Cidade, CidadeEnum, type ComparavelItem, type ConsultaEnderecoParams, type ConsultaEnderecoResult, type ConsultaSQLResult, ForbiddenError, type HistoricoItem, IPTUAPIError, IPTUClient, type IPTUClientOptions, type Logger, NetworkError, NotFoundError, RateLimitError, type RateLimitInfo, type RetryConfig, ServerError, TimeoutError, ValidationError, type ValuationParams, type ValuationResult, type ZoneamentoResult, IPTUClient as default };
+export { type AVMEstimate, AuthenticationError, type Cidade, type ClientConfig, type ClientOptions, type ComparablesParams, type Comparavel, type EvaluateParams, type FinalValuation, ForbiddenError, IPTUAPIError, IPTUClient, type ITBIAliquota, type ITBICalculo, type ITBICalculoParams, type ITBIGuia, type ITBIGuiaParams, type ITBIHistorico, type ITBIIsencao, type ITBIMarketEstimate, type ITBISimulacao, type ITBISimularParams, type ITBIStatus, type ITBIValidacao, type Imovel, NetworkError, NotFoundError, type Pessoa, type PropertyEvaluation, RateLimitError, type RateLimitInfo, type RetryConfig, ServerError, TimeoutError, ValidationError, type Valuation, type ValuationParams, type Zoneamento };