O valor do bem.
Na sua aplicação.

01 / ACESSO

Autenticação por tipo de consulta

Solicite uma credencial no formulário de integração, informando o projeto e as categorias desejadas. O envio do formulário registra o interesse; não libera uma chave automaticamente. Configure a credencial nas variáveis de ambiente do servidor consumidor. Não a coloque em URL, código do navegador ou variáveis expostas ao frontend.

Em outro site, envie a consulta pelo seu backend. As rotas não oferecem um contrato geral de CORS para chamadas entre origens no navegador. O cliente envia a chave somente às consultas imobiliárias autenticadas e não segue redirecionamentos.

02 / IMÓVEIS

Endereço + tipo + área

POST /api/v2/property-estimates

Envie JSON com dados do imóvel. Para identificar o município, prefira o código IBGE ou cidade e UF; também é possível usar CEP. Use endereço detalhado quando disponível. O serviço estima a partir dos dados enviados e da cobertura existente; não confirma a porta do imóvel ou sua titularidade.

A área correta para cada imóvel

Consulte a cobertura antes de prometer uma estimativa

GET /api/v2/coverage?municipalityCode=3550308, com a mesma chave, informa a cobertura do município. O catálogo territorial nacional não significa disponibilidade de preço para todos os imóveis. A referência municipal automática atende apartamentos onde houver dados compatíveis. Casas, terrenos e consultas por transação dependem de comparáveis compatíveis; sem eles, a API informa dados insuficientes.

A consulta por CEP isolada é pública: GET /api/v2/postal?cep=01050000. Nesta rota, use exatamente oito dígitos. Ela resolve endereço, não estima valor. O SDK oferece postalAddress("01050000") e propertyCoverage("3550308").

03 / EXEMPLO PERSONALIZADO

Monte a requisição do seu imóvel

Preencha o mínimo necessário e gere o código para executar no seu servidor. Este formulário prepara a requisição localmente; não consulta preços nem recebe uma chave de acesso.

import { createEstimaBemClient, readEstimate, EstimaBemApiError }
  from "./estimabem-client.mjs";

const api = createEstimaBemClient({
  apiKey: process.env.ESTIMABEM_API_KEY,
});

try {
  const result = await api.estimateProperty({
  "externalId": "imovel-123",
  "address": {
    "city": "São Paulo",
    "state": "SP"
  },
  "property": {
    "type": "apartment",
    "privateAreaM2": 100
  }
});
  const value = readEstimate(result);
  if (value.hasValue) {
    console.log(value.amount, value.currency, value.referenceDate);
  } else if (result.status === "needs_input") {
    console.log("Complete os dados:", result.requiredFields);
  } else {
    console.log("Sem estimativa disponível", result.limitations);
  }
} catch (error) {
  if (!(error instanceof EstimaBemApiError)) throw error;
  console.error(error.code, error.message, error.requestId);
}

04 / RESULTADOS

HTTP 200 não significa valor disponível

A consulta imobiliária tem três estados de negócio. Verifique status antes de ler estimate.value. Os trechos abaixo foram gerados com o motor do projeto durante a construção desta documentação, usando o exemplo de apartamento e uma casa sem comparáveis. São exemplos datados, não uma cotação atual para qualquer imóvel.

estimated · valor disponível

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

estimate.value é um número JSON em reais. pricePerM2 usa a área correspondente ao tipo do imóvel. dispersion pode ser null; não crie uma faixa de valores quando a API não a fornece.

needs_input · complete os dados

{
  "status": "needs_input",
  "externalId": null,
  "currency": "BRL",
  "estimate": null,
  "requiredFields": [
    {
      "field": "property.privateAreaM2",
      "message": "Informe a área privativa do apartamento. Área total, área comum e fração ideal não a substituem."
    }
  ]
}

Use requiredFields[].field para identificar o campo e message para orientar a pessoa. Reenvie o objeto completo após a confirmação. Não substitua uma informação desconhecida por zero.

insufficient_data · sem suporte para estimar

{
  "status": "insufficient_data",
  "externalId": null,
  "currency": "BRL",
  "referenceDate": "2026-10-26",
  "estimate": null,
  "requiredFields": [],
  "reason": {
    "code": "INSUFFICIENT_COMPARABLES",
    "message": "Não há referência automática compatível com este município e tipo de imóvel. O cálculo local exige pelo menos 5 endereços distintos do mesmo bairro, perfil e base de preço, nos últimos 12 meses."
  }
}

Informe “Não há estimativa disponível para estes dados” e preserve as limitações. Repetir imediatamente o mesmo corpo não resolve uma ausência de cobertura.

Como ler veículos e outros bens

Os formatos originais são preservados por compatibilidade: imóveis usam estados em minúsculas e número JSON; outros bens usam estados em maiúsculas e strings decimais. O SDK normaliza erros e a leitura do valor sem alterar o JSON original.

05 / SEU LEITOR DE MATRÍCULAS

Do documento aos dados da consulta

1. Seu sistema extrai tipo, endereço e áreas da matrícula.
2. Confirme a correspondência de cada área: privativa, construída ou terreno. Converta unidades de forma explícita antes do envio.
3. Monte address e property com os fatos confirmados. Use externalId para relacionar o resultado ao registro interno.
4. Chame estimateProperty pelo backend. Se receber needs_input, peça a confirmação dos campos pendentes.
5. Apresente valor, data e contexto; guarde o resultado no seu sistema se precisar de histórico.

A rota recebe fatos estruturados. Ela não faz OCR, não recebe PDF e não precisa de nomes de proprietários, CPF ou inteiro teor da matrícula. id identifica o cálculo retornado; requestId identifica a requisição. Nenhum dos dois cria um histórico consultável nesta rota.

// Exemplo de mapeamento no backend do seu leitor de matrículas.
// confirmed contém apenas fatos conferidos, já normalizados em m².
function propertyFromRegistry(confirmed) {
  const areas = {
    apartment: { privateAreaM2: confirmed.privateAreaM2 },
    house: { builtAreaM2: confirmed.builtAreaM2, landAreaM2: confirmed.landAreaM2 },
    land: { landAreaM2: confirmed.landAreaM2 },
  };
  if (!areas[confirmed.type]) throw new Error("Confirme o tipo do imóvel.");
  const property = { type: confirmed.type };
  for (const [field, value] of Object.entries(areas[confirmed.type])) {
    if (value !== undefined && value !== null) property[field] = value;
  }
  return {
    externalId: confirmed.internalId,
    address: confirmed.address,
    property,
  };
}
// api.estimateProperty(propertyFromRegistry(confirmed));

Se houver uma referência municipal, o nome do bairro não transforma automaticamente essa referência em uma avaliação específica do condomínio. O resultado não comprova a situação registral ou a titularidade do imóvel.

06 / VEÍCULOS

Marca, modelo, versão e ano

Carros e motos usam cars e motorcycles; caminhões e ônibus usam trucks. As consultas são públicas. Não use texto livre para substituir os identificadores do catálogo.

Envie POST /api/v1/asset-valuation/market/vehicle-estimates com type, brand, model e year, todos textos. model é o código da versão. year é o código completo retornado pela etapa anterior, não apenas o ano de fabricação. Para zero-quilômetro, use a opção disponível no catálogo; a resposta terá asset.zero_km: true e asset.model_year: null.

import { createEstimaBemClient, readEstimate }
  from "./estimabem-client.mjs";

const api = createEstimaBemClient(); // Catálogos e veículos são públicos.
const type = "cars"; // motorcycles: motos; trucks: caminhões e ônibus.

// Etapa 1: apresente brands.items para a pessoa selecionar a marca.
const brands = await api.vehicleCatalog({ type });

// Etapa 2: passe o code da marca selecionada.
async function modelsFor(brand) {
  return api.vehicleCatalog({ type, brand });
  // model_groups: famílias de modelos; versions: versões de cada família.
  // Use o code de versions, nunca o code "family:..." do agrupamento.
}

// Etapa 3: após selecionar a versão, apresente seus anos e combustíveis.
async function yearsFor(brand, model) {
  return api.vehicleCatalog({ type, brand, model });
}

// Etapa 4: envie exatamente o code do ano retornado no catálogo.
async function estimateSelection(brand, model, year) {
  const result = await api.estimateVehicle({ type, brand, model, year });
  return { value: readEstimate(result), vehicle: result.asset };
}

console.log(brands.items);
// Limpe modelo/versão/ano sempre que a pessoa alterar a marca.
// Trate erros com EstimaBemApiError, como no exemplo de imóveis.

Ao mudar marca ou versão, limpe as escolhas dependentes. Não escolha automaticamente a primeira versão como se fosse o veículo identificado. A referência mensal não ajusta quilometragem, conservação, avarias, opcionais ou localização. O contrato contém um esquema tipado da resposta em vehicle-estimates.

07 / COBERTURA

Um caminho para cada uma das 18 classes

Comece com GET /api/v1/asset-valuation/market/coverage. Ele descreve os modos de consulta; os catálogos e a resposta da estimativa confirmam a disponibilidade da seleção. As rotas abreviadas da tabela usam o prefixo /api/v1/asset-valuation/market/. Todas as rotas de estimativa abaixo usam POST.

Aeronaves e embarcações

Repita a seleção por fabricante, modelo, ano e configuração. Cada consulta retorna opções disponíveis. Se vier NO_COVERAGE, apresente a indisponibilidade e permita outra seleção. A referência corresponde ao conjunto descrito em item e context.

const api = createEstimaBemClient();
const asset_class = "AIRCRAFT"; // Use VESSEL para embarcações.
const brands = await api.knowledgeCatalog({ asset_class });
// Após cada escolha, acrescente o code retornado à próxima consulta:
// { asset_class, brand_id } → modelos
// { asset_class, brand_id, model_id } → anos
// { asset_class, brand_id, model_id, year } → configurações
// NO_COVERAGE: não prossiga com códigos inventados.

async function estimateSelection(brand_id, model_id, year, configuration_id) {
  const result = await api.estimateKnowledge({
    asset_class, brand_id, model_id, year, configuration_id,
  });
  return readEstimate(result);
}

Equipamentos e estoques

Para equipamentos, busque GET /market/equipment?family=tractor e envie a configuração escolhida em {"family":"tractor","product_code":"CODIGO_DO_CATALOGO","condition":"new"}. Para usados, o cenário exige age_years, useful_life_years e residual_percent, em strings decimais. Vida útil é o total desde novo; não estime essas premissas silenciosamente.

Para estoques, busque GET /api/v1/asset-valuation/inventory/presets e envie {"product_id":"ID_DO_PRODUTO","quantity":"100"} a /inventory/quick-estimates, sob o mesmo prefixo /api/v1/asset-valuation. Confira available e a unidade; 100 sacas não é a mesma quantidade que 100 kg.

Os corpos completos de equipamentos, títulos, créditos e cenários por classe estão no OpenAPI público. Os campos mudam conforme a classe; não envie o formulário de imóvel a uma rota de outro bem. A coleção Postman inclui consultas de catálogo e exemplos para começar.

08 / OPERAÇÃO

Erros que seu projeto consegue tratar

Exemplos de erros, com IDs substituídos por texto ilustrativo:

{
  "requestId": "ID_DA_REQUISICAO",
  "error": {
    "code": "INVALID_AREA",
    "message": "A área deve ser um número positivo em m²."
  }
}

{
  "code": "INVALID_INPUT",
  "message": "Confira os códigos da seleção.",
  "request_id": "ID_DA_REQUISICAO",
  "retryable": false,
  "details": []
}

O SDK converte ambos em EstimaBemApiError: status, code, message, requestId, details, retryable e retryAfterSeconds. Erros de rede usam status: 0. O cabeçalho X-Request-Id ajuda a identificar a consulta em suporte; o SDK também o usa quando o corpo não traz o ID.

Timeout, repetição e limites

• O cliente usa 20 segundos de timeout por padrão, configurável de 1 a 60.000 milissegundos com timeoutMs. Catálogos de equipamentos podem exigir um prazo maior. Use { signal } para cancelar uma consulta obsoleta.
• O SDK não repete requisições automaticamente. Para falhas temporárias, faça poucas tentativas com espera crescente e variação aleatória. Respeite Retry-After quando houver. A indicação retryable por HTTP não substitui a leitura do código do erro.
• Corpos: imóveis até 16 KiB; consultas de mercado e estoque rápido até 4 KiB. Outros limites constam no contrato da rota. Essas consultas não persistem ativos e não exigem Idempotency-Key.
• Não há uma quota ou SLA geral publicado nesta documentação. Combine volume e condições de uso pelo contato de integração. Não envie consultas em massa sem controle de concorrência.
• A API de gestão tem regras próprias de idempotência, permissões e processamento assíncrono. Use o contrato de gestão se precisar cadastrar e guardar ativos.

Versionamento e histórico

Guarde a resposta original, seu identificador interno e os metadados de versão/data disponíveis. apiVersion, modelVersion, datasetId e schema_version identificam contextos diferentes; não os substitua pela data de hoje. Campos adicionais podem surgir: leia os campos de que precisa e trate estados desconhecidos de forma explícita. O SDK lança INVALID_RESPONSE se o resumo recebe um estado desconhecido.

09 / FERRAMENTAS

Contratos e arquivos para integrar

A API imobiliária v3 recebe as 24 famílias, condomínio, torre, unidade e áreas separadas. Use estimatePropertyV3 e propertyCoverageV3 no SDK. Consulte a cobertura de fontes por família e município antes de prometer um resultado numérico.

As rotas anteriores continuam disponíveis: integração imobiliária detalhada e API v1 do Morumbi e guia de gestão de bens. A v2 permanece compatível; a ampliação de famílias está na v3.