Copy page

Documentação

Guia de Início Rápido

Neste guia você fará suas primeiras consultas à API FIPE em JavaScript usando a biblioteca fipe-promise: navegar pela hierarquia de marcas, modelos e anos e, ao final, obter o preço de um veículo.

Pré-requisitos

• Conhecimento básico de JavaScript.
• Um ambiente que execute JavaScript moderno (navegador ou Node.js 18+).

Como funciona a consulta

A API organiza os dados em uma hierarquia de quatro níveis:

Marca → Modelo → Ano → Preço

A biblioteca expõe um método para cada nível — fetchBrands, fetchModels, fetchYears e fetchDetail — que você encadeia até chegar ao preço. Se já tiver o código FIPE, pode pular as etapas iniciais e consultar o preço diretamente com fetchDetailByFipeCode.

Instalação e configuração

A fipe-promise é um cliente para a API FIPE que cuida das requisições HTTP, do envio do token e do tratamento de erros, devolvendo promessas com os dados já em JSON.

Code
npm i fipe-promise

Importe a biblioteca e, opcionalmente, defina seu token. Todos os métodos aceitam um último argumento options com os campos token e reference.

Code
import * as fipe from 'fipe-promise';

// Opcional: aumenta o limite diário de requisições
const options = { token: 'seu_token_aqui' };

Exemplos práticos

Consulta passo a passo: Volkswagen Gol

Este exemplo percorre toda a hierarquia, da marca ao preço, imprimindo o resultado da etapa final.

Code
import * as fipe from 'fipe-promise';

async function buscarPrecoGol() {
    const marcas = await fipe.fetchBrands(fipe.vehicleType.CARS);
    const volkswagen = marcas.find(marca => marca.name.includes('VolksWagen'));

    const modelos = await fipe.fetchModels(fipe.vehicleType.CARS, volkswagen.code);
    const gol = modelos.find(modelo => modelo.name.includes('Gol'));

    const anos = await fipe.fetchYears(fipe.vehicleType.CARS, volkswagen.code, gol.code);
    const anoMaisRecente = anos[0];

    const detalhes = await fipe.fetchDetail(
        fipe.vehicleType.CARS,
        volkswagen.code,
        gol.code,
        anoMaisRecente.code
    );

    console.log(`Modelo: ${detalhes.model}`);
    console.log(`Ano: ${detalhes.modelYear}`);
    console.log(`Preço: ${detalhes.price}`);
    console.log(`Combustível: ${detalhes.fuel}`);

    return detalhes;
}

buscarPrecoGol();

Busca direta por código FIPE

Quando você já tem o código FIPE, consulte o preço sem percorrer marcas e modelos. Se o ano não for informado, o código usa o ano mais recente disponível.

Code
import * as fipe from 'fipe-promise';

async function buscarPorCodigoFipe(codigoFipe, ano = null) {
    if (!ano) {
        const anos = await fipe.fetchYearsByFipeCode(fipe.vehicleType.CARS, codigoFipe);
        ano = anos[0].code;
    }

    const veiculo = await fipe.fetchDetailByFipeCode(fipe.vehicleType.CARS, codigoFipe, ano);

    console.log(`Código FIPE: ${veiculo.codeFipe}`);
    console.log(`Modelo: ${veiculo.model}`);
    console.log(`Preço: ${veiculo.price}`);

    return veiculo;
}

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

Função genérica para qualquer veículo

Esta função recebe o tipo de veículo (fipe.vehicleType.CARS, MOTORCYCLES ou TRUCKS), o nome da marca e do modelo e, opcionalmente, o ano. Ela serve de base para os demais casos de uso.

Code
import * as fipe from 'fipe-promise';

async function buscarVeiculo(tipo, marcaNome, modeloNome, anoEscolhido = null) {
    const marcas = await fipe.fetchBrands(tipo);
    const marca = marcas.find(m =>
        m.name.toLowerCase().includes(marcaNome.toLowerCase())
    );

    if (!marca) {
        throw new Error(`Marca "${marcaNome}" não encontrada`);
    }

    const modelos = await fipe.fetchModels(tipo, marca.code);
    const modelo = modelos.find(m =>
        m.name.toLowerCase().includes(modeloNome.toLowerCase())
    );

    if (!modelo) {
        throw new Error(`Modelo "${modeloNome}" não encontrado`);
    }

    const anos = await fipe.fetchYears(tipo, marca.code, modelo.code);

    let anoSelecionado = anos[0];
    if (anoEscolhido) {
        anoSelecionado = anos.find(a => a.name.includes(anoEscolhido));
    }

    return fipe.fetchDetail(tipo, marca.code, modelo.code, anoSelecionado.code);
}

buscarVeiculo(fipe.vehicleType.CARS, 'Toyota', 'Corolla', '2023')
    .then(veiculo => console.log('Toyota Corolla:', veiculo));

buscarVeiculo(fipe.vehicleType.MOTORCYCLES, 'Honda', 'CB', '2022')
    .then(moto => console.log('Honda CB:', moto));

Comparação de preços

Reutilizando buscarVeiculo, este exemplo consulta vários veículos e ordena o resultado do mais barato ao mais caro.

Code
import * as fipe from 'fipe-promise';

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);
        }
    }

    resultados.sort((a, b) => a.precoNumerico - b.precoNumerico);

    resultados.forEach((resultado, index) => {
        console.log(`${index + 1}º ${resultado.nome}: ${resultado.preco}`);
    });

    return resultados;
}

compararVeiculos([
    { tipo: fipe.vehicleType.CARS, marca: 'Volkswagen', modelo: 'Gol', ano: '2023' },
    { tipo: fipe.vehicleType.CARS, marca: 'Chevrolet', modelo: 'Onix', ano: '2023' },
    { tipo: fipe.vehicleType.CARS, marca: 'Fiat', modelo: 'Argo', ano: '2023' }
]);

Boas práticas

• Use um token. Passe-o em options (fipe.fetchBrands(fipe.vehicleType.CARS, { token })) para elevar o limite de 500 para 1.000 requisições por dia.
• Faça cache das listas estáveis. Marcas e modelos mudam pouco; armazená-los localmente evita requisições repetidas.
• Paralelize consultas independentes com Promise.all() em vez de aguardar uma a uma.
• Trate os erros por requisição. A biblioteca rejeita a promessa em caso de falha; envolva chamadas individuais em try/catch para que um erro isolado não interrompa todo o fluxo.

Solução de problemas

Erro 429 – Limite de requisições

Você atingiu o limite diário. O contador é reiniciado a cada 24 horas. Para uso sem esse limite, consulte os planos Premium, que oferecem requisições ilimitadas.

Erro 404 – Recurso não encontrado

O recurso solicitado não existe. As causas mais comuns são:

• Código FIPE inválido — confira se o código está correto.
• Combinação inexistente — a combinação marca/modelo/ano não consta na base FIPE.
• Identificadores incorretos — revise os códigos de marca, modelo e ano.

Para validar cada nível antes de consultar o preço:

Code
import * as fipe from 'fipe-promise';

async function recursoExiste(tipo, codigoMarca, codigoModelo, codigoAno) {
    const marcas = await fipe.fetchBrands(tipo);
    if (!marcas.some(m => m.code === codigoMarca)) {
        return false;
    }

    const modelos = await fipe.fetchModels(tipo, codigoMarca);
    if (!modelos.some(m => m.code === codigoModelo)) {
        return false;
    }

    const anos = await fipe.fetchYears(tipo, codigoMarca, codigoModelo);
    return anos.some(a => a.code === codigoAno);
}

Modelo não encontrado

Os nomes na base FIPE nem sempre coincidem exatamente com o termo buscado. Tente a correspondência exata e recorra à parcial quando ela falhar:

Code
function encontrarModelo(modelos, termo) {
    const alvo = termo.toLowerCase();

    return (
        modelos.find(m => m.name.toLowerCase() === alvo) ||
        modelos.find(m => m.name.toLowerCase().includes(alvo))
    );
}

Próximos passos

• Consulte a Referência da API para a lista completa de endpoints.
• Veja Ideias de uso prático para aplicações da API em projetos reais.
• A fipe-promise também oferece fetchPriceHistory (histórico de preços) e fetchReferences (meses de referência da tabela) para consultas históricas.