Skip to content

Araç Arama İşlemleri

Araç arama endpoint'leri, konum, tarih ve diğer kriterlere göre mevcut araç kiralama seçeneklerini bulmanıza olanak tanır. Arama sistemi, fiyatlandırma, araç detayları ve ek ürün ve hizmetleri alma yeteneği ile kapsamlı araç listeleri sağlar.

Araç Arama

Belirtilen konumlar ve tarihler için mevcut araçları arayın. Bu endpoint, fiyatlandırma, araç detayları ve kullanılabilirlik bilgileri dahil olmak üzere kapsamlı sonuçlar döndürür.

Arama Sonuçlarının Sıralama Mantığı

Araç arama sistemi, kullanıcı deneyimini optimize etmek için gelişmiş bir konum-bazlı algoritma kullanır. Sistem, belirtilen koordinatlar etrafında dinamik bir yarıçap taraması yaparak en uygun araç seçeneklerini sunar. Arama sonuçları öncelikle mesafe yakınlığına göre sıralanır - kullanıcının belirttiği alış/teslim noktasına en yakın lokasyonlardaki araçlar üst sıralarda gösterilir. Algoritma, aynı araç modelinin farklı tedarikçiler tarafından tekrarlı olarak listelenmesini önlemek için akıllı bir filtreleme sistemi kullanır. Bu sayede kullanıcılar, benzer özelliklerdeki araçları karşılaştırırken daha temiz ve organize bir liste görür. Sıralama kriterleri arasında mesafe önceliğinin yanı sıra fiyat-performans dengesi, tedarikçi güvenilirliği ve araç müsaitliği gibi faktörler de değerlendirilir. Yurtiçi ve yurtdışı aramalar için optimize edilmiş farklı yaklaşımlar kullanılarak, hem hızlı yanıt süreleri hem de kapsamlı sonuçlar sunulur. Sistem, performans ve kullanıcı deneyimi arasındaki dengeyi koruyarak, en ilgili araç seçeneklerini en verimli şekilde listeler.

Endpoint

POST /search/point

Kimlik Doğrulama

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

Authorization: Bearer ERIŞIM_JETONUNUZ

Para Birimi Desteği

Fiyat yanıtları için para birimini X-Currency başlığı aracılığıyla belirtebilirsiniz. Belirtilmezse varsayılan olarak Türk Lirası (TRY) kullanılacaktır.

Desteklenen Para Birimleri:

  • TRY - Türk Lirası (default)
  • USD - Amerikan Doları
  • EUR - Euro
  • GBP - İngiliz Sterlini

Para birimi başlığıyla örnek:

X-Currency: USD

Saat Dilimi

Araç kiralama hizmeti kapsamında arama yapılan lokasyonun timezone (zaman dilimi) bilgisi de gönderilmektedir. Bu nedenle, arama yapılan lokasyona ait timezone bilgisinin sisteminizde tutulması ve bu bilgiye göre /search/point isteğinin iletilmesi gerekmektedir.

Aksi durumda, eğer ilgili lokasyona ait timezone bilgisi tarafımıza iletilmezse, sistem varsayılan olarak UTC ( Coordinated Universal Time) üzerinden işlem yapmaktadır. Bu durum ise araç alış ve bırakış saatlerinde farklılıkların oluşmasına neden olabilmektedir.

İstek Gövdesi

AlanTürGerekliAçıklama
checkInDateTimedatetimeEvetAlış tarihi ve saati (RFC 3339 formatı)
checkOutDateTimedatetimeEvetTeslim tarihi ve saati (RFC 3339 formatı)
agestringEvetSürücü yaş kategorisi (18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30+)
countrystringEvetISO ülke kodu (2 karakter, ör. "TR", "US")
paymentTypestringEvetÖdeme türü: creditCard veya limit
checkInLocationobjectEvetAlış konumu koordinatları
checkInLocation.latnumberEvetEnlem koordinatı (-90 ila 90)
checkInLocation.lonnumberEvetBoylam koordinatı (-180 ila 180)
checkOutLocationobjectEvetTeslim konumu koordinatları
checkOutLocation.latnumberEvetEnlem koordinatı (-90 ila 90)
checkOutLocation.lonnumberEvetBoylam koordinatı (-180 ila 180)
commissionobjectHayırAcenteler için komisyon detayları
commission.typestringHayırKomisyon türü: percentage veya fixed
commission.percentagenumberHayırKomisyon yüzdesi (0-100, tür percentage ise gerekli)
commission.fixedobjectHayırSabit komisyon tutarı (tür fixed ise gerekli)
campaignCodestringHayırİndirimler için isteğe bağlı kampanya kodu
fullCreditbooleanHayırTam kredi ödemesi kullanılsın mı

Örnek İstek

curl -X POST https://api.pro.yolcu360.com/api/v1/search/point \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ERIŞIM_JETONUNUZ" \
  -d '{
    "checkInDateTime": "2024-08-01T10:00:00+03:00",
    "checkOutDateTime": "2024-08-08T10:00:00+03:00",
    "age": "25",
    "country": "TR",
    "paymentType": "creditCard",
    "checkInLocation": {
      "lat": 41.0082,
      "lon": 28.9784
    },
    "checkOutLocation": {
      "lat": 41.0082,
      "lon": 28.9784
    },
    "commission": {
      "type": "percentage",
      "percentage": 5.0
    },
    "fullCredit": false
  }'

Yanıt

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

{
  "count": 15,
  "results": [
    {
      "code": "ECAR",
      "searchID": "search_123456789",
      "applicableForFullCredit": true,
      "campaign": {
        "id": "summer2024",
        "name": "Yaz İndirimi"
      },
      "brand": {
        "id": "toyota",
        "name": "Toyota"
      },
      "model": {
        "id": "corolla",
        "name": "Corolla"
      },
      "class": {
        "id": "economy",
        "name": "Ekonomi"
      },
      "segment": {
        "id": "compact",
        "name": "Kompakt"
      },
      "transmission": {
        "id": "manual",
        "name": "Manuel"
      },
      "fuel": {
        "id": "petrol",
        "name": "Benzin"
      },
      "isFindeksRequired": false,
      "integrationCode": "FNDX12345",
      "seatCount": 5,
      "sippCode": "ECAR",
      "customClassName": "Ekonomi Araç",
      "vendor": {
        "id": "avis",
        "name": "Avis"
      },
      "rentalDurationInDays": 2,
      "images": [
        {
          "url": "https://example.com/car-image.jpg",
          "alt": "Toyota Corolla"
        }
      ],
      "imageURL": "https://example.com/car-image.jpg",
      "includedCoverages": {
        "collision": true,
        "theft": true
      },
      "rentalConditions": {
        "minimumAge": 21,
        "licenseRequirement": "Geçerli sürücü belgesi gerekli"
      },
      "pricing": {
        "total": {
          "amount": 50000,
          "currency": "TRY"
        },
        "net": {
          "amount": 45000,
          "currency": "TRY"
        },
        "commission": {
          "amount": 2500,
          "currency": "TRY"
        },
        "paymentTotal": {
          "amount": 50000,
          "currency": "TRY"
        },
        "vendorTotal": {
          "amount": 42500,
          "currency": "TRY"
        }
      },
      "rules": [
        {
          "type": "age_restriction",
          "description": "Minimum 21 yaş gerekli"
        }
      ]
    }
  ]
}

Yanıt Alanları

AlanTürAçıklama
countintegerToplam mevcut araç sayısı
resultsarrayMevcut araç nesneleri dizisi
results[].codestringBenzersiz araç ürün kodu
results[].searchIDstringArama oturumu tanımlayıcısı
results[].applicableForFullCreditbooleanAraç tam krediyle ödenebilir mi
results[].pricingobjectKapsamlı fiyatlandırma bilgileri
results[].pricing.totalobjectTüm ücretler dahil toplam fiyat
results[].pricing.netobjectİndirimler sonrası net fiyat
results[].pricing.commissionobjectKomisyon tutarı
results[].brandobjectAraç marka bilgileri
results[].modelobjectAraç model bilgileri
results[].classobjectAraç sınıfı (ekonomi, kompakt, vb.)
results[].transmissionobjectVites türü
results[].fuelobjectYakıt türü
results[].seatCountintegerKoltuk sayısı
results[].isFindeksRequiredbooleanFindeks kredi kontrolü gerekli mi
results[].integrationCodestringKredi kontrolleri için araçla ilişkili entegrasyon kodu
results[].vendorobjectAraç kiralama şirketi bilgileri
results[].imagesarray⚠️ Deprecated: Araç görselleri dizisi. Bunun yerine imageURL kullanın.
results[].imageURLstringAraç görsel URL'si

Findeks Kredi Kontrolü Entegrasyonu

Arama sonuçlarındaki bazı araçlar rezervasyon öncesinde Findeks kredi doğrulaması gerektirebilir. Bir araç sonucunda isFindeksRequired alanı true olduğunda, o araç için sipariş oluşturmadan önce Findeks doğrulama sürecini tamamlamanız gerekir.

Findeks Ne Zaman Gereklidir

  • Arama yanıtındaki isFindeksRequired alanı true olacaktır
  • Bu, müşterinin bir kredi uygunluk kontrolünden geçmesi gerektiğini gösterir
  • Rezervasyonun devam edebilmesi için doğrulama tamamlanmalıdır

Entegrasyon Adımları

isFindeksRequired: true olduğunda:

  1. Findeks Kontrolü Başlat: İlk kredi uygunluğunu doğrulamak için /findeks/check endpoint'ini kullanın
  2. Bilinmeyen Durumu Ele Alın: Durum "Unknown" ise, telefon doğrulaması ve rapor oluşturma ile devam edin
  3. Doğrulamayı Tamamlayın: Gerektiğinde tam Findeks iş akışını takip edin
  4. Rezervasyona Devam Edin: Sadece başarılı Findeks doğrulamasından sonra sipariş oluşturun

Findeks Gerekli Olan Yanıt Örneği

{
  "count": 1,
  "results": [
    {
      "code": "PREMIUM123",
      "searchID": "search_1234567890",
      "isFindeksRequired": true,
      "integrationCode": "FNDX67890",
      "brand": {
        "id": 1,
        "name": "BMW"
      },
      "model": {
        "id": 5,
        "name": "3 Series"
      },
      "class": {
        "id": 3,
        "name": "Premium"
      }
      // ... diğer alanlar
    }
  ]
}

Findeks doğrulamasını uygulamanın tam detayları için Findeks Kredi Uygunluğu dokümantasyonuna bakın.

Araç Ekstra Ürünlerini Al

Arama sonuçlarından belirli bir araç için mevcut ekstra ürünleri (sigorta, GPS, çocuk koltuğu, vb.) alın.

Endpoint

GET /search/{searchID}/{code}/extra-products

Kimlik Doğrulama

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

Yol Parametreleri

ParametreTürGerekliAçıklama
searchIDstringEvetAraç arama sonuçlarından arama kimliği
codestringEvetArama sonuçlarından araç ürün kodu

Örnek İstek

curl -X GET https://api.pro.yolcu360.com/api/v1/search/search_123456789/ECAR \
  -H "Authorization: Bearer ERIŞIM_JETONUNUZ"

Yanıt

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

[
  {
    "code": "GPS",
    "name": "GPS Navigasyon Sistemi",
    "type": "equipment",
    "searchID": "search_123456789",
    "min": 0,
    "max": 1,
    "campaign": {
      "id": "gps_discount",
      "name": "GPS Özel Teklifi"
    },
    "pricing": {
      "total": {
        "amount": 1500,
        "currency": "TRY"
      },
      "net": {
        "amount": 1350,
        "currency": "TRY"
      },
      "commission": {
        "amount": 75,
        "currency": "TRY"
      }
    }
  },
  {
    "code": "CDW",
    "name": "Çarpışma Hasarı Muafiyeti",
    "type": "insurance",
    "searchID": "search_123456789",
    "min": 0,
    "max": 1,
    "pricing": {
      "total": {
        "amount": 3000,
        "currency": "TRY"
      },
      "net": {
        "amount": 2700,
        "currency": "TRY"
      },
      "commission": {
        "amount": 150,
        "currency": "TRY"
      }
    }
  },
  {
    "code": "CHILD_SEAT",
    "name": "Çocuk Güvenlik Koltuğu",
    "type": "equipment",
    "searchID": "search_123456789",
    "min": 0,
    "max": 3,
    "pricing": {
      "total": {
        "amount": 2000,
        "currency": "TRY"
      },
      "net": {
        "amount": 1800,
        "currency": "TRY"
      },
      "commission": {
        "amount": 100,
        "currency": "TRY"
      }
    }
  }
]

Ekstra Ürün Alanları

AlanTürAçıklama
codestringBenzersiz ürün kodu
namestringÜrün görüntüleme adı
typestringÜrün kategorisi (equipment, insurance, service)
searchIDstringİlişkili arama oturumu kimliği
minintegerSeçilebilecek minimum miktar
maxintegerSeçilebilecek maksimum miktar
pricingobjectÜrün fiyatlandırma bilgileri
campaignobjectİlişkili kampanya veya indirim

Arama En İyi Uygulamaları

Konum Koordinatları

  • Doğruluk: Daha iyi sonuçlar için hassas koordinatlar sağlayın
  • Doğrulama: Koordinatların geçerli aralıklarda olduğundan emin olun
  • Yakınlık: Sonuçlar sağlanan koordinatlara uzaklığa göre sıralanır

Tarih ve Saat Seçimi

  • Gelecek Tarihler: Alış saati gelecekte olmalı
  • Süre: Minimum kiralama süresi genellikle 1 gündür
  • Saat Dilimleri: UTC saatleri kullanın veya saat dilimini açıkça belirtin
  • İş Saatleri: Kiralama konumu çalışma saatlerini göz önünde bulundurun

Ödeme Türleri

  • Kredi Kartı: Standart ödeme yöntemi, taksitleri destekler
  • Kredi Limiti: Onaylı kredi limitli acenteler için mevcuttur
  • Karma Ödemeler: Bazı araçlar birden fazla ödeme yöntemini destekleyebilir

Performans Optimizasyonu

  • Önbelleğe Alma: Arama sonuçları 15 dakika önbelleğe alınır
  • Sayfalama: Sonuç kümelerini sınırlamak için uygun filtreler kullanın
  • Paralel İstekler: Ekstra ürünleri aramaya paralel olarak alın

Hata İşleme

Yaygın Hata Yanıtları:

  • 400 Bad Request: Geçersiz arama parametreleri
  • 401 Unauthorized: Kimlik doğrulama gerekli veya jetonun süresi dolmuş
  • 404 Not Found: Arama kimliği veya ürün kodu bulunamadı
  • 500 Internal Server Error: Servis geçici olarak kullanılamıyor

Örnek Hata Yanıtı:

{
  "code": 1001,
  "description": "Geçersiz istek parametreleri",
  "details": {
    "field": "checkInDateTime",
    "message": "Gelecek bir tarih olmalı"
  }
}

Arama İş Akışı

Tipik Entegrasyon Akışı

  1. Konum Arama: Alış/teslim konumlarını bulmak için /locations kullanın
  2. Araç Arama: Konum koordinatları ve tarihlerle /search/point çağrısı yapın
  3. Ekstra Ürünler: Her araç için isteğe bağlı olarak /search/{searchID}/{code}/extra-products çağrısı yapın
  4. Sipariş Oluşturma: Sipariş oluşturmak için arama sonuçlarını /order ile kullanın

Kod Örneği: Eksiksiz Arama Akışı

// Adım 1: Araçları ara
const searchResponse = await fetch('/api/v1/search/point', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${accessToken}`
    },
    body: JSON.stringify({
        checkInDateTime: "2024-08-01T10:00:00+03:00",
        checkOutDateTime: "2024-08-08T10:00:00+03:00",
        age: '25',
        country: 'TR',
        paymentType: 'creditCard',
        checkInLocation: {lat: 41.0082, lon: 28.9784},
        checkOutLocation: {lat: 41.0082, lon: 28.9784}
    })
});

const searchData = await searchResponse.json();
console.log(`${searchData.count} araç bulundu`);

// Adım 2: İlk araç için ekstra ürünleri al
if (searchData.results.length > 0) {
    const vehicle = searchData.results[0];
    const extrasResponse = await fetch(
        `/api/v1/search/${vehicle.searchID}/${vehicle.code}`,
        {
            headers: {
                'Authorization': `Bearer ${accessToken}`
            }
        }
    );

    const extras = await extrasResponse.json();
    console.log(`${extras.length} ekstra ürün bulundu`);
}

Hız Sınırlama

Arama endpoint'leri hız sınırlamasına tabidir:

  • Arama endpoint'i: Kullanıcı başına dakikada maksimum 20 istek
  • Ekstra ürünler: Kullanıcı başına dakikada maksimum 100 istek

Hız sınırı hataları için üstel geri çekilmeyle uygun yeniden deneme mantığını uygulayın.