# Helper Data Operations

Helper data endpoints provide static reference data used throughout the car rental system. These endpoints return
standardized lists of car classes, fuel types, transmission types, and delivery options that are essential for vehicle
search, filtering, and display purposes.

These reference data endpoints help maintain consistency across the application and provide users with standardized
options for vehicle preferences and rental configurations.

## Get Car Classes

Retrieve all available car classes used for vehicle categorization. Car classes help users filter and identify vehicle
types based on size, luxury level, and intended use.

### Endpoint


```
GET /helper-data/car-classes
```

### Authentication

This endpoint requires authentication. Include your JWT access token in the Authorization header:


```
Authorization: Bearer YOUR_ACCESS_TOKEN
```

### Example Request


```bash
curl -X GET https://api.pro.yolcu360.com/api/v1/helper-data/car-classes \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Response

**Success Response (200 OK):**


```json
[
  {
    "id": 12,
    "name": "Lüks Elit"
  },
  {
    "id": 18,
    "name": "Moving van"
  },
  {
    "id": 19,
    "name": "15 passenger van"
  },
  {
    "id": 24,
    "name": "Small SUV"
  },
  {
    "id": 26,
    "name": "Large SUV"
  },
  {
    "id": 27,
    "name": "Exotic SUV"
  },
  {
    "id": 11,
    "name": "Büyük"
  },
  {
    "id": 2,
    "name": "Orta"
  },
  {
    "id": 17,
    "name": "12 passenger van"
  },
  {
    "id": 22,
    "name": "Small/medium truck"
  },
  {
    "id": 28,
    "name": "Four wheel drive"
  },
  {
    "id": 7,
    "name": "Kompakt"
  },
  {
    "id": 4,
    "name": "Prestij"
  },
  {
    "id": 1,
    "name": "Ekonomi"
  },
  {
    "id": 14,
    "name": "Mini"
  },
  {
    "id": 35,
    "name": "Fullsize elite"
  },
  {
    "id": 36,
    "name": "Premium elite"
  },
  {
    "id": 13,
    "name": "Mini Elit"
  },
  {
    "id": 3,
    "name": "Standart"
  },
  {
    "id": 23,
    "name": "Large truck"
  },
  {
    "id": 25,
    "name": "Medium SUV"
  },
  {
    "id": 5,
    "name": "Premium"
  },
  {
    "id": 9,
    "name": "Van"
  },
  {
    "id": 6,
    "name": "Konfor"
  },
  {
    "id": 20,
    "name": "Cargo van"
  },
  {
    "id": 31,
    "name": "Economy elite"
  },
  {
    "id": 10,
    "name": "SUV"
  },
  {
    "id": 15,
    "name": "Subcompact"
  },
  {
    "id": 16,
    "name": "Minivan"
  },
  {
    "id": 29,
    "name": "Special"
  },
  {
    "id": 34,
    "name": "Standard elite"
  },
  {
    "id": 38,
    "name": "Oversize"
  },
  {
    "id": 8,
    "name": "Lüks"
  },
  {
    "id": 21,
    "name": "Unique"
  },
  {
    "id": 32,
    "name": "Compact elite"
  },
  {
    "id": 33,
    "name": "Intermediate elite"
  },
  {
    "id": 37,
    "name": "Luxury elite"
  }
]
```

### Response Fields

| Field | Type | Description |
|  --- | --- | --- |
| `id` | integer | Unique identifier for the car class |
| `name` | string | Display name of the car class |


## Get Fuel Types

Retrieve all available fuel types for rental vehicles. This information helps users understand vehicle efficiency and
environmental impact.

### Endpoint


```
GET /helper-data/fuel-types
```

### Authentication

This endpoint requires authentication. Include your JWT access token in the Authorization header.

### Example Request


```bash
curl -X GET https://api.pro.yolcu360.com/api/v1/helper-data/fuel-types \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Response

**Success Response (200 OK):**


```json
[
  {
    "id": 2,
    "name": "Dizel"
  },
  {
    "id": 9,
    "name": "Unspecified"
  },
  {
    "id": 10,
    "name": "Multifuel"
  },
  {
    "id": 8,
    "name": "Benzin/Dizel"
  },
  {
    "id": 14,
    "name": "Dizel Elektrik"
  },
  {
    "id": 15,
    "name": "Benzin Elektrik"
  },
  {
    "id": 17,
    "name": "Dizel Hibrit"
  },
  {
    "id": 16,
    "name": "Hidrojen"
  },
  {
    "id": 5,
    "name": "LPG"
  },
  {
    "id": 1,
    "name": "Benzin"
  },
  {
    "id": 7,
    "name": "Hibrit"
  },
  {
    "id": 11,
    "name": "Elektrik"
  },
  {
    "id": 13,
    "name": "Benzin/Lpg"
  }
]
```

### Response Fields

| Field | Type | Description |
|  --- | --- | --- |
| `id` | integer | Unique identifier for the fuel type |
| `name` | string | Display name of the fuel type |


## Get Transmission Types

Retrieve all available transmission types for rental vehicles. This helps users select vehicles based on their driving
preferences.

### Endpoint


```
GET /helper-data/transmission-types
```

### Authentication

This endpoint requires authentication. Include your JWT access token in the Authorization header.

### Example Request


```bash
curl -X GET https://api.pro.yolcu360.com/api/v1/helper-data/transmission-types \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Response

**Success Response (200 OK):**


```json
[
  {
    "id": 1,
    "name": "Manuel"
  },
  {
    "id": 2,
    "name": "Otomatik"
  }
]
]
```

### Response Fields

| Field | Type | Description |
|  --- | --- | --- |
| `id` | integer | Unique identifier for the transmission type |
| `name` | string | Display name of the transmission type |


## Get Delivery Types

Retrieve all available delivery options for car rental services. This information helps users understand pickup and
delivery options.

### Endpoint


```
GET /helper-data/delivery-types
```

### Authentication

This endpoint requires authentication. Include your JWT access token in the Authorization header.

### Example Request


```bash
curl -X GET https://api.pro.yolcu360.com/api/v1/helper-data/delivery-types \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Response

**Success Response (200 OK):**


```json
[
  {
    "id": 7,
    "name": "Shuttle Bus"
  },
  {
    "id": 3,
    "name": "Ofis"
  },
  {
    "id": 1,
    "name": "Adrese Teslim"
  },
  {
    "id": 2,
    "name": "Vale Hizmeti"
  },
  {
    "id": 4,
    "name": "Terminal Dışı Buluşma Karşılama"
  },
  {
    "id": 5,
    "name": "Terminal İçi Ofis"
  },
  {
    "id": 6,
    "name": "Terminal Dışı Vale Hizmeti"
  }
]
```

### Response Fields

| Field | Type | Description |
|  --- | --- | --- |
| `id` | integer | Unique identifier for the delivery type |
| `name` | string | Display name of the delivery type |


## Get Suppliers

Retrieve all available car rental suppliers and subsuppliers for agency integration. This endpoint supports filtering
between main suppliers and subsuppliers, as well as pagination for large result sets.

### Endpoint


```
GET /helper-data/suppliers
```

### Authentication

This endpoint requires authentication. Include your JWT access token in the Authorization header.

### Query Parameters

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `hasParentID` | boolean | No | Filter by parent ID presence (true for subsuppliers, false for main) |
| `limit` | integer | No | Maximum number of results to return for pagination |
| `offset` | integer | No | Number of results to skip for pagination |


### Example Request


```bash
# Get all suppliers with pagination
curl -X GET "https://api.pro.yolcu360.com/api/v1/helper-data/suppliers?limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Get only main suppliers
curl -X GET "https://api.pro.yolcu360.com/api/v1/helper-data/suppliers?hasParentID=false" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Get only subsuppliers
curl -X GET "https://api.pro.yolcu360.com/api/v1/helper-data/suppliers?hasParentID=true" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Response

**Success Response (200 OK):**


```json
{
  "limit": 10,
  "offset": 0,
  "total": 45,
  "results": [
    {
      "id": 123,
      "name": "Enterprise Rent-A-Car",
      "displayName": "Enterprise",
      "code": "ENTERPRISE",
      "parentID": null,
      "logo": "https://cdn.example.com/logos/enterprise.png"
    },
    {
      "id": 124,
      "name": "Enterprise Premium",
      "displayName": "Enterprise Premium",
      "code": "ENTERPRISE_PREMIUM",
      "parentID": 123,
      "logo": "https://cdn.example.com/logos/enterprise-premium.png"
    }
  ]
}
```

### Response Fields

| Field | Type | Description |
|  --- | --- | --- |
| `limit` | integer | Maximum number of results returned |
| `offset` | integer | Number of results skipped |
| `total` | integer | Total number of suppliers available |
| `results` | array | Array of supplier objects |
| `id` | integer | Unique identifier for the supplier |
| `name` | string | Full name of the supplier |
| `displayName` | string | Display name for UI presentation |
| `code` | string | Supplier code for integration purposes |
| `parentID` | integer | Parent supplier ID (null for main suppliers) |
| `logo` | string | URL to supplier logo image (optional) |


## Error Handling

All helper data endpoints return standard error responses for common error conditions.

### Common Error Responses

**Unauthorized (401):**


```json
{
  "code": 2001,
  "description": "Unauthorized access. Valid JWT token required.",
  "details": {
    "message": "Authentication token is missing or invalid"
  }
}
```

**Internal Server Error (500):**


```json
{
  "code": 500,
  "description": "Internal server error occurred",
  "details": {
    "message": "Temporary service unavailability"
  }
}
```

### Error Codes

| Code | Description |
|  --- | --- |
| 2001 | Unauthorized access |
| 2002 | Forbidden - insufficient permissions |
| 500 | Internal server error |


## Usage Patterns

### Caching Strategy

Helper data is relatively static and suitable for client-side caching:

- **Recommended Cache Duration**: 24 hours
- **Cache Key**: Include endpoint name and API version
- **Invalidation**: Manual refresh or application restart


### Integration Workflow

1. **Application Startup**: Load all helper data during app initialization
2. **Search Filters**: Use car classes, fuel types, and transmission types for search filtering
3. **Display**: Show user-friendly names in dropdown menus and filters
4. **Validation**: Validate user selections against helper data before API calls


### Code Example: Loading Helper Data


```javascript
class HelperDataService {
    constructor(apiClient) {
        this.apiClient = apiClient;
        this.cache = new Map();
    }

    async loadAllHelperData() {
        try {
            const [carClasses, fuelTypes, transmissionTypes, deliveryTypes] =
                await Promise.all([
                    this.getCarClasses(),
                    this.getFuelTypes(),
                    this.getTransmissionTypes(),
                    this.getDeliveryTypes()
                ]);

            return {
                carClasses,
                fuelTypes,
                transmissionTypes,
                deliveryTypes
            };
        } catch (error) {
            console.error('Failed to load helper data:', error);
            throw new Error('Unable to load reference data');
        }
    }

    async getCarClasses() {
        if (this.cache.has('carClasses')) {
            return this.cache.get('carClasses');
        }

        const response = await this.apiClient.get('/helper-data/car-classes');
        this.cache.set('carClasses', response.data);
        return response.data;
    }

    async getFuelTypes() {
        if (this.cache.has('fuelTypes')) {
            return this.cache.get('fuelTypes');
        }

        const response = await this.apiClient.get('/helper-data/fuel-types');
        this.cache.set('fuelTypes', response.data);
        return response.data;
    }

    async getTransmissionTypes() {
        if (this.cache.has('transmissionTypes')) {
            return this.cache.get('transmissionTypes');
        }

        const response = await this.apiClient.get('/helper-data/transmission-types');
        this.cache.set('transmissionTypes', response.data);
        return response.data;
    }

    async getDeliveryTypes() {
        if (this.cache.has('deliveryTypes')) {
            return this.cache.get('deliveryTypes');
        }

        const response = await this.apiClient.get('/helper-data/delivery-types');
        this.cache.set('deliveryTypes', response.data);
        return response.data;
    }

    clearCache() {
        this.cache.clear();
    }
}

// Usage example
const helperDataService = new HelperDataService(apiClient);

// Load all data at application startup
const helperData = await helperDataService.loadAllHelperData();

// Use in search filters
const searchFilters = {
    carClassIds: helperData.carClasses.map(c => c.id),
    fuelTypeIds: helperData.fuelTypes.map(f => f.id),
    transmissionTypeIds: helperData.transmissionTypes.map(t => t.id)
};
```

## Rate Limiting

Helper data endpoints have generous rate limits due to their reference nature:

- **Rate Limit**: 100 requests per minute per user
- **Recommendation**: Cache responses and refresh only when necessary
- **Retry Strategy**: Implement exponential backoff for temporary failures


## Best Practices

### Performance Optimization

1. **Batch Loading**: Load all helper data in parallel during application initialization
2. **Local Caching**: Cache responses client-side for 24 hours minimum
3. **Lazy Loading**: Load helper data only when needed for specific features
4. **Error Resilience**: Implement fallback mechanisms for failed requests


### Data Handling

1. **ID References**: Always use ID values for API calls, display names for UI
2. **Validation**: Validate user selections against current helper data
3. **Localization**: Consider implementing localized names for international users
4. **Consistency**: Use helper data consistently across all application features


### Security Considerations

1. **Authentication**: Always include valid JWT tokens
2. **Token Refresh**: Implement automatic token refresh for long-running applications
3. **HTTPS**: Use HTTPS for all API communications
4. **Rate Limiting**: Respect rate limits and implement appropriate retry logic