İlk rezervasyon

Önce oturum açın. Aşağıdaki çağrılar aynı test hesabının erişim token'ıyla yapılmalıdır.

1. Müsait araçları sorgulayın

curl 'https://test-api.yolcugo.com/api/availability' \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept-Language: tr-TR' \
  --header 'X-Currency: TRY' \
  --data '{
    "requestId": "d90a6d8b-4717-4c50-b38c-9e81d06d952f",
    "bestPrice": true,
    "pickUpDateTime": "2030-06-15T12:00:00+03:00",
    "hour": 0,
    "pickUpLocation": {
      "name": "İstanbul Havalimanı",
      "latitude": 41.2611,
      "longitude": 28.7419,
      "isAirport": true
    },
    "dropOffLocation": {
      "name": "Taksim Meydanı",
      "latitude": 41.0369,
      "longitude": 28.9850
    }
  }'

Her arama için yeni requestId üretin ve alış tarihini senaryonuza göre değiştirin. Müsaitlik yanıtındaki data.vehicles içinden uygun aracı seçin. itemId değerini, fiyatı ve hizmet koşullarını birlikte alın. Örnekteki adresler ve kişiler sentetiktir. Aracın seat ve baggage kapasitesini yolculuk ihtiyacınızla karşılaştırın; fiyatı tek seçim ölçütü olarak kullanmayın.

not

Araç listesi boşsa rezervasyon oluşturmayın. Rota, tarih veya hesabınızın kapsamı için uygun teklif bulunmamış olabilir.

2. Ekstra ve rota seçimini tamamlayın

Standart tedarikçi ekstraları için teklifin supplierId değeriyle ekstra listesini alın; seçilen kimlikleri supplierExtraIds alanında gönderin.

Dış tedarikçi teklifi kullanıyorsanız externalExtras ve serviceConditions alanlarını inceleyin. Ekstraları yeniden fiyatladıktan sonra dönen teklifin itemId ve fiyatlarını kullanın.

Ara durak, çift yön, saatlik kiralama veya dış tedarikçi kullanıyorsanız ileri rezervasyon rehberindeki koşullu alanları tamamlayın. Ara duraklar rezervasyon öncesinde arama isteğinde de bulunmalıdır.

Alternatif rota için rota seçeneklerini alın. Rezervasyona seçilen seçeneğin teklif anahtarıyla devam edin.

Teklifler sınırlı süre geçerlidir; mevcut araç teklif süresi 30 dakikadır. İşleme devam ederken sunucunun yanıtını esas alın. 410 alırsanız yeniden arayın; eski teklifle devam etmeyin.

3. Rezervasyonu oluşturun

curl 'https://test-api.yolcugo.com/api/booking' \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 88709931-780b-4a11-ae3d-d1d370263de5' \
  --header 'Accept-Language: tr-TR' \
  --header 'X-Currency: TRY' \
  --data '{
    "itemId": "SECILEN_TEKLIF_ITEM_ID",
    "passengerRequests": [
      {
        "firstName": "Demo",
        "lastName": "Yolcu",
        "phone": "+905000000000",
        "email": "demo@example.com",
        "isLeadPassenger": true
      }
    ],
    "note": "Dokümantasyon test rezervasyonu"
  }'

• itemId yerine bir önceki adımda seçilen teklif anahtarını yazın.
• Aramada seçtiğiniz para birimi ve dili rezervasyon çağrısında da gönderin.
• 1–20 yolcu kaydı gönderin; tam olarak bir lider yolcu belirtin. Toplam kişi sayısı kayıt sayısından farklıysa passengerCount gönderin; seçilen araç kapasitesini aşmayın.
• Lider yolcunun telefonu zorunludur. Dış teklifte uluslararası telefon, havalimanı bacağı için uçuş numarası ve güncel koşulların kabulü gerekir. E-posta opsiyoneldir; gönderiliyorsa geçerli olmalıdır.
• Örnekteki Idempotency-Key yerine yeni bir anahtar üretin. Aynı isteği ağ hatası nedeniyle tekrarlarken aynı anahtarı koruyun. Yeni rezervasyon veya değişen rezervasyon niyeti için eski anahtarı kullanmayın.

Bu minimal örnek standart tek yön akışını gösterir. Dış tedarikçi tekliflerinde acceptedServiceConditionsVersion ve externalRequirementsAcknowledged gibi kabul alanlarını teklifin gerekliliklerine göre tamamlayın.

4. Sonucu saklayın ve sorgulayın

Rezervasyon oluşturma başarılıysa HTTP 200 döner:

Alan	Kullanımı
data.transferReservationId	Detay, güncelleme ve iptal işlemlerindeki id
data.pnr	Rezervasyon takip kodu
data.failedWaypoints	Eklenemeyen ara duraklar; null veya boşsa sorun yok
data.returnReservationId / data.returnPnr	Çift yön rezervasyonda dönüş bilgileri

curl 'https://test-api.yolcugo.com/api/booking/RESERVATION_ID' \
  --header 'Authorization: Bearer ACCESS_TOKEN'

RESERVATION_ID yerine transferReservationId yazın. Burada PNR kullanılmaz. Başarı, kaydın oluştuğunu gösterir; tedarikçi/sürücü ataması ve seyahat durumu yaşam döngüsü rehberinde açıklanmıştır. Otomatik takip için webhook bağlantısı kurabilirsiniz.

5. İptal senaryosunu test edin

İptal koşullarını kontrol ettikten sonra iptal işlemini çağırabilirsiniz:

curl --request POST \
  'https://test-api.yolcugo.com/api/booking/RESERVATION_ID/cancel' \
  --header 'Authorization: Bearer ACCESS_TOKEN'

Yanıttaki data bir kesinti yüzdesidir. 25 değeri yüzde 25 kesinti anlamına gelir; 25 TRY veya iade tutarı olarak yorumlamayın. Bu çağrı gerçek iptal yapar; yalnız ücret öğrenmek için kullanmayın.