A partir da versão 2.0.0 esta biblioteca utiliza a API v2 da Parallelum. Mudanças incompatíveis: a URL base agora é https://fipe.parallelum.com.br/api/v2/, os segmentos de caminho passaram a ser em inglês (cars, motorcycles, trucks) e a resposta de fetchModels agora é um array direto (antes era { modelos: [...] }).

Instalação

Browser usando CDN

<script src="https://cdn.jsdelivr.net/npm/fipe-promise/dist/fipe-promise.min.js"></script>

npm

$ npm install --save fipe-promise

Bower

$ bower install --save deividfortuna/fipe-promise

yarn

$ yarn add fipe-promise

Uso

Todos os métodos aceitam um último parâmetro opcional options com o seguinte formato:

{
  reference: 280,        // Código do mês de referência da tabela FIPE (opcional)
  token: 'seu-token'     // X-Subscription-Token para aumentar o limite de requisições (opcional)
}

Consultar marcas

Para consultar as marcas disponíveis para um determinado tipo de veículo, utilize o método fetchBrands. O método recebe um parâmetro obrigatório: o tipo de veículo (cars, motorcycles ou trucks). Exemplo:

fipe
  .fetchBrands(fipe.vehicleType.CARS)
  .then((brands) => {
    // Faça algo com o array de marcas retornado
  })
  .catch((error) => {
    // Lide com o erro aqui
  });

Consultar modelos

Para consultar os modelos disponíveis para uma determinada marca, utilize o método fetchModels. O método recebe dois parâmetros obrigatórios: o tipo de veículo e o identificador da marca. Exemplo:

fipe
  .fetchModels(fipe.vehicleType.CARS, 21)
  .then((models) => {
    // Faça algo com o array de modelos retornado
  })
  .catch((error) => {
    // Lide com o erro aqui
  });

Consultar anos pelos modelos

Para consultar os anos pelos modelos disponíveis, utilize o método fetchYears. O método recebe três parâmetros obrigatórios: o tipo de veículo, o identificador da marca e o identificador do modelo. Exemplo:

fipe
  .fetchYears(fipe.vehicleType.CARS, 21, 4828)
  .then((years) => {
    // Faça algo com o array de anos/modelos retornado
  })
  .catch((error) => {
    // Lide com o erro aqui
  });

Consultar detalhes

Para consultar os detalhes de um determinado veículo (preço médio, código FIPE, marca, modelo e ano/modelo), utilize o método fetchDetail. O método recebe quatro parâmetros obrigatórios: o tipo de veículo, o identificador da marca, o identificador do modelo e o ano/modelo no formato "yyyy-X". Exemplo:

fipe
  .fetchDetail(fipe.vehicleType.CARS, 21, 4828, "2015-1")
  .then((detail) => {
    // Faça algo com o objeto de detalhes retornado
  })
  .catch((error) => {
    // Lide com o erro aqui
  });

Consultar tabelas de referência

Retorna a lista de meses de referência disponíveis (code e month). Útil para passar o code como options.reference nas demais chamadas.

fipe.fetchReferences().then((references) => {
  // [{ code: '278', month: 'abril de 2024' }, ...]
});

Consultar por código FIPE

A API v2 permite consultar diretamente pelo código FIPE (ex.: 004278-1), sem precisar navegar por marca e modelo.

fipe
  .fetchYearsByFipeCode(fipe.vehicleType.CARS, "004278-1")
  .then((years) => { /* ... */ });

fipe
  .fetchDetailByFipeCode(fipe.vehicleType.CARS, "004278-1", "2014-3")
  .then((detail) => { /* ... */ });

Histórico de preços

Retorna os detalhes do veículo junto com o histórico de preços (priceHistory).

fipe
  .fetchPriceHistory(fipe.vehicleType.CARS, "004278-1", "2014-3")
  .then((detail) => {
    // detail.priceHistory => [{ month, price, reference }, ...]
  });

Usando reference e token

fipe.fetchBrands(fipe.vehicleType.CARS, {
  reference: 278,
  token: "seu-token-de-assinatura"
});

Exemplo Angular 2+

import * as fipe from "fipe-promise";

fipe.fetchBrands(fipe.vehicleType.CARS).then(console.log);

Contribuição

Contribuições são sempre bem-vindas! Se você encontrar um bug ou tiver uma ideia para uma nova funcionalidade, fique à vontade para abrir uma issue ou enviar um pull request.

Licença

Este projeto é licenciado sob a MIT License.