Você tem um VIN em mãos e precisa de um valor de mercado defensável para esse veículo em seu aplicativo até sexta-feira. Neste guia, você fará um pedido real à API da Calculadora de Valor de Veículos com curl, analisará o JSON no Node.js e entenderá os campos que você pode enviar para produção (preço médio, faixas de distribuição, certeza, ajuste de quilometragem e mais).
O que a API da Calculadora de Valor de Veículos faz
A API da Calculadora de Valor de Veículos estima preços de mercado para um veículo específico identificado pelo VIN e expõe dados de suporte, como o período observado, tamanho da amostra, desvio padrão e uma distribuição de preços. Ela também fornece endpoints auxiliares para listar fabricantes e modelos suportados.
Os desenvolvedores a utilizam para gerar cotações de troca, recomendações de preços de listagem, verificações de subscrição e painéis de remarketing de frotas. Você fornece um VIN, e a API retorna estatísticas principais que você pode colocar diretamente em widgets de UI ou lógica de preços.
Começando no Zyla API Hub
Todos os chamados passam pelo Zyla API Hub. Abra a listagem da API, inscreva-se e use o token de portador em seus cabeçalhos:
- Visite o item do marketplace e clique em Começar teste de 7 dias (ou inscreva-se) para obter sua chave: Começar teste de 7 dias na API da Calculadora de Valor de Veículos
- A autenticação é via Authorization: Bearer YOUR_API_KEY
- A cobrança é por assinatura + cota (não por chamada). Para uma primeira integração, espere um teste de 7 dias ou 50 solicitações. Não há Plano Gratuito; verifique a página da API para opções de acesso e preços atuais.
O Zyla API Hub hospeda mais de 10.000 APIs públicas sob uma conta e uma chave de API, para que você possa conectar fontes de dados adicionais em sua pilha sem gerenciar vários fluxos de autenticação.
Endpoints que você chamará
Abaixo estão os endpoints expostos pela API da Calculadora de Valor de Veículos no Zyla API Hub. Use exatamente essas URLs e métodos, e passe sua chave de API no cabeçalho de Autorização.
Obter dados de preço do veículo
Busque estatísticas de preço para um VIN dado.
- Método: GET
- URL: https://zylalabs.com/api/3624/vehicle-value-calculator-api/4063/get-vehicle-price-data
- Parâmetro de consulta obrigatório: vin (string). Exemplo: JNKCA31A61T027494
- Descrição: Insira um VIN para receber métricas de preços de mercado. A API suporta parâmetros opcionais, como quilometragem (km) em geral, mas apenas o vin está documentado aqui. A suposição padrão de quilometragem é de 50.000 km, a menos que ajustada de outra forma pelo serviço.
Exemplo oficial de curl:
curl -s -X GET "https://zylalabs.com/api/3624/vehicle-value-calculator-api/4063/get-vehicle-price-data?vin=JNKCA31A61T027494" \
-H "Authorization: Bearer YOUR_API_KEY"Exemplo oficial de resposta JSON:
{
"status": true,
"code": 200,
"data": {
"vin": "JNKCA31A61T027494",
"success": true,
"id": "2001_infiniti_i30_luxury",
"vehicle": "2001 Infiniti I30 Luxury",
"mean": 4427.14,
"stdev": 1066,
"count": 18,
"mileage": 100000,
"certainty": 91,
"period": [
"2024-06-15",
"2024-12-04"
],
"prices": {
"average": 4427.14,
"below": 3360.23,
"above": 5494.05,
"distribution": [
{
"group": {
"min": 2095,
"max": 2350,
"count": 2
}
},
{
"group": {
"min": 2350,
"max": 2690,
"count": 2
}
},
{
"group": {
"min": 2690,
"max": 3555,
"count": 2
}
},
{
"group": {
"min": 3555,
"max": 3999,
"count": 2
}
},
{
"group": {
"min": 3999,
"max": 4200,
"count": 2
}
},
{
"group": {
"min": 4200,
"max": 4250,
"count": 1
}
},
{
"group": {
"min": 4250,
"max": 4500,
"count": 2
}
},
{
"group": {
"min": 4500,
"max": 4990,
"count": 2
}
},
{
"group": {
"min": 4990,
"max": 5250,
"count": 2
}
},
{
"group": {
"min": 5250,
"max": 5697,
"count": 1
}
}
]
},
"adjustments": {
"mileage": {
"average": 153135.17,
"input": 100000,
"adjustment": 463
}
}
},
"message": "Dados buscados com sucesso!"
}Como ler isso:
- data.vehicle e data.id identificam o veículo.
- data.mean e data.prices.average são o preço médio principal. As unidades são valores numéricos de preço; use-os como estão em seu aplicativo. Se você exibir moeda, rotule-a explicitamente em sua UI, uma vez que a resposta não fornece um código de moeda.
- data.prices.below e data.prices.above definem referências de preço inferior e superior em torno da média.
- data.prices.distribution é um histograma em faixas de preço com limites min/max e contagens de amostra.
- data.count é o número de observações que informaram a estimativa. data.stdev é o desvio padrão do preço.
- data.period contém datas ISO-8601 que delimitam a janela observada.
- data.certainty é um indicador de confiança (quanto maior, melhor) que você pode mostrar na UX ou usar para exigir revisão manual.
- data.adjustments.mileage mostra a entrada de quilometragem, uma referência média e o ajuste de quilometragem aplicado à estimativa. A quilometragem é expressa em quilômetros.
Obter Fabricantes
Recupere todos os fabricantes de veículos suportados.
- Método: GET
- URL: https://zylalabs.com/api/3624/vehicle-value-calculator-api/4064/get-makers
- Parâmetros: Nenhum documentado.
curl:
Obter Modelos
Recupere todos os modelos para um fabricante dado.
- Método: GET
- URL: https://zylalabs.com/api/3624/vehicle-value-calculator-api/4065/get-models
- Parâmetro de consulta obrigatório: maker (string). Exemplo: audi
curl:
Node.js: primeiro pedido e manipulação de JSON
O trecho abaixo chama Obter dados de preço do veículo, valida a resposta e extrai campos que você normalmente persistiria ou renderizaria na UI. Ele usa exatamente o endpoint e os valores de parâmetro mostrados acima.
import fetch from "node-fetch";
const API_KEY = process.env.ZYLA_API_KEY; // defina YOUR_API_KEY aqui
const VIN = "JNKCA31A61T027494";
async function fetchVehiclePriceData(vin) {
const url = `https://zylalabs.com/api/3624/vehicle-value-calculator-api/4063/get-vehicle-price-data?vin=${encodeURIComponent(vin)}`;
const res = await fetch(url, {
method: "GET",
headers: {
"Authorization": `Bearer ${API_KEY}`
},
// Se você precisar de um SLA mais rigoroso, considere controller+timeout aqui.
});
if (!res.ok) {
const text = await res.text();
throw new Error(`HTTP ${res.status}: ${text}`);
}
const json = await res.json();
if (!json.status || !json.data || json.data.success !== true) {
throw new Error(`Erro da API: ${JSON.stringify(json)}`);
}
return json.data;
}
function summarize(data) {
const {
vin,
vehicle,
mean,
stdev,
count,
mileage,
certainty,
period,
prices,
adjustments
} = data;
return {
vin,
vehicleLabel: vehicle,
stats: {
average: prices?.average ?? mean,
stdev,
count,
below: prices?.below,
above: prices?.above,
periodStart: period?.[0],
periodEnd: period?.[1],
certainty
},
mileage: {
inputKm: mileage,
referenceKm: adjustments?.mileage?.average,
appliedAdjustment: adjustments?.mileage?.adjustment
},
distribution: (prices?.distribution || []).map(bin => bin.group)
};
}
(async () => {
try {
const data = await fetchVehiclePriceData(VIN);
const summary = summarize(data);
console.log("Veículo:", summary.vehicleLabel);
console.log("Preço médio:", summary.stats.average);
console.log("Intervalo:", summary.stats.periodStart, "até", summary.stats.periodEnd);
console.log("Certeza:", summary.stats.certainty);
console.log("Quilometragem (km):", summary.mileage.inputKm, "(ref:", summary.mileage.referenceKm, ")");
console.log("Faixas de distribuição:", summary.distribution.length);
// Persista em seu DB ou retorne em sua API aqui.
} catch (err) {
console.error(err);
process.exit(1);
}
})();Tratamento de erros e confiabilidade
- Status: Use o código HTTP de nível superior e os campos de código/status JSON para ramificar a lógica.
- Tentativas: Faça backoff em erros transitórios (HTTP 5xx) e evite loops de tentativa em erros do cliente (HTTP 4xx).
- Cache: Os dados de preço normalmente não mudam minuto a minuto. Armazene em cache por VIN por um TTL curto para reduzir a latência e o uso de cota. A resposta inclui um período observado; trate-o como informativo, não como uma chave de cache.
Notas práticas de integração
- Autenticação: Sempre envie Authorization: Bearer YOUR_API_KEY.
- Parâmetros: Para Obter dados de preço do veículo, passe vin. A API pode aceitar quilometragem opcional, mas apenas vin está documentado aqui, então não adicione parâmetros extras a menos que estejam listados na página do hub.
- Unidades e formatos:
- quilometragem é medida em quilômetros.
- datas do período são ISO-8601 (YYYY-MM-DD).
- números de preço são numéricos. Se sua UI requer símbolos de moeda, aplique-os no lado do cliente.
- Taxa & cota: O uso funciona em um modelo de assinatura + cota (não por chamada). As primeiras integrações costumam usar um teste de 7 dias ou 50 solicitações. Verifique a listagem para limites atuais.
Ideias de fluxo de ponta a ponta
Aqui está como os desenvolvedores costumam conectar os endpoints:
- Rota de pesquisa de VIN em seu backend chama Obter dados de preço do veículo e armazena o resultado indexado por VIN com um cache curto TTL.
- Sua UI renderiza:
- o rótulo do veículo (por exemplo, 2001 Infiniti I30 Luxury),
- o preço principal (data.prices.average),
- limites abaixo/acima como uma faixa de listagem sugerida,
- um gráfico de prices.distribution para comunicar a dispersão do mercado,
- certeza como um distintivo de confiança,
- entrada de quilometragem vs. referência e valor de ajuste para transparência.
- Use Obter Fabricantes e Obter Modelos para construir um fluxo de pesquisa guiada quando um usuário não tem um VIN, ou para validar entradas de inventário.
Curl adicional que você pode copiar
Os seguintes comandos curl prontos para uso são úteis para configurar Makefiles, coleções do Postman ou testes de fumaça.
- Obter dados de preço do veículo:
- Obter Fabricantes:
- Obter Modelos (exemplo Audi):
Usando a API de um agente de IA via MCP
Você também pode chamar esta API de ferramentas compatíveis com MCP (Claude Code, Cursor, Windsurf). Aponte seu cliente para o endpoint MCP e inclua sua chave de API Zyla na string de consulta:
- Endpoint MCP: https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY
- Documentos e notas de compatibilidade: MCP
Dentro do seu agente, construa as mesmas URLs HTTPS GET mostradas acima e passe o cabeçalho de Autorização. O MCP permite que seu agente recupere dados de preço de veículos sob demanda, sem embutir outro cliente HTTP em sua cadeia de ferramentas.
Checklist de segurança e implantação
- Não comite YOUR_API_KEY. Armazene-o no gerenciador de segredos da sua plataforma ou em variáveis de ambiente.
- Imponha validação de entrada em vin e maker para prevenir SSRF ou injeção de log. VINs são alfanuméricos e de comprimento fixo.
- Adicione timeouts do lado do servidor e disjuntores para proteger seu aplicativo sob lentidão upstream.
- Registre IDs de solicitação e resumos de resposta (não cargas completas) para manter a telemetria livre de PII.
FAQ
A API requer um VIN para obter preços?
Sim. O endpoint Obter dados de preço do veículo requer o parâmetro de consulta vin.
Posso ajustar a quilometragem na solicitação?
A quilometragem é um fator opcional suportado pelo serviço, mas apenas vin está documentado como um parâmetro de solicitação aqui. Use os parâmetros documentados na página do hub ao construir solicitações.
Em que moeda estão os preços?
A resposta retorna valores numéricos de preço sem um código de moeda. Se sua UI precisar de um rótulo de moeda, aplique-o consistentemente de acordo com o contexto do seu negócio.
Como faço para autenticar?
Envie Authorization: Bearer YOUR_API_KEY em cada chamada para as URLs listadas.
Há um plano gratuito?
Não. O acesso funciona em um modelo de assinatura + cota. Para primeiras integrações, espere um teste de 7 dias ou 50 solicitações; verifique a página da API para opções de acesso e preços atuais.
Pronto para enviar? Inscreva-se e execute o curl acima na página de listagem: Começar teste de 7 dias na API da Calculadora de Valor de Veículos. Sua primeira resposta bem-sucedida incluirá preço médio, faixas de distribuição, confiança e ajuste de quilometragem que você pode integrar ao seu aplicativo hoje.
