---
title: "Busca veículos"
method: GET
path: "/v1/search"
tags: ["Busca"]
---

# Busca veículos

`GET /v1/search`

## Request

- Base URL: `https://api.fipex.com.br`
- URL: `https://api.fipex.com.br/v1/search`
- Auth: none declared

Busca de texto completo por veículos com filtros e ordenação avançados.

**Filtros Disponíveis:**
- `model`: UUID do modelo (`=`, `!=`, `IN`, `NOT IN`)
- `make`: UUID da marca (`=`, `!=`, `IN`, `NOT IN`)
- `fuel`: UUID do combustível (`=`, `!=`, `IN`, `NOT IN`)
- `type`: UUID do tipo de veículo (`=`, `!=`, `IN`, `NOT IN`)
- `body_type`: Slug da carroceria (`=`, `!=`, `IN`, `NOT IN`)
- `fipe_code`: Código FIPE com hífen, ex. `811049-7` (`=` apenas, exatamente 8 chars)
- `year`: Ano (`=`, `!=`, `>`, `<`, `>=`, `<=`, `IN`, `TO`; suporta "zero")
- `price`: Preço em moeda corrente (`>`, `<`, `>=`, `<=`, `TO`; convertido para centavos)

**Nota sobre CONTAINS:** `CONTAINS`/`NOT CONTAINS` não são suportados em nenhum campo de `/v1/search` (incluindo `body_type`) e resultam em erro 400.

Inclui facets disjuntivos para `make`, `model`, `fuel`, `type`, `body_type`, `year` (distribuição) e `price` (estatísticas min/max).

Zero resultados retorna 200, não 404.

## Query parameters

- `page` integer
- `limit` integer
- `order_by` union
  - string
  - string[]
- `q` string
- `filters` FilterExpression[]
  - `field` string, required: Nome do campo para filtrar.
  - `op` '=' | '!=' | '>' | '<' | '>=' | '<=' | 'CONTAINS' | 'NOT CONTAINS' | 'IN' | 'NOT IN' | 'TO' | 'IS NULL', required: Operador do filtro.
  - `value` string: Valor do filtro (o tipo depende do campo e do operador). Para IN/NOT IN/TO use vírgula como separador.
  - `negate` boolean: Se deve negar a condição do filtro.
  - `condition` 'AND' | 'OR': Condição lógica para combinar com outros filtros.

## Response `200`

Resultados da busca obtidos com sucesso (pode ser array vazio).

- SearchResponse
  - `data` SearchHit[], required
    - `price_id` string, uuid
    - `model_id` string, uuid
    - `model_name` string
    - `model_slug` string
    - `make_id` string, uuid
    - `make_name` string
    - `make_slug` string
    - `fuel_id` string, uuid
    - `fuel_name` string
    - `fuel_acronym` string: Acrônimo do combustível (ex. "g" para gasolina).
    - `model_year` integer: Ano do modelo (oneof com is_zero_km).
    - `is_zero_km` boolean: Indica veículo zero km (oneof com model_year).
    - `latest_market_price_cents` integer: Preço de mercado mais recente em centavos.
    - `type_id` string, uuid
    - `type_name` string
    - `latest_ref_id` string, uuid
    - `ref_month` integer
    - `ref_year` integer
    - `ref_fipe_id` integer
    - `ref_ingested_at` string, date-time
    - `matches` object: Correspondências da busca com trechos destacados.
    - `score` number, float: Pontuação de relevância da busca (0-1).
    - `body_type_id` string: ID da carroceria.
    - `body_type_name` string: Nome da carroceria.
    - `body_type_slug` string: Slug da carroceria.
    - `fipe_code` string: Código FIPE público, ex: "811049-7".
    - `matched_previous_name` string: Quando o resultado correspondeu a um nome **anterior** do modelo (não o atual), traz esse nome antigo para a UI exibir um selo de "antigo nome". Vazio quando a correspondência foi no nome atual.
  - `time_taken_ms` integer, required: Tempo de execução da busca em milissegundos.
  - `facets` Facets, required: Dados de faceting disjuntivo. `distribution` mapeia nome-do-campo → opção-id → contagem. `stats` mapeia nome-do-campo → {min, max}. Campos: make, model, fuel, type, body_type, year (distribution); year, price (stats).
    - `distribution` object
    - `stats` object
  - `pagination` Pagination, required
    - `total` integer, required: Número total de itens.
    - `limit` integer, required: Itens por página.
    - `page` integer, required: Número da página atual.
    - `pages` integer, required: Número total de páginas (mínimo 1, mesmo quando total=0).

## Other responses

- `400`: Erro de validação (400). Usado para TODOS os erros de validação — não há 422.
- `500`: Erro interno do servidor (500).

---

[API](https://skmtc.dev/fipex/apis/api-fipex.md) · [All operations](https://skmtc.dev/fipex/apis/api-fipex/llms.txt) · [OpenAPI document](https://skmtc.dev/fipex/apis/api-fipex/revisions/800eab7da73d?raw)