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://www.carpedia.com.br/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://www.carpedia.com.br/api/v1/marcas?tipo=Automóveis&pagina=1"

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

Modelos da marca

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

Modelos de uma marca, com contagem de versões e a imagem do modelo (foto mais recente do catálogo, ou logo/monograma da marca quando não há foto — ver seção Imagem). Paginada. Use o slug devolvido em /marcas.

curl -H "Authorization: Bearer cpk_SUA_CHAVE" \
  "https://www.carpedia.com.br/api/v1/marcas/jeep/modelos"

{
  "ref": "08-2026",
  "marca": { "slug": "jeep", "nome": "Jeep" },
  "modelos": [
    {
      "slug": "compass", "nome": "Compass", "tipos": ["Automóveis"], "versoes": 25,
      "imagem": {
        "tipo": "foto",
        "url": "https://www.carpedia.com.br/fotos/jeep-compass/2026.webp",
        "ano": "2026",
        "ia": true
      }
    }
  ],
  "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://www.carpedia.com.br/api/v1/modelos/jeep/compass/versoes"

{
  "ref": "08-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 }
    }
  ]
}

Imagem do modelo

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

Resolve a imagem do modelo com fallback previsível — sempre devolve algo renderizável: a foto do carro quando existir; senão o logo da marca; senão um monograma de 2 letras com uma cor estável, pra você montar um chip quando não houver logo. Mesma lógica exposta no campo imagem de /marcas/{marca}/modelos.

curl -H "Authorization: Bearer cpk_SUA_CHAVE" \
  "https://www.carpedia.com.br/api/v1/modelos/jeep/compass/imagem"

Foto encontrada (ano mais recente do catálogo):

{
  "ref": "08-2026",
  "marca": { "slug": "jeep", "nome": "Jeep" },
  "modelo": { "slug": "compass", "nome": "Compass" },
  "imagem": {
    "tipo": "foto",
    "url": "https://www.carpedia.com.br/fotos/jeep-compass/2026.webp",
    "ano": "2026",
    "ia": true,
    "angulo": "3/4 dianteira"
  }
}

Sem foto, marca com logo cadastrado:

{
  "ref": "08-2026",
  "marca": { "slug": "jeep", "nome": "Jeep" },
  "modelo": { "slug": "compass", "nome": "Compass" },
  "imagem": { "tipo": "logo", "url": "https://www.carpedia.com.br/logos/brands/jeep.webp" }
}

Sem foto e sem logo — monograma pra você renderizar um chip:

{
  "imagem": { "tipo": "monograma", "monograma": "GW", "cor": "#2F5E8C" }
}

As URLs de imagem apontam pra assets públicos e estáticos (/fotos/, /logos/) — a autenticação por chave protege só o JSON da API, não o arquivo em si. ia: true marca foto gerada por IA (rotule ao exibir); quando ausente, é foto de divulgação oficial da montadora.

Preço FIPE

GET /api/v1/preco/{fipeId}

Preços FIPE vigentes da versão (ref. 08-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://www.carpedia.com.br/api/v1/preco/170968?ano=2025"

{
  "ref": "08-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": "08-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://www.carpedia.com.br/api/v1/historico/170968/2025"

{
  "ref": "08-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": "08-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://www.carpedia.com.br/api/v1/ficha/170968/2025"

{
  "ref": "08-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.

Consumo do mês

GET /api/v1/consumo

Uso e quota da sua própria chave no mês corrente — mesmo número dos headers X-RateLimit-*, como endpoint dedicado pra consultar gasto sem precisar inspecionar headers de outra chamada. Sem parâmetros.

curl -H "Authorization: Bearer cpk_SUA_CHAVE" \
  "https://www.carpedia.com.br/api/v1/consumo"

{
  "ref": "08-2026",
  "plano": "pro",
  "requisicoes_usadas": 1284,
  "requisicoes_limite": 5000,
  "requisicoes_restantes": 3716,
  "reseta_em": "2026-09-01T00:00:00.000Z"
}

requisicoes_usadas/restantes vêm null só se a medição estiver momentaneamente indisponível (a chamada em si nunca falha por isso).

Relatório de consumo por período

GET /api/v1/relatorio-consumo

Uso agregado por dia e por rota num período livre (não só o mês corrente) — pra reconciliar consumo com o seu próprio controle de gasto.

curl -H "Authorization: Bearer cpk_SUA_CHAVE" \
  "https://www.carpedia.com.br/api/v1/relatorio-consumo?inicio=2026-08-01&fim=2026-08-31"

{
  "periodo": { "inicio": "2026-08-01", "fim": "2026-08-31" },
  "total_requisicoes": 842,
  "por_dia": [
    { "dia": "2026-08-01", "rota": "v1/marcas", "requisicoes": 12 },
    { "dia": "2026-08-01", "rota": "v1/preco", "requisicoes": 40 }
  ]
}

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.