Skip to content

API Endpoints

Esta seção documenta todos os endpoints disponíveis na API de Gerenciamento de Carros.

Autenticação

/api/v1/auth/token - POST

Gera um token de acesso JWT.

Parâmetros de Requisição: 

{
  "email": "string",
  "password": "string"
}

Resposta de Sucesso (200): 

{
  "access_token": "string",
  "token_type": "bearer"
}

Erros Comuns: - 401: Email ou senha incorretos

/api/v1/auth/refresh_token - POST

Atualiza o token de acesso JWT.

Cabeçalhos Requeridos: - Authorization: Bearer {token}

Resposta de Sucesso (200): 

{
  "access_token": "string",
  "token_type": "bearer"
}

Usuários

/api/v1/users/ - POST

Cria um novo usuário.

Parâmetros de Requisição: 

{
  "username": "string",
  "email": "string",
  "password": "string"
}

Resposta de Sucesso (201): 

{
  "id": 1,
  "username": "string",
  "email": "string",
  "created_at": "2023-01-01T00:00:00",
  "updated_at": "2023-01-01T00:00:00"
}

/api/v1/users/ - GET

Lista todos os usuários (requer autenticação).

Cabeçalhos Requeridos: - Authorization: Bearer {token}

Parâmetros de Consulta: - offset: Número de registros a pular (padrão: 0) - limit: Limite de registros (padrão: 100, máximo: 100)

Resposta de Sucesso (200): 

{
  "users": [...],
  "offset": 0,
  "limit": 100
}

/api/v1/users/{user_id} - GET

Obtém detalhes de um usuário específico (requer autenticação).

Cabeçalhos Requeridos: - Authorization: Bearer {token}

Resposta de Sucesso (200): 

{
  "id": 1,
  "username": "string",
  "email": "string",
  "created_at": "2023-01-01T00:00:00",
  "updated_at": "2023-01-01T00:00:00"
}

/api/v1/users/{user_id} - PUT

Atualiza um usuário existente (requer autenticação).

Cabeçalhos Requeridos: - Authorization: Bearer {token}

Parâmetros de Requisição: 

{
  "username": "string",
  "email": "string",
  "password": "string"
}

Resposta de Sucesso (200): 

{
  "id": 1,
  "username": "string",
  "email": "string",
  "created_at": "2023-01-01T00:00:00",
  "updated_at": "2023-01-01T00:00:00"
}

/api/v1/users/{user_id} - DELETE

Exclui um usuário (requer autenticação).

Cabeçalhos Requeridos: - Authorization: Bearer {token}

Resposta de Sucesso (204): - Sem conteúdo

Marcas

/api/v1/brands/ - POST

Cria uma nova marca.

Cabeçalhos Requeridos: - Authorization: Bearer {token}

Parâmetros de Requisição: 

{
  "name": "string",
  "description": "string"
}

Resposta de Sucesso (201): 

{
  "id": 1,
  "name": "string",
  "is_active": true,
  "description": "string",
  "created_at": "2023-01-01T00:00:00",
  "updated_at": "2023-01-01T00:00:00"
}

/api/v1/brands/ - GET

Lista todas as marcas (requer autenticação).

Cabeçalhos Requeridos: - Authorization: Bearer {token}

Parâmetros de Consulta: - offset: Número de registros a pular (padrão: 0) - limit: Limite de registros (padrão: 100, máximo: 100) - search: Pesquisa por nome de marca - is_active: Filtra por status ativo

Resposta de Sucesso (200): 

{
  "brands": [...],
  "offset": 0,
  "limit": 100
}

/api/v1/brands/{brand_id} - GET

Obtém detalhes de uma marca específica (requer autenticação).

Cabeçalhos Requeridos: - Authorization: Bearer {token}

Resposta de Sucesso (200): 

{
  "id": 1,
  "name": "string",
  "is_active": true,
  "description": "string",
  "created_at": "2023-01-01T00:00:00",
  "updated_at": "2023-01-01T00:00:00"
}

/api/v1/brands/{brand_id} - PUT

Atualiza uma marca existente (requer autenticação).

Cabeçalhos Requeridos: - Authorization: Bearer {token}

Parâmetros de Requisição: 

{
  "name": "string",
  "description": "string",
  "is_active": true
}

Resposta de Sucesso (200): 

{
  "id": 1,
  "name": "string",
  "is_active": true,
  "description": "string",
  "created_at": "2023-01-01T00:00:00",
  "updated_at": "2023-01-01T00:00:00"
}

/api/v1/brands/{brand_id} - DELETE

Exclui uma marca (requer autenticação).

Cabeçalhos Requeridos: - Authorization: Bearer {token}

Resposta de Sucesso (204): - Sem conteúdo

Carros

/api/v1/cars/ - POST

Cria um novo carro.

Cabeçalhos Requeridos: - Authorization: Bearer {token}

Parâmetros de Requisição: 

{
  "model": "string",
  "factory_year": 2023,
  "model_year": 2023,
  "color": "string",
  "plate": "string",
  "fuel_type": "gasoline|ethanol|flex|diesel|electric|hybrid",
  "transmission": "manual|automatic|semi_automatic|cvt",
  "price": 50000.00,
  "description": "string",
  "is_available": true,
  "brand_id": 1,
  "owner_id": 1
}

Resposta de Sucesso (201): 

{
  "id": 1,
  "model": "string",
  "factory_year": 2023,
  "model_year": 2023,
  "color": "string",
  "plate": "string",
  "fuel_type": "gasoline",
  "transmission": "manual",
  "price": 50000.00,
  "description": "string",
  "is_available": true,
  "brand_id": 1,
  "owner_id": 1,
  "created_at": "2023-01-01T00:00:00",
  "updated_at": "2023-01-01T00:00:00",
  "brand": {...},
  "owner": {...}
}

/api/v1/cars/ - GET

Lista todos os carros do usuário autenticado (requer autenticação).

Cabeçalhos Requeridos: - Authorization: Bearer {token}

Parâmetros de Consulta: - offset: Número de registros a pular (padrão: 0) - limit: Limite de registros (padrão: 100, máximo: 100) - search: Pesquisa por modelo, cor ou placa - brand_id: Filtra por marca - owner_id: Filtra por proprietário - fuel_type: Filtra por tipo de combustível - transmission: Filtra por tipo de transmissão - is_available: Filtra por disponibilidade - min_price: Preço mínimo - max_price: Preço máximo

Resposta de Sucesso (200): 

{
  "cars": [...],
  "offset": 0,
  "limit": 100
}

/api/v1/cars/{car_id} - GET

Obtém detalhes de um carro específico (requer autenticação e propriedade).

Cabeçalhos Requeridos: - Authorization: Bearer {token}

Resposta de Sucesso (200): 

{
  "id": 1,
  "model": "string",
  "factory_year": 2023,
  "model_year": 2023,
  "color": "string",
  "plate": "string",
  "fuel_type": "gasoline",
  "transmission": "manual",
  "price": 50000.00,
  "description": "string",
  "is_available": true,
  "brand_id": 1,
  "owner_id": 1,
  "created_at": "2023-01-01T00:00:00",
  "updated_at": "2023-01-01T00:00:00",
  "brand": {...},
  "owner": {...}
}

/api/v1/cars/{car_id} - PUT

Atualiza um carro existente (requer autenticação e propriedade).

Cabeçalhos Requeridos: - Authorization: Bearer {token}

Parâmetros de Requisição: 

{
  "model": "string",
  "factory_year": 2023,
  "model_year": 2023,
  "color": "string",
  "plate": "string",
  "fuel_type": "gasoline|ethanol|flex|diesel|electric|hybrid",
  "transmission": "manual|automatic|semi_automatic|cvt",
  "price": 50000.00,
  "description": "string",
  "is_available": true,
  "brand_id": 1,
  "owner_id": 1
}

Resposta de Sucesso (200): 

{
  "id": 1,
  "model": "string",
  "factory_year": 2023,
  "model_year": 2023,
  "color": "string",
  "plate": "string",
  "fuel_type": "gasoline",
  "transmission": "manual",
  "price": 50000.00,
  "description": "string",
  "is_available": true,
  "brand_id": 1,
  "owner_id": 1,
  "created_at": "2023-01-01T00:00:00",
  "updated_at": "2023-01-01T00:00:00",
  "brand": {...},
  "owner": {...}
}

/api/v1/cars/{car_id} - DELETE

Exclui um carro (requer autenticação e propriedade).

Cabeçalhos Requeridos: - Authorization: Bearer {token}

Resposta de Sucesso (204): - Sem conteúdo

Health Check

/health_check - GET

Verifica a saúde da aplicação.

Resposta de Sucesso (200): 

{
  "status": "ok"
}

Autenticação e Autorização

A maioria dos endpoints requer autenticação JWT. Para acessar endpoints protegidos:

  1. Faça login em /api/v1/auth/token para obter um token
  2. Inclua o token no cabeçalho Authorization: Bearer {token}

Alguns endpoints também exigem autorização específica (por exemplo, somente o proprietário pode modificar ou excluir seu carro).

Filtragem e Paginação

Vários endpoints suportam paginação e filtragem:

  • Paginação: Use os parâmetros offset e limit
  • Busca textual: Use o parâmetro search
  • Filtros específicos: Vários parâmetros de consulta estão disponíveis dependendo do endpoint