Skip to content

About

SDKs oficiais (JavaScript e Python) e exemplos da API de Placa e FIPE: consulta de veículo pela placa com Tabela FIPE, Renavam, chassi e motor. MCP para Claude, Cursor e Gemini.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

API de Placa e FIPE — SDKs e exemplos (Placa & FIPE)

Licença MIT Docs OpenAPI MCP

SDKs oficiais (JavaScript/TypeScript e Python) e exemplos prontos da Placa & FIPE, uma API de consulta de placa de veículo brasileira. Você manda a placa, antiga (ABC1234) ou Mercosul (ABC1D23), e recebe em JSON a marca, o modelo, a versão, o ano, a cor, o combustível, o município, a UF, a situação e o valor da Tabela FIPE do mês, tudo numa chamada. Também dá para pegar o Renavam pela placa, o chassi pela placa e o número do motor.

  • API REST em https://api.placaefipe.com.br/v1, autenticada por chave.
  • Servidor MCP para Claude, Cursor, Gemini CLI, Antigravity, Codex, Windsurf e VS Code consultarem placas durante a conversa.
  • Saldo em reais, sem mensalidade. Cada consulta desconta o preço do seu tipo, e só quando o dado é encontrado. Placa não encontrada e erros não descontam nada.
  • Sem dados do proprietário. Nenhum tipo de consulta devolve nome, CPF ou endereço (LGPD).

Comece grátis: 10 consultas básicas grátis ao criar a conta. Crie sua conta e gere a chave no painel. Não pede cartão.

Se você procurou "api placa", "api fipe" ou "consulta placa github", este repositório tem o código para integrar em poucos minutos.

Sumário

Início rápido

  1. Crie a conta e copie a chave pf_live_... no painel. Para desenvolver sem gastar, gere também uma chave de teste pf_test_...: ela devolve dados de exemplo de graça, e a placa AAA0000 simula "não encontrada".
  2. Guarde a chave na variável de ambiente PLACAEFIPE_API_KEY do seu servidor.
  3. Faça a primeira consulta.

cURL

# Básica + FIPE (padrão)
curl https://api.placaefipe.com.br/v1/placas/ABC1D23 \
  -H "Authorization: Bearer $PLACAEFIPE_API_KEY"

# Completa: + chassi, Renavam e número do motor
curl "https://api.placaefipe.com.br/v1/placas/ABC1D23?tipo=completa" \
  -H "Authorization: Bearer $PLACAEFIPE_API_KEY"

# Saldo (grátis) e tabela de preços (pública, sem chave)
curl https://api.placaefipe.com.br/v1/saldo -H "Authorization: Bearer $PLACAEFIPE_API_KEY"
curl https://api.placaefipe.com.br/v1/precos

JavaScript (Node 18+)

npm install github:mirtera157/placaefipe-api
import { PlacaEFipe, ErroPlacaEFipe } from 'placaefipe';

const pf = new PlacaEFipe(); // lê PLACAEFIPE_API_KEY

try {
  const v = await pf.consultarPlaca('ABC1D23'); // tipo padrão: 'basica'
  console.log(v.marca, v.modelo, v.ano_modelo, v.fipe?.valor_texto);

  const c = await pf.consultarPlaca('ABC1D23', { tipo: 'completa' });
  console.log(c.identificacao?.chassi, c.identificacao?.renavam);
} catch (e) {
  if (e instanceof ErroPlacaEFipe && e.codigo === 'placa_nao_encontrada') {
    console.log('Veículo não encontrado (nada foi descontado)');
  } else throw e;
}

Python (3.8+)

pip install "git+https://github.com/mirtera157/placaefipe-api.git#subdirectory=python"
from placaefipe import PlacaEFipe, ErroPlacaEFipe

pf = PlacaEFipe()  # lê PLACAEFIPE_API_KEY

try:
    v = pf.consultar_placa("ABC1D23")  # tipo padrão: "basica"
    print(v["marca"], v["modelo"], v["ano_modelo"], (v.get("fipe") or {}).get("valor_texto"))

    c = pf.consultar_placa("ABC1D23", tipo="renavam")
    print(c["identificacao"]["renavam"])
except ErroPlacaEFipe as e:
    if e.codigo == "placa_nao_encontrada":
        print("Veículo não encontrado (nada foi descontado)")
    else:
        raise

Tipos de consulta e preços

Escolha com o parâmetro ?tipo= em GET /v1/placas/{placa}. Sem tipo, a consulta é basica. Preços de lançamento com 50% de desconto, conferidos em GET /v1/precos em novembro de 2026:

tipo Nome Preço Inclui FIPE Retorna
basica (padrão) Consulta básica + FIPE R$ 0,18 R$ 0,09 sim Marca, modelo, versão, ano, cor, combustível, município, UF, final do chassi e o valor da Tabela FIPE do mês
completa Consulta completa R$ 1,20 R$ 0,60 sim Tudo da básica + FIPE, mais o chassi completo, o número do motor e o Renavam
renavam Consulta Renavam R$ 0,72 R$ 0,36 não Só o número do Renavam
chassi Consulta de chassi R$ 0,72 R$ 0,36 não Só o chassi completo (VIN)
motor Consulta de número do motor R$ 0,72 R$ 0,36 não Só o número do motor gravado no bloco

Os preços podem mudar. A tabela atualizada sai em JSON, sem chave, em https://api.placaefipe.com.br/v1/precos e na página de preços. O saldo é colocado por Pix, de R$ 25 a R$ 5.000, e não expira.

Resposta

Exemplo de GET /v1/placas/INT8C36 (básica):

{
  "placa": "INT8C36",
  "placa_antiga": "INT8236",
  "marca": "VW",
  "modelo": "CROSSFOX",
  "versao": "CROSSFOX 1.6 Mi Total Flex 8V 5p",
  "ano_fabricacao": 2007,
  "ano_modelo": 2007,
  "cor": "Prata",
  "combustivel": "Alcool / Gasolina",
  "chassi_final": "04251",
  "municipio": "São Leopoldo",
  "uf": "RS",
  "situacao": "Sem restrição",
  "origem": "Nacional",
  "tecnico": { "motor": "1.6", "tipo": "Automovel", "especie": "Passageiro", "segmento": "AU - HATCH PEQUENO", "cilindradas": 1599, "passageiros": 5, "eixos": 2 },
  "fipe": {
    "codigo": "005225-6",
    "marca": "VW - VolksWagen",
    "modelo": "CROSSFOX 1.6 Mi Total Flex 8V 5p",
    "ano_modelo": 2007,
    "combustivel": "Gasolina",
    "valor": 28799.0,
    "valor_texto": "R$ 28.799,00",
    "referencia": "novembro de 2026",
    "versoes": []
  },
  "tipo": "basica",
  "consulta": { "id": "cns_7Hq2LmXa9P", "tipo": "basica", "valor_cobrado": 0.09, "saldo_restante": 24.31, "cobrada": true, "cache": false }
}
  • Na completa vem também identificacao: { chassi, renavam, numero_motor }.
  • Nos avulsos (renavam, chassi, motor) vêm só placa, tipo, identificacao (com a chave daquele tipo) e consulta.
  • Qualquer campo do veículo pode vir null. Trate todos como opcionais, exceto placa, tipo e consulta.
  • Quando a FIPE tem mais de uma versão possível, fipe.valor vem null e fipe.versoes traz a lista com o valor de cada uma. Detalhes em FIPE pela placa.

Referência campo a campo: Consultar placa.

Erros

Todo erro vem com o HTTP certo e o corpo { "erro": { "codigo", "mensagem", "docs" } }. Use erro.codigo na sua lógica, porque o texto da mensagem pode mudar. Nenhum erro desconta saldo.

HTTP erro.codigo O que fazer
400 placa_invalida Peça ao usuário para conferir a placa (ABC1234 ou ABC1D23). Não repita.
400 tipo_invalido Use basica, completa, renavam, chassi ou motor.
400 tipo_indisponivel O tipo existe mas não está liberado. Use outro.
401 nao_autenticado Envie Authorization: Bearer pf_live_....
401 chave_invalida Chave errada ou revogada. Gere outra no painel.
402 saldo_insuficiente Coloque saldo por Pix no painel.
404 placa_nao_encontrada Mostre "veículo não encontrado". Nada foi cobrado.
429 limite_excedido Mais de 10 req/s na chave. Espere 1 s e repita.
429 limite_da_chave A chave chegou ao teto mensal de gasto definido no painel.
503 indisponivel Instabilidade temporária. Repita em 2 a 5 s, até 3 vezes.
500 erro_interno Repita; se continuar, fale com o suporte.

Os SDKs transformam esses erros em ErroPlacaEFipe, com codigo, status, mensagem e docs. Eles também usam três códigos próprios, com status: 0 nos dois primeiros: timeout, erro_de_rede e resposta_invalida. A lista completa está em Erros.

SDK JavaScript / TypeScript

Pasta js/. Não tem dependências: usa o fetch global do Node 18+, Deno, Bun e edge runtimes. É ESM e vem com tipos TypeScript para todas as respostas e erros.

import { PlacaEFipe } from 'placaefipe';

const pf = new PlacaEFipe({ apiKey: process.env.PLACAEFIPE_API_KEY, timeoutMs: 20000 });
await pf.consultarPlaca('ABC-1D23', { tipo: 'chassi' }); // traço e minúsculas são aceitos
await pf.saldo();                                        // grátis
await PlacaEFipe.precos();                               // público, sem chave

Documentação do pacote: js/README.md.

SDK Python

Pasta python/. Não tem dependências: usa urllib da biblioteca padrão. As respostas têm tipos (TypedDict) e o pacote inclui py.typed.

from placaefipe import PlacaEFipe

pf = PlacaEFipe(api_key="pf_test_...", timeout=20)
pf.consultar_placa("ABC1D23", tipo="completa")
pf.saldo()
pf.precos()

Documentação do pacote: python/README.md.

Exemplos em outras linguagens

Todos leem a chave de PLACAEFIPE_API_KEY e mostram o uso de ?tipo=.

Arquivo O que mostra
examples/curl.sh Todos os tipos, saldo, preços e cabeçalhos de cobrança
examples/node.mjs Node 18+ com fetch, tratamento de erro e FIPE com várias versões
examples/nextjs-route.ts Rota do App Router que guarda a chave no servidor
examples/python.py Python só com biblioteca padrão
examples/php.php PHP com cURL e exceção tipada
examples/go/main.go Go com structs tipadas
examples/supabase-edge-function.ts Edge Function do Supabase com CORS
examples/n8n.md Nó HTTP Request do n8n, passo a passo

Servidor MCP (Claude, Cursor, Gemini…)

O MCP deixa o seu assistente de IA consultar placas durante a conversa. Por exemplo: "qual o valor FIPE da placa ABC1D23?".

  • URL: https://api.placaefipe.com.br/mcp (Streamable HTTP)
  • Autenticação: Authorization: Bearer SUA_CHAVE
  • Ferramentas: consultar_placa(placa, tipo?) e consultar_saldo (grátis)
  • Discovery: /.well-known/mcp.json

Claude Code

claude mcp add --transport http placaefipe https://api.placaefipe.com.br/mcp --header "Authorization: Bearer SUA_CHAVE"

Cursor: .cursor/mcp.json (ou ~/.cursor/mcp.json)

{
  "mcpServers": {
    "placaefipe": {
      "url": "https://api.placaefipe.com.br/mcp",
      "headers": { "Authorization": "Bearer SUA_CHAVE" }
    }
  }
}

Gemini CLI: ~/.gemini/settings.json

{
  "mcpServers": {
    "placaefipe": {
      "httpUrl": "https://api.placaefipe.com.br/mcp",
      "headers": { "Authorization": "Bearer SUA_CHAVE" }
    }
  }
}

OpenAI Codex: ~/.codex/config.toml

[mcp_servers.placaefipe]
url = "https://api.placaefipe.com.br/mcp"
bearer_token_env_var = "PLACAEFIPE_API_KEY"

VS Code (Copilot): .vscode/mcp.json

{
  "servers": {
    "placaefipe": {
      "type": "http",
      "url": "https://api.placaefipe.com.br/mcp",
      "headers": { "Authorization": "Bearer ${input:placaefipe-key}" }
    }
  },
  "inputs": [
    { "type": "promptString", "id": "placaefipe-key", "description": "Chave Placa & FIPE", "password": true }
  ]
}

Windsurf, Google Antigravity e Claude Desktop: veja Servidor MCP. Para a IA escrever a integração por você, aponte-a para o guia para IA ou o llms.txt.

O MCP serve para a IA consultar enquanto conversa ou programa com você. No sistema em produção, use a API REST.

Segurança

  • Chame a API só do servidor. A chave dá acesso ao seu saldo. Se o app é só front-end (React, Vue, Flutter, Lovable…), crie uma rota de API ou edge function que chama o Placa & FIPE, como em nextjs-route.ts e supabase-edge-function.ts.
  • Guarde a chave em PLACAEFIPE_API_KEY (variável de ambiente ou secret). Nunca faça commit da chave e nunca use prefixos como NEXT_PUBLIC_ ou VITE_.
  • Crie uma chave por projeto e defina um teto mensal de gasto no painel. Se uma chave vazar, o prejuízo fica limitado e você a revoga na hora.
  • Use chaves pf_test_... em testes automatizados e em CI.
  • A API não devolve dados do proprietário do veículo (nome, CPF, endereço).

Encontrou uma vulnerabilidade? Fale com a gente pelo site em vez de abrir uma issue pública.

Links

Licença

MIT © Placa & FIPE. Os SDKs e exemplos são livres. O uso da API segue os termos de uso.

About

SDKs oficiais (JavaScript e Python) e exemplos da API de Placa e FIPE: consulta de veículo pela placa com Tabela FIPE, Renavam, chassi e motor. MCP para Claude, Cursor e Gemini.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages