Guia de Início Rápido

Este guia mostra como começar a usar a API FIPE em poucos minutos. Você aprenderá a fazer consultas básicas e obter preços de veículos usando JavaScript.

📋 Pré-requisitos

Conhecimento básico em JavaScript
Acesso à internet para fazer requisições HTTP
(Opcional) Token de acesso gratuito para mais requisições

🎯 Fluxos Principais

A API FIPE funciona com uma hierarquia simples:

Marca → 2. Modelo → 3. Ano → 4. Preço

Você também pode buscar diretamente por Código FIPE se já souber.

🟨 JavaScript (Fetch API)

1️⃣ Configuração Básica

const API_BASE = 'https://fipe.parallelum.com.br/api/v2';
const TOKEN = 'seu_token_aqui'; // Opcional, mas recomendado

// Função helper para fazer requisições
async function fipeRequest(endpoint, token = null) {
    const headers = {
        'Content-Type': 'application/json'
    };
    
    if (token) {
        headers['X-Subscription-Token'] = token;
    }
    
    try {
        const response = await fetch(`${API_BASE}${endpoint}`, { headers });
        
        if (!response.ok) {
            throw new Error(`Erro ${response.status}: ${response.statusText}`);
        }
        
        return await response.json();
    } catch (error) {
        console.error('Erro na requisição:', error);
        throw error;
    }
}
javascript

2️⃣ Exemplo: Buscar Preço de um Volkswagen Gol

async function buscarPrecoGol() {
    try {
        // 1. Obter marcas de carros
        const marcas = await fipeRequest('/cars/brands');
        console.log('Marcas disponíveis:', marcas.slice(0, 5)); // Primeiras 5
        
        // 2. Encontrar Volkswagen (código 59)
        const volkswagen = marcas.find(marca => marca.name.includes('VolksWagen'));
        console.log('Volkswagen encontrada:', volkswagen);
        
        // 3. Obter modelos da Volkswagen
        const modelos = await fipeRequest(`/cars/brands/${volkswagen.code}/models`);
        
        // 4. Encontrar Gol
        const gol = modelos.find(modelo => modelo.name.includes('Gol'));
        console.log('Gol encontrado:', gol);
        
        // 5. Obter anos disponíveis do Gol
        const anos = await fipeRequest(`/cars/brands/${volkswagen.code}/models/${gol.code}/years`);
        console.log('Anos disponíveis:', anos.slice(0, 3)); // Primeiros 3
        
        // 6. Obter preço do Gol mais recente
        const anoRecente = anos[0]; // Primeiro ano (mais recente)
        const detalhes = await fipeRequest(
            `/cars/brands/${volkswagen.code}/models/${gol.code}/years/${anoRecente.code}`
        );
        
        console.log('🚗 Detalhes do veículo:');
        console.log(`Modelo: ${detalhes.model}`);
        console.log(`Ano: ${detalhes.modelYear}`);
        console.log(`Preço: ${detalhes.price}`);
        console.log(`Combustível: ${detalhes.fuel}`);
        
        return detalhes;
        
    } catch (error) {
        console.error('Erro ao buscar preço:', error);
    }
}

// Executar a busca
buscarPrecoGol();
javascript

3️⃣ Exemplo: Busca Direta por Código FIPE

async function buscarPorCodigoFipe(codigoFipe, ano = null) {
    try {
        // Se não informar ano, buscar anos disponíveis primeiro
        if (!ano) {
            const anos = await fipeRequest(`/cars/${codigoFipe}/years`);
            ano = anos[0].code; // Pegar o primeiro ano
        }
        
        const veiculo = await fipeRequest(`/cars/${codigoFipe}/years/${ano}`);
        
        console.log('🔍 Busca por código FIPE:');
        console.log(`Código FIPE: ${veiculo.codeFipe}`);
        console.log(`Modelo: ${veiculo.model}`);
        console.log(`Preço: ${veiculo.price}`);
        
        return veiculo;
        
    } catch (error) {
        console.error('Erro na busca por código FIPE:', error);
    }
}

// Buscar Honda Civic 2020 (exemplo)
buscarPorCodigoFipe('004278-1', '2020-1');
javascript

4️⃣ Função Genérica para Qualquer Veículo

async function buscarVeiculo(tipo, marcaNome, modeloNome, anoEscolhido = null) {
    try {
        // 1. Buscar marcas
        const marcas = await fipeRequest(`/${tipo}/brands`);
        const marca = marcas.find(m => 
            m.name.toLowerCase().includes(marcaNome.toLowerCase())
        );
        
        if (!marca) {
            throw new Error(`Marca "${marcaNome}" não encontrada`);
        }
        
        // 2. Buscar modelos
        const modelos = await fipeRequest(`/${tipo}/brands/${marca.code}/models`);
        const modelo = modelos.find(m => 
            m.name.toLowerCase().includes(modeloNome.toLowerCase())
        );
        
        if (!modelo) {
            throw new Error(`Modelo "${modeloNome}" não encontrado`);
        }
        
        // 3. Buscar anos
        const anos = await fipeRequest(
            `/${tipo}/brands/${marca.code}/models/${modelo.code}/years`
        );
        
        let anoSelecionado = anos[0]; // Padrão: mais recente
        if (anoEscolhido) {
            anoSelecionado = anos.find(a => a.name.includes(anoEscolhido));
        }
        
        // 4. Obter detalhes
        const detalhes = await fipeRequest(
            `/${tipo}/brands/${marca.code}/models/${modelo.code}/years/${anoSelecionado.code}`
        );
        
        return detalhes;
        
    } catch (error) {
        console.error('Erro:', error.message);
        throw error;
    }
}

// Exemplos de uso
buscarVeiculo('cars', 'Toyota', 'Corolla', '2023')
    .then(veiculo => console.log('Toyota Corolla:', veiculo));

buscarVeiculo('motorcycles', 'Honda', 'CB', '2022')
    .then(moto => console.log('Honda CB:', moto));
javascript

🎯 Casos de Uso Comuns

JavaScript: Comparador de Preços

async function compararVeiculos(veiculos) {
    const resultados = [];
    
    for (const veiculo of veiculos) {
        try {
            const dados = await buscarVeiculo(
                veiculo.tipo, 
                veiculo.marca, 
                veiculo.modelo, 
                veiculo.ano
            );
            
            resultados.push({
                nome: `${veiculo.marca} ${veiculo.modelo} ${veiculo.ano}`,
                preco: dados.price,
                precoNumerico: parseFloat(dados.price.replace(/[R$\s.]/g, '').replace(',', '.'))
            });
        } catch (error) {
            console.error(`Erro ao buscar ${veiculo.marca} ${veiculo.modelo}:`, error.message);
        }
    }
    
    // Ordenar por preço
    resultados.sort((a, b) => a.precoNumerico - b.precoNumerico);
    
    console.log('🏆 COMPARAÇÃO DE PREÇOS:');
    resultados.forEach((resultado, index) => {
        console.log(`${index + 1}º ${resultado.nome}: ${resultado.preco}`);
    });
    
    return resultados;
}

// Comparar carros populares
compararVeiculos([
    { tipo: 'cars', marca: 'Volkswagen', modelo: 'Gol', ano: '2023' },
    { tipo: 'cars', marca: 'Chevrolet', modelo: 'Onix', ano: '2023' },
    { tipo: 'cars', marca: 'Fiat', modelo: 'Argo', ano: '2023' }
]);
javascript

⚡ Dicas de Performance

Use Token: Aumente seu limite de 500 para 1.000 requisições/dia
Cache Inteligente: Guarde listas de marcas e modelos localmente
Requisições Paralelas: Use Promise.all() para múltiplas consultas
Tratamento de Erros: Sempre implemente try/catch adequados

🔧 Troubleshooting

❌ Erro 429 (Too Many Requests)

Este erro indica que você atingiu o limite diário de requisições. Você tem duas opções:

Aguardar: O limite é reiniciado a cada 24 horas
Token Pro: Obtenha um token pro com requisições ilimitadas

❌ Erro 404 (Not Found)

Este erro indica que o recurso ou informação do veículo solicitado não existe. Possíveis causas:

Código FIPE inválido: Verifique se o código está correto
Combinação inexistente: Marca/modelo/ano não disponível na base FIPE
Endpoint incorreto: URL da requisição pode estar mal formada

// Verificar se recurso existe antes de buscar detalhes
async function verificarRecursoExiste(tipo, codigoMarca, codigoModelo, codigoAno) {
    try {
        // Verificar se a marca existe
        const marcas = await fipeRequest(`/${tipo}/brands`);
        const marcaExiste = marcas.find(m => m.code === codigoMarca);
        
        if (!marcaExiste) {
            throw new Error(`Marca com código ${codigoMarca} não encontrada`);
        }
        
        // Verificar se o modelo existe
        const modelos = await fipeRequest(`/${tipo}/brands/${codigoMarca}/models`);
        const modeloExiste = modelos.find(m => m.code === codigoModelo);
        
        if (!modeloExiste) {
            throw new Error(`Modelo com código ${codigoModelo} não encontrado`);
        }
        
        // Verificar se o ano existe
        const anos = await fipeRequest(`/${tipo}/brands/${codigoMarca}/models/${codigoModelo}/years`);
        const anoExiste = anos.find(a => a.code === codigoAno);
        
        if (!anoExiste) {
            throw new Error(`Ano com código ${codigoAno} não encontrado`);
        }
        
        return true;
        
    } catch (error) {
        console.error('Recurso não existe:', error.message);
        return false;
    }
}
javascript

❌ Modelo não encontrado

// Busca mais flexível
function encontrarModelo(modelos, termo) {
    // Busca exata primeiro
    let modelo = modelos.find(m => m.name.toLowerCase() === termo.toLowerCase());
    
    // Se não encontrar, busca parcial
    if (!modelo) {
        modelo = modelos.find(m => 
            m.name.toLowerCase().includes(termo.toLowerCase())
        );
    }
    
    return modelo;
}
javascript

Pronto! Agora você tem tudo que precisa para começar a usar a API FIPE. Explore os endpoints completos ou veja mais casos de uso na documentação.

Introdução Ideias de uso prático