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.
Top comments (0)