FipePlaca
Início/

Referência da API

API da Tabela FIPE por placa

Três consultas pela placa — dados do veículo, candidatos da Tabela FIPE com preço e série histórica — direto do seu sistema. Pré-pago, R$ 0,08 por consulta.

Crie sua chave, recarregue o saldo e comece a consultar por código.

Criar contaEntrar

O que é

A API do FipePlaca abre, para integração, a mesma base que atende o site e o aplicativo. São três consultas que formam um funil: os dados do veículo a partir da placa, os candidatos da Tabela FIPE com preço e confiança, e a série histórica de preço do modelo que você escolher entre eles.

Cada passo é uma consulta distinta, e não uma fatia da mesma resposta — porque o cruzamento entre a placa e a Tabela FIPE é ambíguo com frequência. Em vez de escolher um modelo em silêncio e cobrar como se fosse certeza, a segunda rota entrega os candidatos e o quanto cada um casa. Quem integra decide com o que o dado sustenta.

Preço por rota

Pré-pago, sem mensalidade e sem franquia mínima de uso: você recarrega o saldo e ele só sai quando uma consulta entrega resultado. Placa que não existe, parâmetro malformado e falha nossa não são cobrados.

RotaEntregaSKUPreço
GET /placa/{placa}Os dados do veículo.consulta-veiculoR$ 0,08
GET /placa/{placa}/fipeOs candidatos da Tabela FIPE, com preço e confiança de cada um.consulta-fipeR$ 0,08
GET /fipe/{codigoFipe}/historicoA série de preço do modelo escolhido, até 48 meses.consulta-historicoR$ 0,08
GET /saldoO saldo da conta. Não cobra nada.—grátis

O SKU é o que aparece no extrato de consultas do painel, linha a linha — é por ele que você reconcilia o gasto por rota. As três valem o mesmo hoje de propósito; a tabela existe porque elas podem divergir, e aí você já tem onde olhar.

Como começar

  1. 1. Crie sua conta

    Ao cadastrar, sua primeira chave de API aparece na tela em texto puro, uma única vez. Copie e guarde: o FipePlaca guarda só um hash da chave, e não há como recuperar o texto depois.

  2. 2. Confirme seu e-mail

    Libera a recarga de saldo da conta.

  3. 3. Recarregue o saldo

    A partir de R$ 30,00. O crédito é pré-pago e só sai da conta quando uma consulta entrega resultado.

  4. 4. Comece a consultar

    Use a chave no cabeçalho Authorization: Bearer. Perdeu a chave? Crie outra em Chaves de API, dentro do painel.

Autenticação

Toda chamada leva a chave no cabeçalho Authorization, com o esquema Bearer. Qualquer outro esquema é recusado com CHAVE_INVALIDA. A chave começa com fp_live_ e aparece completa uma única vez, no momento em que é criada.

Authorization: Bearer fp_live_a1b2c3d4e5f6...

O endereço base de todas as rotas é https://services.fipeplaca.com.br/gateway/v1.

O funil de três passos

As três rotas encaixam sem você montar nada à mão. A rota de candidatos devolve, em cada item, os dois valores que a rota de histórico exige: codigoFipe vira o código do caminho, e anoId vira o parâmetro ano. Copie e cole, literalmente.

# 1. dados do veículo — confirme que é o carro certo
curl -H "Authorization: Bearer fp_live_..." \
  https://services.fipeplaca.com.br/gateway/v1/placa/ABC1D23

# 2. os candidatos da Tabela FIPE para essa placa
curl -H "Authorization: Bearer fp_live_..." \
  https://services.fipeplaca.com.br/gateway/v1/placa/ABC1D23/fipe

#    o primeiro candidato traz:
#      "codigoFipe": "001235-1"
#      "anoId":      "2021-1"

# 3. a série histórica DAQUELE candidato
curl -H "Authorization: Bearer fp_live_..." \
  "https://services.fipeplaca.com.br/gateway/v1/fipe/001235-1/historico?ano=2021-1&meses=24"

Cada passo é cobrado por si. Você não precisa dos três: quem só quer conferir o veículo para no passo 1, quem precisa do valor de mercado para no passo 2, e o passo 3 existe para quem precisa da curva — depreciação, laudo, garantia, precificação de seguro.

A rota de histórico não aceita placa, e isso é decisão de desenho: a rota de candidatos existe justamente porque o cruzamento placa → modelo é ambíguo. Aceitar placa no passo 3 traria de volta a ambiguidade que o passo 2 foi feito para expor — e a escolha entre os candidatos é sua, não nossa.

GET/placa/{placa}

Devolve os dados do veículo da placa consultada. Cobra R$ 0,08 por consulta bem-sucedida, no SKU consulta-veiculo. Devolve sempre o mesmo conjunto de chaves — um campo que a base não tem para aquele veículo vem null, nunca some. Quem integrou não precisa testar se a chave existe, só se o valor é nulo.

O chassi sai mascarado, com os quatro últimos caracteres apenas. Renavam e qualquer campo que identifique uma pessoa não saem desta rota. O valor e o código da Tabela FIPE também não saem aqui: o cruzamento entre a placa e o modelo da tabela é ambíguo com frequência, e publicar um código só seria escolher um candidato em silêncio. Preço e código FIPE saem em /placa/{placa}/fipe.

ParâmetroOndeObrigatórioDescrição
placacaminhosimGrafia antiga (ABC1234) ou Mercosul (ABC1D23), maiúsculas, sem hífen nem espaço.

Placa fora desses dois formatos é recusada na porta com 400 PLACA_INVALIDA, sem cobrar nada e sem consultar o fornecedor — é erro de entrada, não falha nossa, e repetir a mesma placa mal formatada nunca vai funcionar.

curl -H "Authorization: Bearer fp_live_..." https://services.fipeplaca.com.br/gateway/v1/placa/ABC1D23
HTTP/1.1 200 OK
X-Saldo-Centavos: 4992

{
  "marca": "FIAT",
  "modelo": "ARGO DRIVE 1.0",
  "anoFabricacao": 2020,
  "anoModelo": 2021,
  "cor": "PRATA",
  "municipio": "CAMPINAS",
  "uf": "SP",
  "cilindradas": 999,
  "potencia": 77,
  "combustivel": "ALCOOL / GASOLINA",
  "chassi": "*************1234"
}

Campos da resposta:

  • marcastring | null

    Marca do veículo.

  • modelostring | null

    Modelo do veículo.

  • anoFabricacaonumber | null

    Ano de fabricação — não é sempre igual ao ano-modelo.

  • anoModelonumber | null

    Ano-modelo — é por ele que a Tabela FIPE precifica o veículo.

  • corstring | null

    Cor predominante.

  • municipiostring | null

    Município de emplacamento.

  • ufstring | null

    UF de emplacamento, com duas letras. Vem null quando a base não devolve uma UF de verdade — nunca um estado provável.

  • cilindradasnumber | null

    Cilindrada do motor, em cm³ (ex.: 999 para um 1.0).

  • potencianumber | null

    Potência do motor, em cv. Vem null quando a base traz um texto que não dá para converter com segurança.

  • combustivelstring | null

    Combustível registrado para o veículo, como a base o escreve (ex.: ALCOOL / GASOLINA).

  • chassistring | null

    Chassi MASCARADO: só os quatro últimos caracteres, o resto em asteriscos.

Erros que esta rota devolve (o que cada um significa está em Erros):

  • PLACA_INVALIDA400
  • CHAVE_INVALIDA401
  • SEM_SALDO402
  • PLACA_NAO_ENCONTRADA404
  • FILA_CHEIA503
  • FORNECEDOR_INDISPONIVEL503
  • ERRO_401401
  • ERRO_403403

X-Saldo-Centavos pode faltar

O cabeçalho X-Saldo-Centavos traz o saldo (em centavos) depois de cobrar esta consulta, e acompanha as três rotas pagas. Ele pode faltar quando a leitura do saldo falha depois de a consulta já ter sido entregue e paga — a ausência é honesta, e o cliente não deve programar assumindo que ele sempre vem.
GET/placa/{placa}/fipe

Devolve os candidatos da Tabela FIPE para aquela placa. Cobra R$ 0,08 por consulta bem-sucedida, no SKU consulta-fipe.

A resposta é um array, ordenado do melhor casamento para o pior, e essa ordem é contrato: [0] é o candidato mais provável, e pode confiar nisso. Uma placa cujo cruzamento é ambíguo sai com vários candidatos; uma cujo vencedor é destacado sai com um só. A ordem é de casamento, não de preço — o primeiro candidato continua em primeiro mesmo quando é ele que está sem preço.

ParâmetroOndeObrigatórioDescrição
placacaminhosimGrafia antiga (ABC1234) ou Mercosul (ABC1D23), maiúsculas, sem hífen nem espaço.
curl -H "Authorization: Bearer fp_live_..." https://services.fipeplaca.com.br/gateway/v1/placa/ABC1D23/fipe
HTTP/1.1 200 OK
X-Saldo-Centavos: 4984

[
  {
    "codigoFipe": "001235-1",
    "modelo": "Doblo Cargo 1.8 mpi Fire Flex 8V/16V 4p",
    "anoModelo": 2021,
    "anoId": "2021-1",
    "combustivel": "Gasolina",
    "valorFipe": "R$ 66.796,00",
    "mesReferencia": "setembro de 2026",
    "confianca": "alta",
    "matchAno": true,
    "matchCombustivel": null
  },
  {
    "codigoFipe": null,
    "modelo": "Doblo Cargo 1.8 mpi Fire Flex 8V/16V 4p (kit)",
    "anoModelo": 2021,
    "anoId": "2021-2",
    "combustivel": null,
    "valorFipe": null,
    "mesReferencia": null,
    "confianca": null,
    "matchAno": null,
    "matchCombustivel": null
  }
]

Campos de cada item do array:

  • codigoFipestring | null

    O código da Tabela FIPE daquela versão. É a entrada da rota de série histórica. Vem null no candidato sem preço: o código chega junto do preço, e inventá-lo seria afirmar o que ninguém mediu.

  • modelostring | null

    O nome do modelo como a FIPE o escreve — não como a base de veículos escreve.

  • anoModelonumber | null

    O ano-modelo sob o qual a FIPE publicou este preço, extraído do anoId. Não é o ano da placa.

  • anoIdstring | null

    O identificador de ano da FIPE (ex.: 2021-1: ano-modelo e código de combustível). É o parâmetro ano da rota de série histórica, e sai pronto daqui para o cliente não ter de montar a string na mão.

  • combustivelstring | null

    O combustível como a FIPE o rotula. Ela chama de "Gasolina" muito carro flex — leia junto com matchCombustivel.

  • valorFipestring | null

    O preço como a FIPE o publica (ex.: R$ 66.796,00). Vem null quando a FIPE não tem preço para esta versão — e o candidato continua no array de propósito.

  • mesReferenciastring | null

    O mês da tabela a que o preço se refere (ex.: setembro de 2026).

  • confianca'alta' | 'media' | 'baixa' | null

    Quanto este candidato casa com o veículo da placa. Lista fechada: um nível fora dela sai null, nunca um valor que a doc não descreve.

  • matchAnoboolean | null

    Se o ano-modelo do candidato bate com o do veículo. null quando não dá para afirmar.

  • matchCombustivelboolean | null

    Se o combustível bate. null quando não dá para afirmar — e isso NÃO significa false. Ver o aviso abaixo.

valorFipe: null não é erro — é um candidato de propósito

valorFipe: null significa este modelo casou com a placa, mas a FIPE não publica preço para ele. O candidato não é omitido, e não deve ser tratado como falha: é justamente ele que explica por que o preço do vizinho não é certeza. Esconder esse item esconderia metade da ambiguidade que esta rota existe para mostrar.

Só quando nenhum candidato se sustenta a rota devolve 404 FIPE_NAO_ENCONTRADA — e aí nada é cobrado.

matchCombustivel: null não quer dizer false

A FIPE rotula muito carro flex como “Gasolina” — um modelo com “Flex” no próprio nome pode vir com fuel: "Gasolina". Divergir do rótulo, portanto, não é erro de cruzamento, e nós não forçamos um false que ninguém pode afirmar: sai null, que quer dizer “não dá para afirmar”. Quem programa if (!matchCombustivel) descartar() descarta exatamente o candidato certo.

Erros que esta rota devolve (o que cada um significa está em Erros):

  • PLACA_INVALIDA400
  • CHAVE_INVALIDA401
  • SEM_SALDO402
  • PLACA_NAO_ENCONTRADA404
  • FIPE_NAO_ENCONTRADA404
  • FILA_CHEIA503
  • FORNECEDOR_INDISPONIVEL503
  • ERRO_401401
  • ERRO_403403
GET/fipe/{codigoFipe}/historico

Devolve a série de preço daquele código FIPE naquele ano-modelo, do mês mais recente para o mais antigo. Cobra R$ 0,08 por consulta bem-sucedida, no SKU consulta-historico — uma cobrança pela série inteira, não por mês.

Os dois parâmetros saem prontos da rota de candidatos: codigoFipe e anoId.

ParâmetroOndeObrigatórioDescrição
codigoFipecaminhosimO código FIPE, no formato 001235-1. Sai do campo codigoFipe da rota de candidatos.
anoquerysimO identificador de ano, no formato 2021-1. Sai do campo anoId da rota de candidatos. É obrigatório: um código FIPE vale para vários anos-modelo, e escolher um por conta própria venderia a série de um veículo que você não pediu.
mesesquerynãoQuantos meses buscar. Padrão 12, teto 48. Pedir mais que o teto é TRUNCADO, não recusado. Já 0, -3, 1.5 e abc são 400 PARAMETRO_INVALIDO — pedido grande demais é claro, pedido sem sentido não é.
curl -H "Authorization: Bearer fp_live_..." \
  "https://services.fipeplaca.com.br/gateway/v1/fipe/001235-1/historico?ano=2021-1&meses=48"
HTTP/1.1 200 OK
X-Saldo-Centavos: 4976

{
  "codigoFipe": "001235-1",
  "anoId": "2021-1",
  "modelo": "Doblo Cargo 1.8 mpi Fire Flex 8V/16V 4p",
  "anoModelo": 2021,
  "combustivel": "Gasolina",
  "tipoVeiculo": 1,
  "mesesSolicitados": 48,
  "serie": [
    { "referencia": 337, "mesReferencia": "setembro de 2026", "valorFipe": "R$ 16.889,00" },
    { "referencia": 336, "mesReferencia": "agosto de 2026",   "valorFipe": "R$ 16.902,00" },
    { "referencia": 334, "mesReferencia": "junho de 2026",    "valorFipe": "R$ 16.955,00" }
  ]
}

Repare no exemplo: a referência 335 não está lá. Esse é o contrato funcionando — ver o aviso sobre buracos, abaixo.

Campos da resposta:

  • codigoFipestring

    O código FIPE consultado, como veio no caminho.

  • anoIdstring

    O identificador de ano consultado, como veio na query.

  • modelostring | null

    O nome do modelo, lido do ponto mais recente que respondeu.

  • anoModelonumber | null

    O ano-modelo, do mesmo ponto.

  • combustivelstring | null

    O combustível, do mesmo ponto.

  • tipoVeiculonumber | null

    O que o fornecedor afirma: 1 carro, 2 moto, 3 caminhão.

  • mesesSolicitadosnumber

    Quantos meses foram PEDIDOS ao fornecedor, já truncados pelo teto de 48. Não é o tamanho da série.

  • seriePontoHistorico[]

    Os pontos de preço, do mais recente para o mais antigo — e essa ordem é contrato. Mês que a FIPE não tem sai AUSENTE, então serie.length pode ser menor que mesesSolicitados.

Campos de cada ponto de serie:

  • referencianumber

    O código da referência FIPE daquele mês (337 é setembro de 2026). A FIPE pula códigos de vez em quando — não faça aritmética com ele.

  • mesReferenciastring | null

    Como o fornecedor nomeia o mês no corpo do preço (ex.: setembro de 2026).

  • valorFipestring

    O preço daquele mês, como a FIPE o publica.

A primeira consulta de um modelo pode demorar

A FIPE não publica série: cada mês é uma leitura separada ao fornecedor. Pedir 48 meses significa até 48 leituras, disparadas em rodadas paralelas com limite. Dimensione o timeout do seu cliente para isso — a primeira consulta de um modelo é a lenta.

Dentro do mês corrente, a repetição do mesmo par código+ano é servida do nosso cache e volta rápido. Entre meses, não: quando a tabela FIPE vira, a série é buscada de novo do zero. Não prometemos um acervo que fica permanentemente quente — prometemos que, dentro do mês, a segunda chamada é barata.

Mês sem preço sai AUSENTE — nunca interpolado

Modelo que saiu de linha some das referências mais antigas, e a FIPE devolve erro naquele mês. Esse mês simplesmente não aparece na série: nada é interpolado, nada é repetido do mês vizinho. Você precisa conseguir distinguir “não havia preço” de “não conseguimos ler”, e um número inventado no meio de uma curva de depreciação é pior que um buraco. Por isso serie.length pode ser menor que mesesSolicitados — e por isso cada ponto carrega a sua referencia.

Série vazia é 404 e não cobra; um ponto que seja cobra

Se nenhum mês responder, a rota devolve 404 FIPE_NAO_ENCONTRADA e nada é cobrado — zero pontos é zero entrega. Série parcial, com um ponto que seja, é entrega legítima e cobra normalmente: o tamanho do array é o que você lê para saber o que recebeu.

Erros que esta rota devolve (o que cada um significa está em Erros):

  • PARAMETRO_INVALIDO400
  • CHAVE_INVALIDA401
  • SEM_SALDO402
  • FIPE_NAO_ENCONTRADA404
  • FILA_CHEIA503
  • FORNECEDOR_INDISPONIVEL503
  • ERRO_401401
  • ERRO_403403
GET/saldo

Não cobra nada e não tem parâmetros. Devolve o saldo atual da conta — para você conferir quanto resta sem gastar uma consulta.

curl -H "Authorization: Bearer fp_live_..." https://services.fipeplaca.com.br/gateway/v1/saldo
HTTP/1.1 200 OK

{
  "saldoCents": 5000,
  "saldo": "50.00"
}

Erros que esta rota devolve (o que cada um significa está em Erros):

  • CHAVE_INVALIDA401
  • ERRO_401401
  • ERRO_403403

Erros

Todo erro do gateway devolve { erro: { codigo, mensagem } }. Programe contra codigo — a lista abaixo é fechada e a mensagem pode mudar de texto sem aviso. Qual rota devolve qual código está no bloco de cada rota.

Uma resposta pode não ter corpo nenhum

Se o cliente que chamou a API desistir da conexão antes da resposta, o gateway responde 499 sem corpo — nenhum JSON, nenhum { erro: ... } . Quem faz response.json() sem checar isso primeiro recebe uma exceção de parse, não um erro do contrato.
CódigoStatusQuando aconteceO que fazer
PLACA_NAO_ENCONTRADA404A placa não existe na base de dados de veículos.Não repita a mesma placa — confirme o dado com o cliente.
FIPE_NAO_ENCONTRADA404Na consulta de FIPE por placa: a placa existe e os dados do veículo vieram, mas nenhum modelo da Tabela FIPE corresponde a ele. Na série histórica: o código FIPE e o ano informados não produziram nenhum ponto de preço — série vazia é zero entrega, não resultado.Não repita a mesma consulta: nem a Tabela FIPE cobre todo veículo, nem um código FIPE inexistente passa a existir tentando de novo. Nada é cobrado neste erro. Na consulta de placa, os dados do veículo continuam disponíveis em /placa/:placa.
CHAVE_INVALIDA401A chave está ausente, incorreta, revogada, sem conta associada — ou o cabeçalho Authorization veio malformado ou com outro esquema que não Bearer.Confira o cabeçalho Authorization: Bearer e se a chave não foi revogada em Chaves de API.
SEM_SALDO402Não há saldo suficiente para cobrir esta consulta.Recarregue o saldo no painel antes de tentar de novo.
FILA_CHEIA503O teto de chamadas simultâneas do nosso processo está ocupado. NÃO é uma cota da sua chave: o contador é do processo inteiro e não olha de qual chave a chamada veio.Espere e tente de novo — nada é cobrado neste erro.
PLACA_INVALIDA400A placa enviada não está no formato aceito: antiga (ABC1234) ou Mercosul (ABC1D23), sem hífen nem espaço. A consulta é recusada na porta, antes de qualquer cobrança.Não repita a chamada: corrija o formato antes. Nada é cobrado neste erro, e repetir a mesma placa mal formatada nunca vai funcionar.
PARAMETRO_INVALIDO400Um parâmetro de caminho ou de query está ausente ou fora de forma — o ano (ano) da série histórica, que é obrigatório, o código FIPE do caminho, ou meses, que precisa ser um inteiro positivo. A consulta é recusada na porta, antes de qualquer cobrança.Não repita a chamada: corrija o parâmetro antes. Nada é cobrado neste erro. Pedir mais de 48 meses NÃO cai aqui — o pedido é truncado em 48 e atendido.
FORNECEDOR_INDISPONIVEL503Falha temporária no fornecedor de dados por trás da consulta. Na série histórica, também é o código de uma falha de credencial NOSSA junto à FIPE — sem ela as referências passadas são recusadas, e uma série de um mês só ficaria indistinguível de um veículo que de fato tem um mês de histórico.Tente de novo com espera — este erro é de fato temporário, e nada é cobrado nele. Placa em formato inválido não cai mais aqui: ela tem código próprio (PLACA_INVALIDA).
ERRO_401401O IP de origem da chamada está bloqueado (hook global, não é sobre a chave).Não é a chave — confirme de onde a chamada está saindo antes de repetir.
ERRO_403403Mesmo bloqueio de IP do ERRO_401, para o caso em que o status vem 403.Não é a chave — confirme de onde a chamada está saindo antes de repetir.

Promessas do contrato

  • Conjunto de chaves estável — cada rota sempre devolve as mesmas chaves. Um dado que a base ou a FIPE não têm para aquele veículo vem null, nunca some. E null quer dizer “não sabemos”: nunca publicamos um valor plausível no lugar de um que não podemos garantir.
  • Ordem é contrato onde dissemos que é — os candidatos de /placa/{placa}/fipe vêm do melhor casamento para o pior, e a serie do histórico vem do mês mais recente para o mais antigo. Reordenar qualquer uma das duas seria quebra de contrato, não detalhe de apresentação.
  • Você só paga entrega — placa inexistente, parâmetro malformado, fila cheia, falha nossa e série vazia não são cobradas. Uma consulta que devolve resultado é cobrada uma vez, mesmo quando custou dezenas de leituras ao fornecedor.
  • Sem franquia, sem cota, sem limite por segundo — não existe rate limit por IP nem por chave, e nenhuma cota é reservada ou descontada por chave: o saldo é o teto, e você consulta na velocidade que ele permitir. O que existe é um teto de chamadas simultâneas do nosso processo, para ele não cair levando o site junto — não é trava comercial. Ele é folgado de propósito e uma integração legítima não chega nele; uma rajada que chegue recebe FILA_CHEIA, que não é cobrada e passa assim que as chamadas em andamento terminam. Cada conta pode ter até 3 chaves ativas.
  • Erros programáveis — os códigos de erro são uma lista fechada e não mudam sem aviso; a mensagem em texto pode mudar, o código não.

Já tem conta?

Crie sua chave, acompanhe o saldo e o histórico de consultas no painel — em um clique.

Entrar no painelCriar conta