# Yardımcı Veri İşlemleri

Yardımcı veri endpoint'leri, araç kiralama sistemi boyunca kullanılan statik referans verilerini sağlar. Bu endpoint'ler
araç sınıfları, yakıt türleri, şanzıman türleri ve teslimat seçeneklerinin standartlaştırılmış listelerini döndürür. Bu
veriler araç arama, filtreleme ve görüntüleme amaçları için vazgeçilmezdir.

Bu referans veri endpoint'leri uygulama genelinde tutarlılığı korumaya yardımcı olur ve kullanıcılara araç tercihleri ve
kiralama konfigürasyonları için standartlaştırılmış seçenekler sunar.

## Araç Sınıflarını Al

Araç kategorilendirmesi için kullanılan tüm mevcut araç sınıflarını alın. Araç sınıfları, kullanıcıların boyut, lüks
seviyesi ve kullanım amacına göre araç türlerini filtrelemesine ve tanımlamasına yardımcı olur.

### Endpoint

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

### Kimlik Doğrulama

Bu endpoint kimlik doğrulama gerektirir. Authorization başlığında JWT erişim jetonunuzu ekleyin:

```
Authorization: Bearer ERIŞIM_JETONUNUZ
```

### Örnek İstek

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

### Yanıt

**Başarılı Yanıt (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"
  }
]
```

### Yanıt Alanları

| Alan | Tür | Açıklama |
|  --- | --- | --- |
| `id` | integer | Araç sınıfı için benzersiz tanımlayıcı |
| `name` | string | Araç sınıfının görüntüleme adı |


## Yakıt Türlerini Al

Kiralık araçlar için mevcut tüm yakıt türlerini alın. Bu bilgi kullanıcıların araç verimliliğini ve çevresel etkiyi
anlamalarına yardımcı olur.

### Endpoint

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

### Kimlik Doğrulama

Bu endpoint kimlik doğrulama gerektirir. Authorization başlığında JWT erişim jetonunuzu ekleyin.

### Örnek İstek

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

### Yanıt

**Başarılı Yanıt (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"
  }
]
```

### Yanıt Alanları

| Alan | Tür | Açıklama |
|  --- | --- | --- |
| `id` | integer | Yakıt türü için benzersiz tanımlayıcı |
| `name` | string | Yakıt türünün görüntüleme adı |


## Şanzıman Türlerini Al

Kiralık araçlar için mevcut tüm şanzıman türlerini alın. Bu, kullanıcıların sürüş tercihlerine göre araç seçmelerine
yardımcı olur.

### Endpoint

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

### Kimlik Doğrulama

Bu endpoint kimlik doğrulama gerektirir. Authorization başlığında JWT erişim jetonunuzu ekleyin.

### Örnek İstek

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

### Yanıt

**Başarılı Yanıt (200 OK):**

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

### Yanıt Alanları

| Alan | Tür | Açıklama |
|  --- | --- | --- |
| `id` | integer | Şanzıman türü için benzersiz tanımlayıcı |
| `name` | string | Şanzıman türünün görüntüleme adı |


## Teslimat Türlerini Al

Araç kiralama hizmetleri için mevcut tüm teslimat seçeneklerini alın. Bu bilgi kullanıcıların alış ve teslimat
seçeneklerini anlamalarına yardımcı olur.

### Endpoint

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

### Kimlik Doğrulama

Bu endpoint kimlik doğrulama gerektirir. Authorization başlığında JWT erişim jetonunuzu ekleyin.

### Örnek İstek

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

### Yanıt

**Başarılı Yanıt (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"
  }
]
```

### Yanıt Alanları

| Alan | Tür | Açıklama |
|  --- | --- | --- |
| `id` | integer | Teslimat türü için benzersiz tanımlayıcı |
| `name` | string | Teslimat türünün görüntüleme adı |


## Ekstra Ürün Türlerini Al

Araç kiralamaları için mevcut tüm ekstra ürün türlerini alın. Bu, Bebek Koltuğu, GPS Navigasyon, Ek Sürücü, Sigorta
paketleri ve daha fazlası gibi seçenekleri içerir. İsimler Accept-Language başlığına göre çevrilir.

### Endpoint

```
GET /helper-data/extra-products
```

### Kimlik Doğrulama

Bu endpoint kimlik doğrulama gerektirir. Authorization başlığında JWT erişim jetonunuzu ekleyin.

### Başlıklar

| Başlık | Tür | Gerekli | Açıklama |
|  --- | --- | --- | --- |
| `Accept-Language` | string | Hayır | Çevrilmiş isimler için dil (en, tr, de). Varsayılan: en. |


### Örnek İstek

```bash
# İngilizce ekstra ürünleri al
curl -X GET https://api.pro.yolcu360.com/api/v1/helper-data/extra-products \
  -H "Authorization: Bearer ERIŞIM_JETONUNUZ" \
  -H "Accept-Language: en"

# Türkçe ekstra ürünleri al
curl -X GET https://api.pro.yolcu360.com/api/v1/helper-data/extra-products \
  -H "Authorization: Bearer ERIŞIM_JETONUNUZ" \
  -H "Accept-Language: tr"
```

### Yanıt

**Başarılı Yanıt (200 OK):**

```json
[
  {
    "id": 1,
    "name": "Bebek Koltuğu",
    "type": "babySeat",
    "code": "BABY_SEAT"
  },
  {
    "id": 2,
    "name": "GPS Navigasyon",
    "type": "gpsNavigation",
    "code": "GPS"
  },
  {
    "id": 3,
    "name": "Ek Sürücü",
    "type": "additionalDriver",
    "code": "ADD_DRIVER"
  },
  {
    "id": 4,
    "name": "Hasar Muafiyet Sigortası",
    "type": "insurance",
    "code": "CDW"
  },
  {
    "id": 5,
    "name": "Ekstra Kilometre",
    "type": "extraRange",
    "code": "EXTRA_RANGE"
  }
]
```

### Yanıt Alanları

| Alan | Tür | Açıklama |
|  --- | --- | --- |
| `id` | integer | Ekstra ürün türü için benzersiz tanımlayıcı |
| `name` | string | Ekstra ürünün görüntüleme adı (çevrilmiş) |
| `type` | string | Ekstra ürün tür kategorisi |
| `code` | string | Ürün kod tanımlayıcısı (örn., CDW, GPS) |


## Tedarikçileri Al

Acenta entegrasyonu için mevcut tüm araç kiralama tedarikçilerini ve alt tedarikçilerini alın. Bu endpoint, ana
tedarikçiler ve alt tedarikçiler arasında filtreleme yapılmasını ve büyük sonuç kümeleri için sayfalamayı destekler.

### Endpoint

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

### Kimlik Doğrulama

Bu endpoint kimlik doğrulama gerektirir. Authorization başlığında JWT erişim jetonunuzu ekleyin.

### Sorgu Parametreleri

| Parametre | Tür | Gerekli | Açıklama |
|  --- | --- | --- | --- |
| `hasParentID` | boolean | Hayır | Üst ID varlığına göre filtrele (alt tedarikçiler için true, ana için false) |
| `limit` | integer | Hayır | Sayfalama için döndürülecek maksimum sonuç sayısı |
| `offset` | integer | Hayır | Sayfalama için atlanacak sonuç sayısı |


### Örnek İstek

```bash
# Sayfalama ile tüm tedarikçileri al
curl -X GET "https://api.pro.yolcu360.com/api/v1/helper-data/suppliers?limit=10&offset=0" \
  -H "Authorization: Bearer ERIŞIM_JETONUNUZ"

# Sadece ana tedarikçileri al
curl -X GET "https://api.pro.yolcu360.com/api/v1/helper-data/suppliers?hasParentID=false" \
  -H "Authorization: Bearer ERIŞIM_JETONUNUZ"

# Sadece alt tedarikçileri al
curl -X GET "https://api.pro.yolcu360.com/api/v1/helper-data/suppliers?hasParentID=true" \
  -H "Authorization: Bearer ERIŞIM_JETONUNUZ"
```

### Yanıt

**Başarılı Yanıt (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"
    }
  ]
}
```

### Yanıt Alanları

| Alan | Tür | Açıklama |
|  --- | --- | --- |
| `limit` | integer | Döndürülen maksimum sonuç sayısı |
| `offset` | integer | Atlanan sonuç sayısı |
| `total` | integer | Toplam mevcut tedarikçi sayısı |
| `results` | array | Tedarikçi nesnelerinin dizisi |
| `id` | integer | Tedarikçi için benzersiz tanımlayıcı |
| `name` | string | Tedarikçinin tam adı |
| `displayName` | string | Kullanıcı arayüzü sunumu için görüntüleme adı |
| `code` | string | Entegrasyon amaçlı tedarikçi kodu |
| `parentID` | integer | Üst tedarikçi ID'si (ana tedarikçiler için null) |
| `logo` | string | Tedarikçi logo görsel URL'si (opsiyonel) |


## Hata Yönetimi

Tüm yardımcı veri endpoint'leri, yaygın hata durumları için standart hata yanıtları döndürür.

### Yaygın Hata Yanıtları

**Yetkilendirilmemiş (401):**

```json
{
  "code": 2001,
  "description": "Yetkilendirilmemiş erişim. Geçerli JWT jetonu gereklidir.",
  "details": {
    "message": "Kimlik doğrulama jetonu eksik veya geçersiz"
  }
}
```

**Sunucu Hatası (500):**

```json
{
  "code": 500,
  "description": "Sunucu hatası oluştu",
  "details": {
    "message": "Geçici hizmet kullanılamama durumu"
  }
}
```

### Hata Kodları

| Kod | Açıklama |
|  --- | --- |
| 2001 | Yetkilendirilmemiş erişim |
| 2002 | Yasak - yetersiz izinler |
| 500 | Sunucu hatası |


## Kullanım Desenleri

### Önbellekleme Stratejisi

Yardımcı veriler nispeten statiktir ve istemci tarafında önbellekleme için uygundur:

- **Önerilen Önbellek Süresi**: 24 saat
- **Önbellek Anahtarı**: Endpoint adı ve API sürümünü içersin
- **Geçersiz Kılma**: Manuel yenileme veya uygulama yeniden başlatma


### Entegrasyon İş Akışı

1. **Uygulama Başlatma**: Uygulama başlatılırken tüm yardımcı verileri yükleyin
2. **Arama Filtreleri**: Arama filtreleme için araç sınıfları, yakıt türleri ve şanzıman türlerini kullanın
3. **Görüntüleme**: Açılır menülerde ve filtrelerde kullanıcı dostu isimleri gösterin
4. **Doğrulama**: API çağrıları öncesinde kullanıcı seçimlerini yardımcı verilere göre doğrulayın


### Kod Örneği: Yardımcı Veri Yükleme

```javascript
class YardimciVeriServisi {
    constructor(apiClient) {
        this.apiClient = apiClient;
        this.onbellek = new Map();
    }

    async tumYardimciVerileriYukle(dil) {
        try {
            const [aracSiniflari, yakitTurleri, sanzimanTurleri, teslimatTurleri, ekstraUrunler] =
                await Promise.all([
                    this.getAracSiniflari(),
                    this.getYakitTurleri(),
                    this.getSanzimanTurleri(),
                    this.getTeslimatTurleri(),
                    this.getEkstraUrunler(dil)
                ]);

            return {
                aracSiniflari,
                yakitTurleri,
                sanzimanTurleri,
                teslimatTurleri,
                ekstraUrunler
            };
        } catch (error) {
            console.error('Yardımcı veri yükleme başarısız:', error);
            throw new Error('Referans veriler yüklenemiyor');
        }
    }

    async getAracSiniflari() {
        if (this.onbellek.has('aracSiniflari')) {
            return this.onbellek.get('aracSiniflari');
        }

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

    async getYakitTurleri() {
        if (this.onbellek.has('yakitTurleri')) {
            return this.onbellek.get('yakitTurleri');
        }

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

    async getSanzimanTurleri() {
        if (this.onbellek.has('sanzimanTurleri')) {
            return this.onbellek.get('sanzimanTurleri');
        }

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

    async getTeslimatTurleri() {
        if (this.onbellek.has('teslimatTurleri')) {
            return this.onbellek.get('teslimatTurleri');
        }

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

    async getEkstraUrunler(dil = 'tr') {
        const onbellekAnahtari = `ekstraUrunler_${dil}`;
        if (this.onbellek.has(onbellekAnahtari)) {
            return this.onbellek.get(onbellekAnahtari);
        }

        const response = await this.apiClient.get('/helper-data/extra-products', {
            headers: { 'Accept-Language': dil }
        });
        this.onbellek.set(onbellekAnahtari, response.data);
        return response.data;
    }

    onbellekTemizle() {
        this.onbellek.clear();
    }
}

// Kullanım örneği
const yardimciVeriServisi = new YardimciVeriServisi(apiClient);

// Uygulama başlatmada tüm verileri yükle
const yardimciVeriler = await yardimciVeriServisi.tumYardimciVerileriYukle('tr');

// Arama filtrelerinde kullan
const aramaFiltreleri = {
    aracSinifIdi: yardimciVeriler.aracSiniflari.map(c => c.id),
    yakitTuruIdi: yardimciVeriler.yakitTurleri.map(f => f.id),
    sanzimanTuruIdi: yardimciVeriler.sanzimanTurleri.map(t => t.id)
};
```

## Hız Sınırlaması

Yardımcı veri endpoint'leri, referans doğaları gereği cömert hız sınırlarına sahiptir:

- **Hız Sınırı**: Kullanıcı başına dakikada 100 istek
- **Öneri**: Yanıtları önbelleğe alın ve yalnızca gerektiğinde yenileyin
- **Yeniden Deneme Stratejisi**: Geçici hatalar için üstel geri çekilme uygulayın


## En İyi Uygulamalar

### Performans Optimizasyonu

1. **Toplu Yükleme**: Uygulama başlatılırken tüm yardımcı verileri paralel olarak yükleyin
2. **Yerel Önbellekleme**: Yanıtları minimum 24 saat istemci tarafında önbelleğe alın
3. **Tembel Yükleme**: Yardımcı verileri yalnızca belirli özellikler için gerektiğinde yükleyin
4. **Hata Dayanıklılığı**: Başarısız istekler için yedek mekanizmalar uygulayın


### Veri İşleme

1. **ID Referansları**: API çağrıları için her zaman ID değerlerini, kullanıcı arayüzü için görüntüleme adlarını
kullanın
2. **Doğrulama**: Kullanıcı seçimlerini mevcut yardımcı verilere göre doğrulayın
3. **Yerelleştirme**: Uluslararası kullanıcılar için yerelleştirilmiş adlar uygulamayı düşünün
4. **Tutarlılık**: Yardımcı verileri tüm uygulama özelliklerinde tutarlı olarak kullanın


### Güvenlik Hususları

1. **Kimlik Doğrulama**: Her zaman geçerli JWT jetonları ekleyin
2. **Jeton Yenileme**: Uzun süreli uygulamalar için otomatik jeton yenileme uygulayın
3. **HTTPS**: Tüm API iletişimleri için HTTPS kullanın
4. **Hız Sınırlaması**: Hız sınırlarına saygı gösterin ve uygun yeniden deneme mantığı uygulayın