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 2. Teste com cURL
curl https://api.placaefipe.com.br/v1/placas/ABC1D23 \ -H "Authorization: Bearer $PLACAEFIPE_API_KEY" 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 } } 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); 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")) 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"); 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' } }); } 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.valorpreenchido: mostrefipe.valor_textoe "FIPE de {fipe.referencia}". -
fipe.valornulo efipe.versoescom itens: deixe o usuário escolher a versão (1.6, 2.0...). Cada item tem seuvalor_texto. -
fipenulo: "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 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.
