Vehicle CRUD Operations

Overview

The Vehicle API provides comprehensive CRUD operations for managing cars and motorcycles in the SGIVU inventory system. All endpoints require JWT authentication and appropriate permissions.

Base URL

https://your-domain.com/v1

Cars

Create Car

POST /v1/cars

Registers a new car in the inventory. Authentication: Required Authorization: vehicle:create permission

Request Body

plate

string

required

License plate number

brand

string

required

Vehicle brand/manufacturer

line

string

required

Vehicle line/model name

model

string

required

Model year

fuelType

string

required

Fuel type (e.g., GASOLINE, DIESEL, ELECTRIC, HYBRID)

bodyType

string

required

Body type (e.g., SEDAN, SUV, HATCHBACK, TRUCK)

transmission

string

required

Transmission type (MANUAL, AUTOMATIC)

mileage

integer

required

Current mileage in kilometers

capacity

integer

required

Passenger capacity

salePrice

number

required

Sale price

purchasePrice

number

Purchase price (optional)

city

string

required

City where vehicle is registered

status

string

default:"AVAILABLE"

Vehicle status (AVAILABLE, UNAVAILABLE, SOLD)

color

string

Vehicle color

engineCapacity

number

Engine displacement in liters

{
  "plate": "ABC123",
  "brand": "Toyota",
  "line": "Corolla",
  "model": "2022",
  "fuelType": "GASOLINE",
  "bodyType": "SEDAN",
  "transmission": "AUTOMATIC",
  "mileage": 25000,
  "capacity": 5,
  "salePrice": 75000000,
  "purchasePrice": 65000000,
  "city": "Bogotá",
  "status": "AVAILABLE",
  "color": "Silver",
  "engineCapacity": 1.8
}

Response

{
  "id": 15,
  "plate": "ABC123",
  "brand": "Toyota",
  "line": "Corolla",
  "model": "2022",
  "fuelType": "GASOLINE",
  "bodyType": "SEDAN",
  "transmission": "AUTOMATIC",
  "mileage": 25000,
  "capacity": 5,
  "salePrice": 75000000,
  "purchasePrice": 65000000,
  "city": "Bogotá",
  "status": "AVAILABLE",
  "color": "Silver",
  "engineCapacity": 1.8,
  "createdAt": "2026-03-06T10:30:00",
  "updatedAt": "2026-03-06T10:30:00"
}

Status Codes

201 Created - Vehicle created successfully
400 Bad Request - Invalid input data
401 Unauthorized - Not authenticated
403 Forbidden - Missing vehicle:create permission

Example

curl -X POST https://your-domain.com/v1/cars \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "plate": "ABC123",
    "brand": "Toyota",
    "line": "Corolla",
    "model": "2022",
    "fuelType": "GASOLINE",
    "bodyType": "SEDAN",
    "transmission": "AUTOMATIC",
    "mileage": 25000,
    "capacity": 5,
    "salePrice": 75000000,
    "city": "Bogotá"
  }'

Get Car by ID

GET /v1/cars/{id}

Retrieves detailed information about a specific car. Authentication: Required Authorization: vehicle:read permission

Path Parameters

integer

required

Car ID

Response

{
  "id": 15,
  "plate": "ABC123",
  "brand": "Toyota",
  "line": "Corolla",
  "model": "2022",
  "fuelType": "GASOLINE",
  "bodyType": "SEDAN",
  "transmission": "AUTOMATIC",
  "mileage": 25000,
  "capacity": 5,
  "salePrice": 75000000,
  "purchasePrice": 65000000,
  "city": "Bogotá",
  "status": "AVAILABLE",
  "color": "Silver",
  "engineCapacity": 1.8,
  "images": [
    {
      "id": 1,
      "url": "https://bucket.s3.amazonaws.com/images/car-15-front.jpg",
      "isPrimary": true
    }
  ],
  "createdAt": "2026-03-06T10:30:00",
  "updatedAt": "2026-03-06T10:30:00"
}

Status Codes

200 OK - Car found
401 Unauthorized - Not authenticated
404 Not Found - Car does not exist

Example

curl -X GET https://your-domain.com/v1/cars/15 \
  -H "Authorization: Bearer YOUR_TOKEN"

List Cars (Paginated)

GET /v1/cars/page/{page}

Retrieves a paginated list of cars (10 per page). Authentication: Required Authorization: vehicle:read permission

Path Parameters

page

integer

required

Page number (0-based)

Response

{
  "content": [
    {
      "id": 15,
      "plate": "ABC123",
      "brand": "Toyota",
      "line": "Corolla",
      "model": "2022",
      "status": "AVAILABLE",
      "salePrice": 75000000
    }
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 10
  },
  "totalElements": 150,
  "totalPages": 15,
  "last": false
}

Example

curl -X GET https://your-domain.com/v1/cars/page/0 \
  -H "Authorization: Bearer YOUR_TOKEN"

Update Car

PUT /v1/cars/{id}

Updates an existing car record. Authentication: Required Authorization: vehicle:update permission

Path Parameters

integer

required

Car ID to update

Request Body

Same structure as Create Car. All fields that need to be updated should be included.

{
  "plate": "ABC123",
  "brand": "Toyota",
  "line": "Corolla",
  "model": "2022",
  "fuelType": "GASOLINE",
  "bodyType": "SEDAN",
  "transmission": "AUTOMATIC",
  "mileage": 30000,
  "capacity": 5,
  "salePrice": 72000000,
  "city": "Bogotá",
  "status": "AVAILABLE"
}

Response

{
  "id": 15,
  "plate": "ABC123",
  "mileage": 30000,
  "salePrice": 72000000,
  "updatedAt": "2026-03-06T14:30:00"
}

Status Codes

200 OK - Car updated successfully
400 Bad Request - Invalid input
401 Unauthorized - Not authenticated
403 Forbidden - Missing vehicle:update permission
404 Not Found - Car does not exist

Example

curl -X PUT https://your-domain.com/v1/cars/15 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mileage": 30000,
    "salePrice": 72000000
  }'

Delete Car

DELETE /v1/cars/{id}

Permanently deletes a car from the inventory. Authentication: Required Authorization: vehicle:delete permission

Path Parameters

integer

required

Car ID to delete

Status Codes

204 No Content - Car deleted successfully
401 Unauthorized - Not authenticated
403 Forbidden - Missing vehicle:delete permission
404 Not Found - Car does not exist

Example

curl -X DELETE https://your-domain.com/v1/cars/15 \
  -H "Authorization: Bearer YOUR_TOKEN"

Change Car Status

PATCH /v1/cars/{id}/status

Updates the availability status of a car. Authentication: Required Authorization: vehicle:update permission

Path Parameters

integer

required

Car ID

Request Body

status

string

required

New status: AVAILABLE, UNAVAILABLE, or SOLD

"UNAVAILABLE"

Response

{
  "status": "UNAVAILABLE"
}

Example

curl -X PATCH https://your-domain.com/v1/cars/15/status \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '"UNAVAILABLE"'

Get Car Counts

GET /v1/cars/count

Retrieves statistics about cars in inventory. Authentication: Required Authorization: vehicle:read permission

Response

{
  "total": 150,
  "available": 120,
  "unavailable": 20,
  "sold": 10
}

Example

curl -X GET https://your-domain.com/v1/cars/count \
  -H "Authorization: Bearer YOUR_TOKEN"

Search Cars

GET /v1/cars/search

Multi-criteria search for cars with optional filters. Authentication: Required Authorization: vehicle:read permission

Query Parameters

plate

string

Filter by license plate (partial match)

brand

string

Filter by brand

line

string

Filter by line/model

model

string

Filter by year

fuelType

string

Filter by fuel type

bodyType

string

Filter by body type

transmission

string

Filter by transmission

city

string

Filter by registered city

status

string

Filter by status

minYear

integer

Minimum year

maxYear

integer

Maximum year

minCapacity

integer

Minimum passenger capacity

maxCapacity

integer

Maximum passenger capacity

minMileage

integer

Minimum mileage

maxMileage

integer

Maximum mileage

minSalePrice

number

Minimum sale price

maxSalePrice

number

Maximum sale price

Response

[
  {
    "id": 15,
    "plate": "ABC123",
    "brand": "Toyota",
    "line": "Corolla",
    "model": "2022",
    "salePrice": 75000000,
    "status": "AVAILABLE"
  }
]

Example

curl -X GET "https://your-domain.com/v1/cars/search?brand=Toyota&minYear=2020&maxSalePrice=80000000" \
  -H "Authorization: Bearer YOUR_TOKEN"

Search Cars (Paginated)

GET /v1/cars/search/page/{page}

Paginated variant of multi-criteria car search. Authentication: Required Authorization: vehicle:read permission

Path Parameters

page

integer

required

Page number (0-based)

Query Parameters

size

integer

default:"10"

Page size

All search parameters from the non-paginated endpoint are also available.

Response

{
  "content": [...],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 10
  },
  "totalElements": 45,
  "totalPages": 5
}

Example

curl -X GET "https://your-domain.com/v1/cars/search/page/0?size=20&brand=Toyota&status=AVAILABLE" \
  -H "Authorization: Bearer YOUR_TOKEN"

Motorcycles

Motorcycle endpoints follow the same pattern as car endpoints but use /v1/motorcycles as the base path.

Additional Motorcycle Fields

Motorcycles have additional fields specific to two-wheeled vehicles:

motorcycleType - Type (SPORT, CRUISER, TOURING, etc.)
engineCapacity - Engine displacement in CC
cylinderCount - Number of cylinders

Example: Create Motorcycle

curl -X POST https://your-domain.com/v1/motorcycles \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "plate": "XYZ789",
    "brand": "Yamaha",
    "line": "MT-09",
    "model": "2023",
    "motorcycleType": "SPORT",
    "fuelType": "GASOLINE",
    "transmission": "MANUAL",
    "engineCapacity": 890,
    "cylinderCount": 3,
    "mileage": 5000,
    "salePrice": 35000000,
    "city": "Medellín",
    "status": "AVAILABLE"
  }'

All motorcycle endpoints (GET, PUT, DELETE, PATCH, search) work identically to car endpoints but operate on the /v1/motorcycles path.

Vehicle Status Values

AVAILABLE - Vehicle is available for sale
UNAVAILABLE - Vehicle is temporarily unavailable
SOLD - Vehicle has been sold

Error Responses

400 Bad Request

{
  "error": "validation_error",
  "message": "Invalid input data",
  "details": [
    {
      "field": "salePrice",
      "message": "Sale price must be greater than 0"
    }
  ]
}

404 Not Found

{
  "error": "not_found",
  "message": "Car with ID 999 not found"
}

Authentication

User Management

Vehicle Management

Client Management

Purchase & Sales

Machine Learning

​Overview

​Base URL

​Cars

​Create Car

​Request Body

​Response

​Status Codes

​Example

​Get Car by ID

​Path Parameters

​Response

​Status Codes

​Example

​List Cars (Paginated)

​Path Parameters

​Response

​Example

​Update Car

​Path Parameters

​Request Body

​Response

​Status Codes

​Example

​Delete Car

​Path Parameters

​Status Codes

​Example

​Change Car Status

​Path Parameters

​Request Body

​Response

​Example

​Get Car Counts

​Response

​Example

​Search Cars

​Query Parameters

​Response

​Example

​Search Cars (Paginated)

​Path Parameters

​Query Parameters

​Response

​Example

​Motorcycles

​Additional Motorcycle Fields

​Example: Create Motorcycle

​Vehicle Status Values

​Error Responses

​400 Bad Request

​404 Not Found

Build docs developers (and LLMs) love

Overview

Base URL

Cars

Create Car

Request Body

Response

Status Codes

Example

Get Car by ID

Path Parameters

Response

Status Codes

Example

List Cars (Paginated)

Path Parameters

Response

Example

Update Car

Path Parameters

Request Body

Response

Status Codes

Example

Delete Car

Path Parameters

Status Codes

Example

Change Car Status

Path Parameters

Request Body

Response

Example

Get Car Counts

Response

Example

Search Cars

Query Parameters

Response

Example

Search Cars (Paginated)

Path Parameters

Query Parameters

Response

Example

Motorcycles

Additional Motorcycle Fields

Example: Create Motorcycle

Vehicle Status Values

Error Responses

400 Bad Request

404 Not Found