Vehicles - Masar Eagle

Overview

The Vehicles API provides endpoints for managing vehicle registrations, images, and vehicle types. Drivers can add, update, and delete their vehicles, while admins have full access to all vehicle operations.

Authentication

All endpoints require authentication. Include the JWT token in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

List Driver Vehicles

Get all vehicles belonging to the authenticated driver with images and vehicle type information.

Response

Vehicles

array

List of driver’s vehicles

TotalCount

integer

Total number of vehicles

Message

string

Status message

Example Request

curl -X GET "https://api.masareagles.com/api/vehicles" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example Response

{
  "Vehicles": [
    {
      "Id": "v_456789",
      "Name": "تويوتا كامري",
      "Model": "2022",
      "VehicleTypeId": "vt_001",
      "VehicleTypeName": "Sedan",
      "VehicleTypeIconUrl": "/uploads/vehicle-types/sedan.svg",
      "ImageUrls": [
        "/uploads/vehicles/v_456789/image1.jpg",
        "/uploads/vehicles/v_456789/image2.jpg"
      ],
      "CreatedAt": "2024-02-01T12:00:00Z",
      "UpdatedAt": "2024-02-15T10:30:00Z",
      "CanDelete": true
    }
  ],
  "TotalCount": 1,
  "Message": "عرض 1 إلى 1 من 1 عنصر"
}

Add Vehicle with Images

Add a new vehicle with optional image uploads. Supports multipart/form-data.

Path Parameters

driverId

string

required

Driver unique identifier

Request Body (Form Data)

Name

string

required

Vehicle name (2-100 characters)

Model

string

required

Vehicle model/year (2-50 characters)

VehicleTypeId

string

required

Vehicle type identifier

Images

file[]

Vehicle images (JPEG, PNG, WebP - max 5 images, 10MB each)

Response

string

Created vehicle ID

Name

string

Vehicle name

Model

string

Vehicle model

VehicleTypeId

string

Vehicle type ID

ImageUrls

array

Uploaded image URLs

Message

string

Success message

Example Request

curl -X POST "https://api.masareagles.com/api/vehicles/d_123456/with-images" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "Name=تويوتا كامري" \
  -F "Model=2022" \
  -F "VehicleTypeId=vt_001" \
  -F "[email protected]" \
  -F "[email protected]"

Example Response

{
  "Id": "v_456789",
  "Name": "تويوتا كامري",
  "Model": "2022",
  "VehicleTypeId": "vt_001",
  "ImageUrls": [
    "/uploads/vehicles/v_456789/image1.jpg",
    "/uploads/vehicles/v_456789/image2.jpg"
  ],
  "Message": "تم إضافة المركبة بنجاح"
}

Batch Add Vehicles with Images

Add multiple vehicles in a single batch operation with optional images.

Path Parameters

driverId

string

required

Driver unique identifier

Request Body (Form Data)

vehicles[0].Name

string

required

First vehicle name

vehicles[0].Model

string

required

First vehicle model

vehicles[0].VehicleTypeId

string

required

First vehicle type ID

vehicles[0].Images

file[]

First vehicle images

vehicles[1].*

object

Second vehicle (same structure as first)

Response

SuccessCount

integer

Number of successfully added vehicles

FailureCount

integer

Number of failed vehicle additions

Vehicles

array

List of successfully added vehicles

Errors

array

List of errors for failed vehicles

Example Request

curl -X POST "https://api.masareagles.com/api/vehicles/d_123456/batch/with-images" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "vehicles[0].Name=تويوتا كامري" \
  -F "vehicles[0].Model=2022" \
  -F "vehicles[0].VehicleTypeId=vt_001" \
  -F "vehicles[0][email protected]" \
  -F "vehicles[1].Name=هوندا أكورد" \
  -F "vehicles[1].Model=2021" \
  -F "vehicles[1].VehicleTypeId=vt_001"

Get Vehicle by ID

Get detailed information about a specific vehicle.

Path Parameters

vehicleId

string

required

Vehicle unique identifier

Example Request

curl -X GET "https://api.masareagles.com/api/vehicles/v_456789" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Update Vehicle

Update vehicle information and images.

Path Parameters

driverId

string

required

Driver unique identifier

vehicleId

string

required

Vehicle unique identifier

Request Body (Form Data)

Name

string

Updated vehicle name

Model

string

Updated vehicle model

VehicleTypeId

string

Updated vehicle type ID

Images

file[]

New vehicle images (replaces existing)

Example Request

curl -X PUT "https://api.masareagles.com/api/vehicles/d_123456/v_456789" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "Name=تويوتا كامري جراند" \
  -F "Model=2023"

Delete Vehicle

Delete a vehicle and all associated images. Only allowed if vehicle has no trip history.

Path Parameters

driverId

string

required

Driver unique identifier

vehicleId

string

required

Vehicle unique identifier (must start with “v_“)

Response

Message

string

Success message

Example Request

curl -X DELETE "https://api.masareagles.com/api/vehicles/d_123456/v_456789" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example Response

{
  "Message": "تم حذف المركبة بنجاح"
}

Get Driver Vehicles

Get all vehicles for a specific driver. Useful for admin operations.

Path Parameters

driverId

string

required

Driver unique identifier

Example Request

curl -X GET "https://api.masareagles.com/api/vehicles/driver/d_123456" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Get Vehicle Images

Get all images for a specific vehicle.

Path Parameters

vehicleId

string

required

Vehicle unique identifier

Response

Images

array

Array of image objects

Example Request

curl -X GET "https://api.masareagles.com/api/vehicles/v_456789/images" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Admin: List All Vehicles

Retrieve all vehicles in the system. Admin only.

Response

Same structure as List Driver Vehicles, but includes vehicles from all drivers.

Example Request

curl -X GET "https://api.masareagles.com/api/admin/vehicles" \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN"

Vehicle Types

List Vehicle Types

Get all available vehicle types.

Query Parameters

Page

integer

default:"1"

Page number

PageSize

integer

default:"20"

Items per page

IsActive

boolean

Filter by active status

Response

VehicleTypes

array

List of vehicle types

Example Request

curl -X GET "https://api.masareagles.com/api/vehicle-types?IsActive=true"

Example Response

{
  "VehicleTypes": [
    {
      "Id": "vt_001",
      "Name": "Sedan",
      "SeatCount": 4,
      "IconUrl": "/uploads/vehicle-types/sedan.svg",
      "IsActive": true
    },
    {
      "Id": "vt_002",
      "Name": "SUV",
      "SeatCount": 7,
      "IconUrl": "/uploads/vehicle-types/suv.svg",
      "IsActive": true
    }
  ],
  "TotalCount": 2
}

Error Responses

All endpoints may return the following error responses:

message

string

Error message in Arabic or English

errors

array

Detailed validation errors

Common Error Codes

400 Bad Request - Invalid request parameters or validation errors
401 Unauthorized - Missing or invalid authentication token
403 Forbidden - Insufficient permissions or vehicle has trips
404 Not Found - Vehicle or vehicle type not found
413 Payload Too Large - Image file too large
500 Internal Server Error - Server error

Example Error Response

{
  "message": "فشل التحقق من صحة البيانات",
  "errors": [
    "Vehicle 1: اسم المركبة مطلوب"
  ]
}

Overview

Identity Service

Users Service

Trips Service

Wallet & Payments

Admin APIs

Notifications

​Overview

​Authentication

​List Driver Vehicles

​Response

​Example Request

​Example Response

​Add Vehicle with Images

​Path Parameters

​Request Body (Form Data)

​Response

​Example Request

​Example Response

​Batch Add Vehicles with Images

​Path Parameters

​Request Body (Form Data)

​Response

​Example Request

​Get Vehicle by ID

​Path Parameters

​Example Request

​Update Vehicle

​Path Parameters

​Request Body (Form Data)

​Example Request

​Delete Vehicle

​Path Parameters

​Response

​Example Request

​Example Response

​Get Driver Vehicles

​Path Parameters

​Example Request

​Get Vehicle Images

​Path Parameters

​Response

​Example Request

​Admin: List All Vehicles

​Response

​Example Request

​Vehicle Types

​List Vehicle Types

​Query Parameters

​Response

​Example Request

​Example Response

​Error Responses

​Common Error Codes

​Example Error Response

Build docs developers (and LLMs) love

Overview

Authentication

List Driver Vehicles

Response

Example Request

Example Response

Add Vehicle with Images

Path Parameters

Request Body (Form Data)

Response

Example Request

Example Response

Batch Add Vehicles with Images

Path Parameters

Request Body (Form Data)

Response

Example Request

Get Vehicle by ID

Path Parameters

Example Request

Update Vehicle

Path Parameters

Request Body (Form Data)

Example Request

Delete Vehicle

Path Parameters

Response

Example Request

Example Response

Get Driver Vehicles

Path Parameters

Example Request

Get Vehicle Images

Path Parameters

Response

Example Request

Admin: List All Vehicles

Response

Example Request

Vehicle Types

List Vehicle Types

Query Parameters

Response

Example Request

Example Response

Error Responses

Common Error Codes

Example Error Response