@altis-tech/fipe

Cliente oficial Node/TypeScript da Altis FIPE API. Consulte a Tabela FIPE (carros, motos e caminhões) com poucas linhas.

Instalação

npm install @altis-tech/fipe
# ou: pnpm add @altis-tech/fipe / yarn add @altis-tech/fipe

Pegue sua chave (grátis)

1. Crie a conta em https://fipe.altis.online/cadastro — você ganha 1.000 créditos de cortesia.
2. Copie a chave fpk_live_... que aparece no fim do cadastro (ou em Painel → API Keys).
3. Exporte como variável de ambiente:

export ALTIS_FIPE_KEY="fpk_live_xxxxxxxxxxxx"

Uso

import { AltisFipe } from "@altis-tech/fipe";

const fipe = new AltisFipe({ apiKey: process.env.ALTIS_FIPE_KEY! });

// 1. Marcas de carros (grátis, 0 créditos)
const brands = await fipe.cars.brands();

// 2. Modelos da marca
const models = await fipe.cars.models(56);

// 3. Anos disponíveis
const years = await fipe.cars.years(56, 9984);

// 4. Preço FIPE (consulta-mãe)
const quote = await fipe.cars.quote({ brandId: 56, modelId: 9984, yearId: "2025-6" });
console.log(`${quote.model}: ${quote.price} (${quote.referenceMonth})`);

Motos e caminhões usam a mesma interface:

await fipe.motorcycles.brands();
await fipe.trucks.quote({ brandId: 1, modelId: 100, yearId: "2024-3" });

Tratamento de erros

import { AltisFipe, AltisFipeError } from "@altis-tech/fipe";

try {
  await fipe.cars.quote({ brandId: 56, modelId: 9984, yearId: "2025-6" });
} catch (err) {
  if (err instanceof AltisFipeError) {
    if (err.isOutOfCredits) console.error("Sem créditos — compre mais no painel.");
    else if (err.isRateLimited) console.error("Muitas requisições, aguarde.");
    else if (err.isAuthError) console.error("Chave inválida.");
    else console.error(err.code, err.message, err.details);
  }
}

Opções

| Opção | Default | Descrição | | --- | --- | --- | | apiKey | — | Obrigatório. Chave fpk_live_... | | baseUrl | https://api.fipe.altis.online | Sobrescreve a base (ex.: staging/local) | | timeoutMs | 15000 | Timeout por requisição | | maxRetries | 2 | Retentativas em 429/5xx (com backoff) | | fetch | global | fetch customizado |

Combustível (yearId)

yearId segue o padrão YYYY-F: 1=Gasolina, 2=Álcool, 3=Diesel, 4=Flex, 5=Elétrico, 6=Híbrido. Ex.: 2025-4 = 2025 Flex.

Créditos por chamada

| Chamada | Créditos | | --- | --- | | references(), brands() | 0 | | models(), years(), yearsByBrand(), modelsByYear() | 1 | | quote() | 2 |

A cobrança só ocorre em respostas 2xx.

Licença

Proprietária — Altis 2026.