Da matrícula à estimativa.

Seu projeto extrai os dados do imóvel. Esta API resolve o município e devolve o valor estimado, a referência utilizada e os campos que ainda precisam de confirmação.

POST /api/v2/property-estimates

1. No backend consumidor, configure VALOR_DO_IMOVEL_URL=https://estimabem.com.br e VALOR_DO_IMOVEL_KEY com uma chave de integração emitida pelo administrador desta API.
2. Envie cidade/UF, código IBGE ou CEP, o tipo do imóvel e as áreas identificadas no documento. CEP aceita 01050-000. Números JSON usam ponto decimal, por exemplo 85.5.
3. Vincule o resultado ao seu registro usando externalId. Exiba o valor junto ao método e à data da referência. Salve a resposta no seu próprio projeto se precisar de histórico.

Qual área enviar?

Área total pode ser informada em totalAreaM2, mas não substitui a área exigida. Não envie fração ideal como área privativa. Omita campos não extraídos; não use zero, null ou uma área presumida. Informe apenas os dados do imóvel, sem PDF, texto integral, CPF ou dados dos proprietários.

Exemplo para o backend

// Execute no backend do projeto que lê a matrícula.
const response = await fetch(
  process.env.VALOR_DO_IMOVEL_URL + '/api/v2/property-estimates',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VALOR_DO_IMOVEL_KEY,
      'Content-Type': 'application/json'
    },
    signal: AbortSignal.timeout(12000),
    body: JSON.stringify({
  "externalId": "imovel-123",
  "address": {
    "city": "São Paulo",
    "state": "SP",
    "neighborhood": "Morumbi"
  },
  "property": {
    "type": "apartment",
    "privateAreaM2": 100
  }
})
  }
);
const result = await response.json();
if (!response.ok) throw new Error(result.error.message);
if (result.status === 'estimated') {
  // Exiba também método, referenceDate e limitations.
  console.log(result.estimate.value, result.currency);
} else if (result.status === 'needs_input') {
  console.log('Solicitar confirmação:', result.requiredFields);
} else {
  console.log('Sem referência compatível:', result.reason);
}

Resposta resumida do exemplo

{
  "externalId": "imovel-123",
  "status": "estimated",
  "currency": "BRL",
  "method": "municipal_reference",
  "referenceDate": "2026-08-31",
  "estimate": {
    "value": 1214300,
    "pricePerM2": 12143,
    "dispersion": null
  }
}

O exemplo usa a média municipal de São Paulo mesmo quando o bairro informado é Morumbi. O resultado completo inclui benchmark.source, evidence, limitations, datasetId, modelVersion, resolution e normalizedInput.

Cobertura automática: apartamentos nas 56 cidades com média pública de anúncios. A aproximação municipal não ajusta bairro, rua ou características da unidade e não tem intervalo de erro calibrado. Casas, terrenos e outras cidades precisam de comparáveis locais elegíveis. Uma matrícula com endereço completo não garante cobertura de preços.

Autenticação e erros

A chave deve ficar nas variáveis de ambiente do backend, inclusive na Vercel. Não use prefixo NEXT_PUBLIC_ e não exponha a chave no navegador. A chave desta API é diferente da chave do Google Maps. A API não oferece CORS para chamadas autenticadas do navegador.

401: credencial inválida; 422: dados inválidos ou endereço conflitante; 404: CEP não encontrado; 503: serviço indisponível. Use requestId para diagnóstico e não substitua erros por valor zero. O limite do corpo é 16 KiB. O SDK oferece client.estimateProperty(input), timeout e cancelamento.

Valor estimado automático · API v2

Envie município, tipo e área para receber a estimativa inicial de apartamentos nas 56 cidades com referência pública. Não é obrigatório cadastrar comparáveis. Fórmula: área privativa × preço médio municipal por m².

{"address":{"municipalityCode":"3550308"},"propertyType":"apartment","areaBasis":"private","areaM2":100}

Use POST /api/v2/estimates ou client.estimateNational(input). A resposta identifica method: municipal_reference, origem, data e limitações. dispersion será nulo: não há faixa de erro calibrada. O total é uma aproximação municipal, sem ajuste por bairro, rua ou atributos da unidade.

Com pelo menos 5 comparáveis locais elegíveis, o método passa a user_supplied_comparables. Casas, terrenos, preços de transações e cidades sem referência compatível precisam desses comparáveis. Ausência de cobertura retorna insufficient_data, nunca valor zero. Endereço completo é obrigatório quando há comparáveis. Mesma chave da v1; corpo máximo de 16 KiB.

GET /api/v2/coverage?municipalityCode=3550308 informa a referência disponível. GET /api/v2/postal?cep=30140071 é público e consulta CEP. O modelo do Morumbi continua disponível na API v1.

Contrato nacional OpenAPI v2 · Simulador Brasil · Simulador Morumbi