DEV Community

API-DEV
API-DEV

Posted on Fully Autonomous

Como consultar placa de veículo com valor FIPE em Node, Python e PHP

Se você está fazendo sistema para oficina, revenda de carros, despachante, vistoria ou frota, uma hora vai precisar disto: o usuário digita a placa e o formulário se preenche sozinho com os dados do carro e o valor da Tabela FIPE.

Neste tutorial eu mostro como fazer isso com a API Placa & FIPE, que eu criei justamente para esse caso: uma chamada só traz os dados do veículo e a FIPE do mês.

Transparência: eu sou o autor da API. A conta nova vem com 10 consultas grátis, então dá para seguir o tutorial sem pagar nada.

O que a API devolve

Uma consulta básica (tipo=basica) traz:

  • marca, modelo, versão, ano de fabricação e ano do modelo
  • cor, combustível, município e UF
  • situação do veículo e dados técnicos (cilindradas, passageiros, segmento)
  • fipe: código, modelo e valor do mês, já formatado

Ela não traz dados do dono (nome, CPF, endereço). Isso é proposital, por causa da LGPD.

1. Pegue a chave

Crie a conta em placaefipe.com.br/criar-conta e gere a chave no painel. Existem dois tipos:

  • pf_test_...: devolve dados de exemplo e não gasta saldo. Use no desenvolvimento.
  • pf_live_...: a de produção.

Guarde a chave numa variável de ambiente:

# .env (e confira se ele está no .gitignore)
PLACAEFIPE_API_KEY=pf_test_sua_chave
Enter fullscreen mode Exit fullscreen mode

2. Teste com cURL

curl https://api.placaefipe.com.br/v1/placas/ABC1D23 \
  -H "Authorization: Bearer $PLACAEFIPE_API_KEY"
Enter fullscreen mode Exit fullscreen mode

A resposta (resumida) vem assim:

{
  "placa": "ABC1D23",
  "tipo": "basica",
  "marca": "VW",
  "modelo": "CROSSFOX",
  "versao": "CROSSFOX 1.6 Mi Total Flex 8V 5p",
  "ano_fabricacao": 2007,
  "ano_modelo": 2007,
  "cor": "Prata",
  "combustivel": "Alcool / Gasolina",
  "municipio": "São Leopoldo",
  "uf": "RS",
  "situacao": "Sem restrição",
  "fipe": {
    "codigo": "005225-6",
    "modelo": "CROSSFOX 1.6 Mi Total Flex 8V 5p",
    "valor": 28799,
    "valor_texto": "R$ 28.799,00",
    "referencia": "novembro de 2026",
    "versoes": []
  },
  "consulta": { "valor_cobrado": 0.09, "saldo_restante": 0.81, "cobrada": true, "cache": false }
}
Enter fullscreen mode Exit fullscreen mode

Para conferir a chave sem gastar nada, use GET /v1/saldo.

3. Node.js (18+)

fetch já vem no Node, então não precisa de biblioteca:

export async function consultarPlaca(placa, tipo = 'basica') {
  const url = `https://api.placaefipe.com.br/v1/placas/${encodeURIComponent(placa)}?tipo=${tipo}`;
  const r = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.PLACAEFIPE_API_KEY}` },
  });
  const dados = await r.json();
  if (!r.ok) throw new Error(`${dados.erro.codigo}: ${dados.erro.mensagem}`);
  return dados;
}

const v = await consultarPlaca('ABC1D23');
console.log(v.marca, v.modelo, v.ano_modelo, v.fipe?.valor_texto);
Enter fullscreen mode Exit fullscreen mode

4. Python

import os
import requests

def consultar_placa(placa: str, tipo: str = "basica") -> dict:
    r = requests.get(
        f"https://api.placaefipe.com.br/v1/placas/{placa}",
        params={"tipo": tipo},
        headers={"Authorization": f"Bearer {os.environ['PLACAEFIPE_API_KEY']}"},
        timeout=15,
    )
    dados = r.json()
    if not r.ok:
        raise RuntimeError(f"{dados['erro']['codigo']}: {dados['erro']['mensagem']}")
    return dados

v = consultar_placa("ABC1D23")
print(v["marca"], v["modelo"], v["ano_modelo"], (v.get("fipe") or {}).get("valor_texto"))
Enter fullscreen mode Exit fullscreen mode

5. PHP

<?php
function consultarPlaca(string $placa, string $tipo = "basica"): array {
    $url = "https://api.placaefipe.com.br/v1/placas/" . urlencode($placa) . "?tipo=" . urlencode($tipo);
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 15,
        CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("PLACAEFIPE_API_KEY")],
    ]);
    $corpo = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    $dados = json_decode($corpo, true);
    if ($status !== 200) {
        throw new RuntimeException($dados["erro"]["codigo"] . ": " . $dados["erro"]["mensagem"]);
    }
    return $dados;
}

$v = consultarPlaca("ABC1D23");
echo $v["marca"] . " " . $v["modelo"] . " " . ($v["fipe"]["valor_texto"] ?? "sem FIPE");
Enter fullscreen mode Exit fullscreen mode

6. Não coloque a chave no front-end

Esse é o erro mais comum, principalmente em app gerado por IA. Se a chave vai para o navegador, qualquer pessoa abre o DevTools, copia e gasta o seu saldo.

O certo é o front chamar uma rota sua, e essa rota chamar a API. No Next.js (App Router):

// app/api/placa/[placa]/route.ts
export async function GET(_req: Request, { params }: { params: Promise<{ placa: string }> }) {
  const { placa } = await params;
  const r = await fetch(`https://api.placaefipe.com.br/v1/placas/${encodeURIComponent(placa)}?tipo=basica`, {
    headers: { Authorization: `Bearer ${process.env.PLACAEFIPE_API_KEY}` },
    cache: 'no-store',
  });
  return new Response(await r.text(), { status: r.status, headers: { 'Content-Type': 'application/json' } });
}
Enter fullscreen mode Exit fullscreen mode

Proteja essa rota com o login do seu app, para terceiros não usarem ela de graça.

7. FIPE: os três casos

A placa nem sempre diz a versão exata do carro, então trate três situações:

  • fipe.valor preenchido: mostre fipe.valor_texto e "FIPE de {fipe.referencia}".
  • fipe.valor nulo e fipe.versoes com itens: deixe o usuário escolher a versão (1.6, 2.0...). Cada item tem seu valor_texto.
  • fipe nulo: "FIPE não encontrada para este veículo".

8. Erros

Use sempre erro.codigo, nunca o texto da mensagem:

HTTP erro.codigo O que fazer
400 placa_invalida Pedir para o usuário conferir a placa
401 chave_invalida Erro de configuração, avise o admin
402 saldo_insuficiente Avisar o admin para colocar saldo
404 placa_nao_encontrada "Veículo não encontrado"
429 limite_excedido Esperar 1 s e tentar de novo uma vez
503 indisponivel Tentar até 3 vezes (1 s, 2 s, 4 s)

Nenhum erro desconta saldo, nem placa não encontrada.

Bônus: deixar a IA integrar por você

Se você usa Cursor, Claude Code, Lovable ou Bolt, a documentação tem um guia escrito para agentes de IA. Cole isto no chat:

Integre a API Placa & FIPE (consulta de veículo pela placa com valor FIPE) neste projeto.
Leia e siga o guia oficial para agentes: https://placaefipe.com.br/guia-ia.md
Enter fullscreen mode Exit fullscreen mode

Ele cria o cliente no servidor, a variável de ambiente e o tratamento de erros. Também existe um servidor MCP (https://api.placaefipe.com.br/mcp) para consultar placas direto na conversa com a IA. Os comandos de cada ferramenta estão em docs/mcp.

Preço

  • 10 consultas grátis no cadastro, sem cartão
  • R$ 0,09 por consulta básica com FIPE depois disso, com saldo no Pix e sem mensalidade
  • Placa não encontrada não é cobrada

Documentação completa: placaefipe.com.br/docs. Se ficar alguma dúvida, comenta aqui que eu respondo.

Top comments (0)