Consulta de placa com valor FIPE em Node.js usando a APIBrasil

Quem trabalha com seguros, financiamento, compra e venda de usados ou marketplaces de veículos precisa saber, a partir da placa, qual é o carro e quanto ele vale na Tabela FIPE. Neste tutorial você vai fazer uma consulta de placa com valor FIPE em Node.js usando a API Placa FIPE (Com Chassi) da APIBrasil.

Em uma única chamada você recebe marca, modelo, ano de fabricação e modelo, combustível, cor, código FIPE, o valor atual e o histórico de preços.

O que a API Placa FIPE devolve

A API fica na categoria Precificação Veicular e custa R$ 0,10 por consulta em produção, conforme o catálogo em doc.apibrasil.io. A resposta traz uma lista resultados, porque uma placa pode ter mais de uma versão FIPE compatível. O item com principal: true é o mais provável.

Campo	O que traz
marca, modelo	Fabricante e versão do veículo
anoFabricacao, anoModelo	Ano de fabricação e ano do modelo
combustivel, cor, categoria	Características do veículo
chassi	Chassi (com máscara, conforme a fonte)
codigoFipe, mesReferencia	Código na Tabela FIPE e mês de referência
valor	Valor FIPE atual, em número
historico	Lista de { mes, valor } com a evolução do preço
principal	true no resultado mais provável

Pré-requisitos

• Node.js 18 ou mais novo (o fetch é nativo).
• Bearer Token da APIBrasil, em Credenciais no painel. Se é sua primeira vez, veja os primeiros passos.

Passo 1: crie o projeto

mkdir placa-fipe && cd placa-fipe
npm init -y

Crie um arquivo .env:

APIBRASIL_TOKEN=seu_token_aqui
APIBRASIL_HOMOLOG=true

A partir do Node 20.6 dá para carregar o .env com a flag --env-file, sem instalar nada. Em versões anteriores, use o pacote dotenv.

Passo 2: a chamada

POST https://gateway.apibrasil.io/api/v2/consulta/veiculos/credits
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "tipo": "fipe-chassi",
  "placa": "ABC1234",
  "homolog": true
}

A placa pode estar no padrão antigo (ABC1234) ou no padrão Mercosul (ABC1D23). Envie sem hífen e em maiúsculas.

Passo 3: o código em Node.js

Crie o arquivo placa.js:

const URL = "https://gateway.apibrasil.io/api/v2/consulta/veiculos/credits";

const brl = (n) =>
  n.toLocaleString("pt-BR", { style: "currency", currency: "BRL" });

function normalizarPlaca(placa) {
  const p = placa.toUpperCase().replace(/[^A-Z0-9]/g, "");
  if (!/^[A-Z]{3}[0-9][A-Z0-9][0-9]{2}$/.test(p)) {
    throw new Error("Placa inválida: use ABC1234 ou ABC1D23");
  }
  return p;
}

async function consultarPlaca(placa, tentativas = 3) {
  const corpo = {
    tipo: "fipe-chassi",
    placa: normalizarPlaca(placa),
    homolog: process.env.APIBRASIL_HOMOLOG !== "false",
  };

  for (let t = 1; t <= tentativas; t++) {
    let resp;
    try {
      resp = await fetch(URL, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${process.env.APIBRASIL_TOKEN}`,
        },
        body: JSON.stringify(corpo),
        signal: AbortSignal.timeout(120_000),
      });
    } catch (erro) {
      if (t === tentativas) throw erro; // timeout ou falha de rede
      await new Promise((r) => setTimeout(r, 2 ** t * 1000));
      continue;
    }

    if (resp.status === 402) throw new Error("Saldo insuficiente: recarregue a conta");
    if (resp.status >= 500 && t < tentativas) {
      await new Promise((r) => setTimeout(r, 2 ** t * 1000));
      continue;
    }
    if (!resp.ok) throw new Error(`HTTP ${resp.status}: ${await resp.text()}`);

    const json = await resp.json();
    if (json.error) throw new Error(json.message || "Erro na consulta");
    return json;
  }
}

const placa = process.argv[2];
const r = await consultarPlaca(placa);
const lista = r.data?.resultados ?? [];
const v = lista.find((x) => x.principal) ?? lista[0];

if (!v) {
  console.log("Nenhum resultado FIPE para esta placa");
  process.exit(1);
}

const [atual, anterior] = [...v.historico].reverse();
console.log("Veículo .........", v.marca, v.modelo);
console.log("Ano .............", `${v.anoFabricacao}/${v.anoModelo}`, "·", v.combustivel, "·", v.cor);
console.log("Código FIPE .....", v.codigoFipe);
console.log("Referência ......", v.mesReferencia);
console.log("Valor FIPE ......", brl(v.valor));
if (anterior) {
  const variacao = ((atual.valor - anterior.valor) / anterior.valor) * 100;
  console.log("Mês anterior ....", brl(anterior.valor), `(${variacao.toFixed(2)}%)`);
}

Para usar await no topo do arquivo, adicione "type": "module" no package.json.

Passo 4: rode a consulta

node --env-file=.env placa.js ABC1D23

A ordem do historico pode variar. Se for usar a variação em uma decisão, ordene a lista pelo campo mes antes de comparar.

Ideias de uso

• Cotação de seguro: preencha marca, modelo e ano automaticamente a partir da placa.
• Avaliação de usados: compare o preço anunciado com o valor FIPE e destaque ofertas acima da tabela.
• Garantia em crédito: use o valor FIPE para calcular o limite de um empréstimo com veículo em garantia.
• Gráfico de preço: o historico permite montar um gráfico de desvalorização em poucos minutos.

Boas práticas

• Cache por placa e mês: o valor FIPE muda uma vez por mês. Guardar o resultado por placa e mesReferencia evita pagar duas vezes.
• Mais de um resultado: mostre as outras versões da lista quando principal não bater com o que o usuário informou.
• Homologação em testes: mantenha APIBRASIL_HOMOLOG=true em desenvolvimento e CI.

Perguntas frequentes

A APIBrasil tem outras APIs de veículos?

Sim. As categorias Segurança Veicular e Precificação Veicular têm dezenas de APIs, como débitos, roubo e furto, leilão, gravame, recall e emissão de CRLV. O fluxo de chamada é o mesmo deste tutorial, mudando o tipo e a rota.

Funciona no navegador?

Não faça essa chamada direto do front-end: o token ficaria exposto. Crie uma rota no seu back-end que chama a APIBrasil e devolve só o necessário para a tela. Se precisar de ajuda com isso, veja como criar sua primeira API com Node.js e Express.

Próximos passos

Veja também como calcular a distância entre CEPs e como calcular o piso de frete ANTT com a APIBrasil.