Çift yön, ara durak ve özel ihtiyaçlar

İlk rezervasyon akışındaki kimlik doğrulama, para birimi ve idempotency kuralları burada da geçerlidir. Örnek kimlikleri gerçek arama yanıtınızdan alın; örnek kişiler ve tarihler test amaçlıdır.

Hangi alan ne zaman gerekir?

Alan	Kural
itemId	Seçilen güncel teklifin anahtarı; arama ve rezervasyonda aynı hesap kullanılmalı.
passengerRequests	1–20 kayıt, tam olarak bir isLeadPassenger: true; her kayıtta ad ve soyad zorunlu, en fazla 50 karakter.
passengerCount	Toplam seyahat eden kişi sayısı. Gönderilmezse kayıt sayısı kullanılır. Gönderilirse 1–100, kayıt sayısından az olamaz; araç koltuk kapasitesi ayrıca uygulanır.
Lider yolcu phone	Zorunlu, en fazla 50 karakter. Dış teklifte + ile başlayan 7–15 rakamlık uluslararası biçim gerekir.
Yolcu email	Opsiyonel; gönderilirse geçerli adres ve en fazla 256 karakter.
Yolcu idNo	Opsiyonel; gönderilirse geçerli TCKN veya pasaport numarası. Uydurma kimlik numarası göndermeyin.
Yolcu nationalityCode	Gönderilirse iki karakterli ülke kodu; örneğin TR.
flightNo	Dış tedarikçi teklifinde alış veya bırakış havalimanıysa zorunlu. Dış akışta 2–12 karakter, en az bir harf ve rakam; harf, rakam, boşluk ve tire kullanılabilir.
costCenterId	Kullanılacaksa hesabınıza ait maliyet merkezi kimliği. Rastgele bir kimlik göndermeyin.
acceptedServiceConditionsVersion	Dış teklifte gidişin güncel serviceConditions.version değeri.
returnAcceptedServiceConditionsVersion	Dönüş dış teklifse dönüşün güncel koşul sürümü; ana gövdede gönderilir.
externalRequirementsAcknowledged	Dış teklifte koşullar ve özel ihtiyaç kapsamı kullanıcıya gösterilip kabul edildiğinde true.

passengerCount ile isimleri girilen yolcu sayısı farklı olabilir. Örneğin üç kişi için yalnız liderin kaydını gönderiyorsanız passengerCount: 3 yazın ve en az üç koltuklu teklif seçin. Dönüşte de aynı yolcu listesi ve toplam sayı kullanılır.

Çift yön rezervasyon

1. Gidiş için müsaitlik arayın ve bir teklif seçin.
2. Dönüş için alış/bırakış noktalarını ve tarihi değiştirerek ayrı bir arama yapın.
3. Her iki teklifin fiyatını, ekstralarını ve koşullarını ayrı ayrı kabul ettirin.
4. Tek POST /api/booking isteğinde dönüş teklifini returnLeg içinde gönderin.

Gidiş ve dönüş farklı araç veya tedarikçiden olabilir. Oluşturma birlikte yapılır; iki bacak başarıyla oluşursa iki ayrı rezervasyon kimliği ve PNR döner.

curl 'https://test-api.yolcugo.com/api/booking' \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept-Language: tr-TR' \
  --header 'X-Currency: TRY' \
  --header 'Idempotency-Key: YENI_BENZERSIZ_ANAHTAR' \
  --data '{
    "itemId": "GIDIS_TEKLIF_ITEM_ID",
    "passengerCount": 1,
    "flightNo": "TK1234",
    "note": "Gidiş: terminal çıkışında buluşma",
    "returnLeg": {
      "itemId": "DONUS_TEKLIF_ITEM_ID",
      "flightNo": "TK1235",
      "note": "Dönüş: otel lobisinde buluşma"
    },
    "passengerRequests": [{
      "firstName": "Demo",
      "lastName": "Yolcu",
      "phone": "+905000000000",
      "email": "demo@example.com",
      "isLeadPassenger": true
    }]
  }'

Bu örnek standart teklif içindir. Dış teklif kullanan bacakların kabul alanlarını aşağıdaki kurala göre ekleyin. note, flightNo, costCenterId, supplierExtraIds, waypoints ve yetkili tedarikçi kullanımındaki overrideNetAmount her bacak için ayrıdır; gidiş değerleri dönüşe kopyalanmaz. passengerRequests, passengerCount ve varsa partnerSubAccountCode ortaktır.

data.returnReservationId ve data.returnPnr değerlerini de saklayın. Güncelleme ve iptal bacak kimliğiyle yapılır; bir bacağı iptal etmek için yapılan partner isteği diğer bacağı otomatik iptal etmez.

Ara durakları teklif aşamasında belirtin

Her bacak için en fazla iki sıralı ara durak kullanın. Önce müsaitlik isteğine waypoints ekleyin; aynı listeyi o tekliften oluşturacağınız rezervasyona taşıyın. Durak ekleme, çıkarma, sıralama veya koordinat değişikliği yeni arama gerektirir.

{
  "requestId": "7c053eee-96a4-433c-a419-75b3775f216b",
  "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.985
  },
  "waypoints": [{
    "name": "Bomonti",
    "latitude": 41.058,
    "longitude": 28.978
  }]
}

Bu gövdeyi müsaitlik endpoint'ine gönderin. Dönen itemId ile rezervasyon gövdesine aynı waypoints dizisini ve gerekli passengerRequests alanını ekleyin. Geçerli bir placeId kullanıyorsanız onu da değiştirmeden taşıyın. Teklif ile duraklar uyuşmazsa 410 alınabilir.

waypointCount, waypointNetAmount, waypointVatAmount ve waypointGrossAmount teklifin durak kalemini açıklar. Bunları toplam fiyata yeniden eklemeyin. Dönüş duraklarını dönüş aramasında fiyatlatıp returnLeg.waypoints içinde gönderin.

Başarılı rezervasyonda bile failedWaypoints dolu olabilir: rezervasyon oluşmuş, belirtilen duraklar eklenememiştir. Kullanıcıya uyarı gösterin ve durakları rezervasyon detayındaki stops ile kontrol edin. Çift yön yanıttaki failedWaypoints gidişe aittir; dönüş duraklarını dönüş rezervasyon detayından ayrıca doğrulayın.

Saatlik kiralama

Saatlik aramada hour değerini pozitif gönderin; örneğin 4. Alış konumu ve tarihi gerekir; sabit bırakış için dropOffLocation göndermeyin. Saatlik akışa ara durak veya returnLeg eklemeyin. Rezervasyon, dönen itemId ve yolcularla standart tek yön gövdesi üzerinden oluşturulur. Süreye göre fiyatı sunucudan alın; sabit bir indirim formülü uygulamayın.

Standart ve dış tedarikçi ekstraları

Standart teklif: Tedarikçi ekstraları yanıtından seçim yapın. Yalnız seçilen tedarikçinin gerçek kimliklerini supplierExtraIds içinde gönderin; dönüş için kendi listesini kullanın.

Dış teklif: Teklifin externalExtras kataloğundaki code, maxQuantity, unitPrice ve currency alanlarını kullanın. Seçimi yeniden fiyatlama çağrısına gönderin:

{
  "itemId": "DIS_TEKLIF_ITEM_ID",
  "extras": [
    { "code": "KATALOGDAN_SECILEN_KOD", "quantity": 1 }
  ]
}

Kodu katalogdaki gerçek kodla değiştirin; miktarı katalog sınırı ve toplam yolcu sayısıyla uyumlu tutun. extras: [] seçili dış ekstraları kaldırarak yeniden teklif almak içindir. Yeni yanıttaki itemId, fiyat ve koşullarla devam edin; eski teklif anahtarına bağlı seçimleri kullanmayın. Dış teklife standart supplierExtraIds göndermeyin.

Dış teklifin koşullarını kabul etme

serviceConditions içindeki iptal sınırı, waitingMinutes, waitingStartsAt, pickUpTimeZoneId, requiresFlightNumber, specialRequestsMinHours ve requiresSupportForSpecialRequests değerlerini teklif bazında gösterin. Boş bekleme süresi veya iptal tarihi sınırsız hak anlamına gelmez.

Kullanıcı koşulları gördükten sonra gidiş için acceptedServiceConditionsVersion, dönüş için ana gövdedeki returnAcceptedServiceConditionsVersion alanına ilgili teklifin version değerini aktarın; ortak externalRequirementsAcknowledged değerini true yapın. Sürümü sabitlemeyin; yeniden fiyatlama sonrası tekrar okuyun.

İki bacağı da dış teklif olan bir booking gövdesi örneği:

{
  "itemId": "GIDIS_GUNCEL_ITEM_ID",
  "acceptedServiceConditionsVersion": "GIDIS_SERVICE_CONDITIONS_VERSION",
  "returnAcceptedServiceConditionsVersion": "DONUS_SERVICE_CONDITIONS_VERSION",
  "externalRequirementsAcknowledged": true,
  "passengerCount": 1,
  "flightNo": "TK1234",
  "passengerRequests": [{
    "firstName": "Demo",
    "lastName": "Yolcu",
    "phone": "+905000000000",
    "email": "demo@example.com",
    "isLeadPassenger": true
  }],
  "returnLeg": {
    "itemId": "DONUS_GUNCEL_ITEM_ID",
    "flightNo": "TK1235"
  }
}

Bu gövdeyi yukarıdaki booking cURL örneğindeki başlıklarla gönderin. Dört teklif ve sürüm yer tutucusunu ilgili iki tekliften alınan gerçek değerlerle değiştirin. Tek yön için returnLeg ve returnAcceptedServiceConditionsVersion gönderilmez.

Özel ihtiyaç için yalnız note yazmak hizmetin sağlanacağı anlamına gelmez. Destek gerektiren rota veya özel ihtiyaçlarda support@yolcugo.com ile iletişime geçin. EXTERNAL_ROUTE_SUPPORT_REQUIRED veya EXTERNAL_SPECIAL_REQUEST_SUPPORT_REQUIRED yanıtını yeni anahtarla tekrar tekrar rezervasyon göndererek aşmaya çalışmayın.

Cari bazlı birleştirme

Hesabınız için tanımlanmış cari kısa kodunu partnerSubAccountCode içinde gönderebilirsiniz. Kodun bulunması tek başına birleşme garantisi vermez; hesap, rota ve rezervasyon koşulları değerlendirilir. Dönüş aynı cariye bağlanır, otomatik birleştirmeye dahil edilmez.

Birleşen kayıtları transferGroupId ve groupInfo üzerinden izleyin. Grup üyeliği sıradan rezervasyon durumundan ayrı bir kavramdır. Birleşik gruptaki rezervasyonun partner güncellemesi BOOKING_LOCKED_IN_MERGED_GROUP ile reddedilebilir; destekle ilerleyin. Entegrasyonunuz birleştirme webhook'larını da işlemelidir.