Método HTTP GET
Autenticação: API Key + API Secret
Catálogo
Listar veículos com filtros e paginação
Retorna lista paginada de veículos do catálogo com filtros opcionais, incluindo ano exato via `ano` ou intervalo via `ano_min`/`ano_max`.
Resumo técnico
- Método
- Método HTTP GET
- Rota
- /catalog/vehicles
- URL completa
- https://uzjxyrtbszreqxjvpzpv.supabase.co/functions/v1/public-catalog-phase1/catalog/vehicles
Quando usar
Use para grids/listagens com paginação e filtros de catálogo.
Headers obrigatórios
| Header | Obrigatório | Descrição | Exemplo |
|---|---|---|---|
| X-API-Key | Sim | Chave pública fornecida para consumo da API pública. | SUA_PUBLIC_KEY |
| X-API-Secret | Sim | Segredo pareado à API Key para autenticação. | SEU_SECRET |
Parâmetros de consulta
| Nome | Tipo | Obrigatório | Descrição | Exemplo |
|---|---|---|---|---|
| marca | string | Não | Filtra por marca (ilike). | - |
| modelo | string | Não | Filtra por modelo (ilike). | - |
| categoria | string | Não | Filtra por categoria (ilike). | - |
| combustivel | string | Não | Filtra por combustível (ilike). | - |
| propulsao | string | Não | Filtra por tipo de propulsão (ilike). | - |
| transmissao | string | Não | Filtra por transmissão (ilike). | - |
| ano | number | Não | Ano exato (1900-2100); equivalente a ano_min=<ano>&ano_max=<ano>. | 2023 |
| ano_min | number | Não | Ano mínimo (1900-2100). | 2020 |
| ano_max | number | Não | Ano máximo (1900-2100). | 2026 |
| page | number | Não | Página atual (>= 1). | 1 |
| page_size | number | Não | Itens por página (1-100). | 20 |
Campos principais da resposta
Retorna `success`, envelope `data.data.items` e metadados em `data.meta` com paginação real.
| Nome | Tipo | Obrigatório | Descrição | Exemplo |
|---|---|---|---|---|
| success | string | Não | Flag de sucesso do envelope HTTP. | - |
| data.data.items[] | string | Não | Lista paginada de veículos. | - |
| data.data.items[].id | string | Não | UUID do veículo. | - |
| data.data.items[].motor | string | null | Não | Pode ser null. | - |
| data.data.items[].transmissao_tipo | string | null | Não | Pode ser null. | - |
| data.data.items[].transmissao_marchas | number | null | Não | Pode ser null. | - |
| data.data.items[].ar_condicionado | boolean | null | Não | Pode ser null. | - |
| data.meta.pagination | string | Não | Paginação: page, page_size, total, total_pages. | - |
| data.meta.filters_applied | object | undefined | Não | Filtros aplicados quando informados pelo endpoint. | - |
Cenários de uso
- Listar veículos com filtros e paginação reais do backend (page/page_size + ano exato ou ano_min/ano_max).
- Consumir `data.data.items` e `data.meta.pagination` na UI sem flatten indevido.
- Aplicar filtros opcionais por marca/modelo/categoria/combustível/propulsão/transmissão.
Exemplos de integração
Os exemplos desta documentação utilizam dados fictícios/mockados para fins ilustrativos, mas seguem a estrutura oficial real da API.
Nunca exponha X-API-Secret em aplicações front-end públicas. Para aplicações web públicas, faça a chamada a partir do seu backend.
Exemplo de integração (cURL)
curl -X GET "https://uzjxyrtbszreqxjvpzpv.supabase.co/functions/v1/public-catalog-phase1/catalog/vehicles?marca=Toyota&combustivel=Flex&ano=2023&page=1&page_size=20" \
-H "X-API-Key: SUA_PUBLIC_KEY" \
-H "X-API-Secret: SEU_SECRET"Os exemplos desta documentação utilizam dados fictícios/mockados para fins ilustrativos, mas seguem a estrutura oficial real da API.
Exemplo de resposta
{
"success": true,
"data": {
"data": {
"items": [
{
"id": "001af754-592a-42ce-8227-01c958d4de3c",
"marca": "Toyota",
"modelo": "Corolla",
"versao": "Altis",
"ano": 2025,
"categoria": "Sedan",
"motor": "2.0",
"tipo_propulsao": "Combustão",
"combustivel_tipo": "Flex",
"transmissao_tipo": "Automática",
"transmissao_marchas": 10,
"ar_condicionado": true,
"direcao_assistida_tipo": "Elétrica"
}
]
},
"meta": {
"generated_at": "2026-04-17T22:03:16.372Z",
"request_id": "762f6abe-1846-4c04-a979-e348c3e0c072",
"pagination": {
"page": 1,
"page_size": 20,
"total": 120,
"total_pages": 6
}
}
}
}Erros possíveis (exemplo de payload)
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Parâmetros inválidos: page deve ser maior que 0"
}
}