Vehicle Validation

Vehicle validation is the process that determines whether a vehicle can be rented by a customer. When a customer attempts to scan a vehicle or start a ride, the system performs multiple validation checks to ensure the vehicle is safe, available, and properly configured.

Validation Overview

When Validation Occurs

Vehicle validation happens at several points:

Validation Response

Each validation returns:

• Success: Vehicle is available, ride can proceed
• Failure: Vehicle cannot be rented, with reason

Validation Checks

The system performs multiple checks in sequence. All must pass for a vehicle to be available.

1. Vehicle Exists

Check: Does the vehicle exist in the system?

Common failures:

• Invalid or corrupted QR code
• Vehicle deleted from system
• Vehicle from different environment (staging vs production)

2. Status Check

Check: Is the vehicle in an available status?

3. Active Ride Check

Check: Does the vehicle already have an active ride?

This prevents double-booking even if status wasn't properly updated.

4. Battery Level Check

Check: Does the vehicle have sufficient battery?

Example: If minimum is set to 20%, a vehicle at 18% battery fails validation.

5. IoT Device Check

Check: Is there a working IoT device attached?

Vehicles without IoT devices cannot be rented because:

• Cannot send unlock command
• Cannot track location during ride
• Cannot verify ride end

6. Location Validation

Check: Is the vehicle in an allowed zone?

7. Subaccount Check

Check: Does the customer have access to this subaccount?

This applies when:

• Multiple operators share an app
• Customer signed up with a different operator
• Regional restrictions apply

8. Customer Eligibility

Check: Is the customer allowed to rent?

Validation Messages

Success Response

When validation passes:

{
  "valid": true,
  "vehicle": {
    "id": "vehicle-uuid",
    "vehicle_number": "VH-001",
    "battery_level": 85,
    "model": "Levy Max"
  },
  "pricing": {
    "unlock_fee": 1.00,
    "per_minute_rate": 0.35
  }
}

Failure Response

When validation fails:

{
  "valid": false,
  "error_code": "VEHICLE_LOW_BATTERY",
  "message": "This vehicle's battery is too low. Please try another vehicle.",
  "details": {
    "current_battery": 12,
    "minimum_required": 20
  }
}

Common Error Codes

Configuration Options

Subaccount Settings

Each subaccount can configure validation rules:

Override Capabilities

Certain roles can bypass validation:

Real-Time Availability

Map Display

On the customer app map:

• Only validated-available vehicles appear
• Vehicles failing any check are hidden
• Updates in real-time as conditions change

Availability Calculation

The system continuously evaluates:

Available = Status is 'available'
          AND Battery >= Minimum
          AND No active ride
          AND IoT connected
          AND In service area

Troubleshooting Validation

"Vehicle Not Available"

Steps to diagnose:

1. Check vehicle status in dashboard
2. Review battery level - is it above minimum?
3. Check for active rides on the vehicle
4. Verify IoT device is linked and communicating
5. Check location - is vehicle in service area?

"Vehicle Not Found"

Possible causes:

1. QR code damaged - regenerate and replace
2. Wrong environment - staging vs production
3. Vehicle deleted - check deleted vehicles
4. Subaccount mismatch - vehicle in different subaccount

Customer Can't Rent Any Vehicle

Check customer-side issues:

1. Account status - suspended or banned?
2. Payment method - valid card on file?
3. Outstanding balance - unpaid charges?
4. Verification - age/ID verification needed?
5. Active rides - at maximum limit?

Validation Passes But Unlock Fails

Validation and unlock are separate:

1. Validation checks eligibility (database)
2. Unlock sends command to IoT device

If validation passes but unlock fails:

• IoT device may be offline (stale status)
• Command may have timed out
• Device may have hardware issue

API Reference

Validate Vehicle

POST /api/vehicles/{id}/validate

Request:

{
  "customer_id": "customer-uuid",
  "location": {
    "latitude": 40.7128,
    "longitude": -74.0060
  }
}

Response (success):

{
  "valid": true,
  "vehicle_id": "vehicle-uuid",
  "checks_passed": [
    "status",
    "battery",
    "iot_device",
    "no_active_ride",
    "service_area",
    "customer_eligible"
  ]
}

Response (failure):

{
  "valid": false,
  "error_code": "VEHICLE_LOW_BATTERY",
  "message": "Battery level is below minimum requirement",
  "failed_check": "battery",
  "details": {
    "current": 15,
    "required": 20
  }
}

Check Vehicle Availability (Lightweight)

GET /api/vehicles/{id}/available

Returns simple boolean for map display:

{
  "available": true
}

Best Practices

For Operators

1. Set appropriate minimums: Balance availability with safety
2. Monitor failed validations: Track patterns in failures
3. Keep zones updated: Ensure service areas are accurate
4. Regular status audits: Verify statuses match reality

For Integration

1. Handle all error codes: Provide helpful user messages
2. Cache appropriately: Availability changes frequently
3. Implement retries: Transient failures may resolve
4. Log validation results: Useful for debugging

For Customer Experience

1. Clear error messages: Help customers understand issues
2. Suggest alternatives: "Try another nearby vehicle"
3. Real-time updates: Remove unavailable vehicles promptly
4. Explain requirements: Battery minimums, service areas

---