Documentação da API

Autenticação

Toda requisição exige uma chave de API no header Authorization. Peça a sua em /desenvolvedores/solicitar — nossa equipe analisa o pedido e libera o acesso.

Authorization: Bearer cpk_SUA_CHAVE

A chave completa (formato cpk_ + 48 caracteres) é exibida uma única vez, na criação. Guarde-a em local seguro — no painel fica visível só o prefixo. Se perdê-la, revogue e gere outra.

Exemplo mínimo:

curl -H "Authorization: Bearer cpk_SUA_CHAVE" \
  "https://catalogo-veicular-two.vercel.app/api/v1/marcas"

Marcas

GET /api/v1/marcas

Lista as marcas do catálogo, com contagem de modelos. Paginada.

curl -H "Authorization: Bearer cpk_SUA_CHAVE" \
  "https://catalogo-veicular-two.vercel.app/api/v1/marcas?tipo=Automóveis&pagina=1"

{
  "ref": "06-2026",
  "marcas": [
    { "slug": "jeep", "nome": "Jeep", "tipos": ["Automóveis"], "modelos": 7 }
  ],
  "paginacao": { "pagina": 1, "porPagina": 100, "total": 211, "totalPaginas": 3 }
}

Modelos da marca

GET /api/v1/marcas/{marca}/modelos

Modelos de uma marca, com contagem de versões. Paginada. Use o slug devolvido em /marcas.

curl -H "Authorization: Bearer cpk_SUA_CHAVE" \
  "https://catalogo-veicular-two.vercel.app/api/v1/marcas/jeep/modelos"

{
  "ref": "06-2026",
  "marca": { "slug": "jeep", "nome": "Jeep" },
  "modelos": [
    { "slug": "compass", "nome": "Compass", "tipos": ["Automóveis"], "versoes": 25 }
  ],
  "paginacao": { "pagina": 1, "porPagina": 100, "total": 7, "totalPaginas": 1 }
}

Versões do modelo

GET /api/v1/modelos/{marca}/{modelo}/versoes

Todas as versões do modelo, com anos-modelo disponíveis, combustíveis e preço de referência (ano mais novo). Sem paginação — o conjunto é limitado por modelo. manual: true marca lançamentos ainda sem código FIPE (id sintético negativo; o precoRef deles vem com estimado: true).

curl -H "Authorization: Bearer cpk_SUA_CHAVE" \
  "https://catalogo-veicular-two.vercel.app/api/v1/modelos/jeep/compass/versoes"

{
  "ref": "06-2026",
  "marca": { "slug": "jeep", "nome": "Jeep" },
  "modelo": { "slug": "compass", "nome": "Compass" },
  "versoes": [
    {
      "id": 170968,
      "nome": "COMPASS Black Hurricane 2.0 4x4 TB Aut.",
      "versao": "Black Hurricane 2.0 4x4 TB Aut.",
      "slug": "black-hurricane-2-0-4x4-tb-aut",
      "tipo": "Automóveis",
      "anos": ["0 Km", "2026", "2025"],
      "combustiveis": ["Gasolina"],
      "manual": false,
      "precoRef": { "valor": 273271, "ano": "0 Km", "estimado": false }
    }
  ]
}

Preço FIPE

GET /api/v1/preco/{fipeId}

Preços FIPE vigentes da versão (ref. 06-2026), um por ano-modelo — a linha "0 Km" é o veículo novo. Com ?ano=, devolve só o ano pedido e agrega variacao: preço atual, variação mensal (mom) e de 12 meses (m12), em percentual. Versão manual (id negativo): precos: [] e variacao: null.

curl -H "Authorization: Bearer cpk_SUA_CHAVE" \
  "https://catalogo-veicular-two.vercel.app/api/v1/preco/170968?ano=2025"

{
  "ref": "06-2026",
  "versao": {
    "id": 170968,
    "nome": "COMPASS Black Hurricane 2.0 4x4 TB Aut.",
    "marca": "Jeep",
    "modelo": "Compass"
  },
  "precos": [
    { "ano": "2025", "combustivel": "Gasolina", "valor": 200126 }
  ],
  "variacao": { "atual": 200126, "refAtual": "06-2026", "mom": -0.87, "m12": -6.1 }
}

Histórico de preço

GET /api/v1/historico/{fipeId}/{ano}

Série histórica mensal do preço FIPE da versão×ano-modelo, variação e — quando há base estatística suficiente — projeção de depreciação. A projeção vem sempre rotulada com "estimativa": true: é modelo calculado sobre o histórico do próprio modelo, não dado FIPE.

curl -H "Authorization: Bearer cpk_SUA_CHAVE" \
  "https://catalogo-veicular-two.vercel.app/api/v1/historico/170968/2025"

{
  "ref": "06-2026",
  "versao": {
    "id": 170968,
    "nome": "COMPASS Black Hurricane 2.0 4x4 TB Aut.",
    "marca": "Jeep",
    "modelo": "Compass"
  },
  "ano": "2025",
  "serie": [
    { "ref": "2024-02", "valor": 259865 },
    { "ref": "2026-06", "valor": 200126 }
  ],
  "variacao": { "atual": 200126, "refAtual": "06-2026", "mom": -0.87, "m12": -6.1 },
  "projecao": {
    "estimativa": true,
    "valorBase": 200126,
    "refBase": "2026-06",
    "pontos": [
      { "ano": 2027, "valor": 186000 },
      { "ano": 2028, "valor": 174000 }
    ],
    "base": "depreciação média observada em 4 anos-modelo do próprio modelo (18 observações)"
  }
}

projecao é omitida quando não há base honesta (modelo novo, série curta). Os pontos são anos-calendário.

Ficha técnica

GET /api/v1/ficha/{fipeId}/{ano}

Ficha técnica da versão×ano em seções (motor, dimensões, equipamentos…), com a fonte do dado quando registrada e o consumo oficial PBEV/Inmetro quando há match auditado. ?resumida=1 devolve o mesmo recorte do bloco principal da página de versão do site.

curl -H "Authorization: Bearer cpk_SUA_CHAVE" \
  "https://catalogo-veicular-two.vercel.app/api/v1/ficha/170968/2025"

{
  "ref": "06-2026",
  "versao": {
    "id": 170968,
    "nome": "COMPASS Black Hurricane 2.0 4x4 TB Aut.",
    "marca": "Jeep",
    "modelo": "Compass"
  },
  "ano": "2025",
  "fonte": { "fonte": "montadora", "em": "2025-03-10" },
  "secoes": [
    {
      "titulo": "Motor",
      "itens": [
        { "label": "Potência", "valor": "272 cv" },
        { "label": "Torque", "valor": "40,8 kgfm" }
      ]
    }
  ],
  "consumo": {
    "kml_cidade": 9.1,
    "kml_estrada": 10.9,
    "autonomia_km": 520,
    "selo": "A",
    "fonte": "PBEV/Inmetro"
  },
  "anosDisponiveis": [2026, 2025]
}

fonte e consumo são omitidos quando não há registro. anosDisponiveis lista os anos com ficha para a mesma versão.

Erros

Toda resposta de erro tem o mesmo corpo, com um código estável para tratar por programa (a mensagem pode mudar; o código não):

{
  "erro": {
    "codigo": "quota_mensal",
    "mensagem": "Quota mensal do plano excedida. Renova em 2026-08-01.",
    "status": 429
  }
}

Limites e planos

Cada plano tem uma quota mensal (teto duro) e um limite por minuto (proteção de rajada). Toda resposta de sucesso traz o estado da quota mensal nos headers:

X-RateLimit-Limit: 100         # limite mensal do plano
X-RateLimit-Remaining: 87      # restante no mês (pode atrasar até 60 s)
X-RateLimit-Reset: 1754006400  # epoch UTC do dia 1º do mês seguinte

Ao estourar o limite por minuto, a resposta 429 (limite_minuto) inclui Retry-After: 60.

Para subir de plano, solicite o acesso — o plano Empresa é montado sob consulta, de acordo com a necessidade de cada cliente.