Ana içeriğe geç

Ç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?​

AlanKural
itemIdSeçilen güncel teklifin anahtarı; arama ve rezervasyonda aynı hesap kullanılmalı.
passengerRequests1–46 kayıt (paylaşımlı transfer teklifinde en çok 20), tam olarak bir isLeadPassenger: true; her kayıtta ad ve soyad zorunlu, en fazla 50 karakter.
passengerCountToplam seyahat eden kişi sayısı. Gönderilmezse kayıt sayısı kullanılır. Gönderilirse 1–46, kayıt sayısından az olamaz; araç koltuk kapasitesi ayrıca uygulanır.
Lider yolcu phoneZorunlu, en fazla 50 karakter. Dış teklifte + ile başlayan 7–15 rakamlık uluslararası biçim gerekir.
Yolcu emailOpsiyonel; gönderilirse geçerli adres ve en fazla 256 karakter.
Yolcu idNoOpsiyonel; gönderilirse geçerli TCKN veya pasaport numarası. Uydurma kimlik numarası göndermeyin.
Yolcu nationalityCodeGönderilirse iki karakterli ülke kodu; örneğin TR. KKTC uyruğu için XN kullanılır.
languageOpsiyonel; bildirim ve e-posta dili: tr, en, de, ru veya ar (büyük/küçük harf duyarsız). Başka bir değer 400 ve "Desteklenmeyen dil." mesajıyla reddedilir. Gönderilmezse dil sırasıyla yolcu uyruğundan, hesabın varsayılanından, sonra alış ülkesinden seçilir. Güncellemede null gönderilirse mevcut değer korunur. Dönüş bacağı gidişin dilini taşır. SMS, push ve WhatsApp şablonları yalnız tr ve en dilindedir, de/ru/ar için yalnız birkaç e-posta şablonu vardır; bu dillerde şablonu olmayan mesaj İngilizce gönderilir.
flightNoDış 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.
costCenterIdKullanılacaksa hesabınıza ait maliyet merkezi kimliği. Rastgele bir kimlik göndermeyin.
acceptedServiceConditionsVersionDış teklifte gidişin güncel serviceConditions.version değeri.
returnAcceptedServiceConditionsVersionDönüş dış teklifse dönüşün güncel koşul sürümü; ana gövdede gönderilir.
externalRequirementsAcknowledgedDış 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.

Partner hesabıyla yapılan müsaitlik aramasında alış zamanı en erken arama anından 6 saat sonrası olabilir; daha yakını 400 doğrulama hatası döner. Kural çift yönün dönüş araması ve saatlik kiralama dahil her arama için geçerlidir.

Çift yön rezervasyon​

Etkin kurumsal otomatik havuzun uçuş/bagaj girdileri ve saat kaynakları için planlı birleştirme rehberine bakın.

  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. customerReference gidişten dönüşe kopyalanır; dönüş için farklı numara returnLeg.customerReference ile gönderilir.

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. Örnekteki +03:00 yalnız Türkiye'deki alış için geçerlidir (tarih ve saat kuralları). 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. Teklifin üst düzey pickUpTimeZoneId alanı iç tekliflerde de doludur (Türkiye'deki alışta Europe/Istanbul); dış teklif ayrımını bu alanın boş olmasına bağlamayın.

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 fiyatıyla arama​

Carileriniz için tedarikçinin tanımladığı fiyatı görmek için müsaitlik isteğinde de partnerSubAccountCode gönderin.

Tanımsız, pasif ya da başka hesaba ait kod hata vermez. Arama carisiz fiyatla yapılır, rezervasyon carisiz oluşur ve cari bazlı birleştirmeye girmez. Kodu YolcuGo'da tanımlı olup olmadığına bakmadan gönderebilirsiniz; rezervasyonun bir cariye bağlanıp bağlanmadığını GET /api/booking/{id} yanıtındaki partnerSubAccountCode alanından görürsünüz. Tek İstekte Rezervasyon da aynı kuralı uygular; orada uygulanan fiyat kapsamı webhook data.quickBooking.priceScope alanında döner.

Her araç tipi için fiyat şu sırayla seçilir: cariye tanımlanan fiyat, hesabınıza özel fiyat, hesabınızın atandığı fiyat listesi, tedarikçinin genel fiyatı. Cari için fiyat tanımlamamış tedarikçiler hesabınızın fiyatıyla döner.

Cari fiyatıyla alınan teklifi rezervasyonda aynı partnerSubAccountCode ile kullanın. Farklı kodla ya da kodsuz gönderilen istek, süresi dolmuş teklifle aynı yanıtı alır (410); yeni teklif alın. Çift yönde aynı kod iki bacak için geçerlidir.

Entegrasyon (teknik) kullanıcınızla kodsuz alınan teklif de rezervasyonda aktif bir cariye ait kodla kullanılamaz (410). Tanımsız ya da pasif kod bu durumda hata vermez; rezervasyon carisiz oluşur. Cari adına rezervasyonda aramayı baştan o carinin koduyla yapın; böylece cariye tanımlı fiyat atlanmaz.

Rezervasyon yanıtında (GET /api/booking/{id}) carinin kodu ve adı partnerSubAccountCode ve partnerSubAccountName alanlarında döner; carisiz rezervasyonda bu alanlar null olur.

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. Birleştirme ayrı bir webhook olayı üretmez: üyelik değişimi transfer.updated ile data.mergeStatus (ve kurumsal planda data.corporatePlan.groupId) değişikliği olarak, seferin sürücüsü de rezervasyonun sürücü olaylarıyla gelir (Webhook rehberi).

Birleştirilmeyecek Rezervasyon (noMerge)​

Bir yolcunun ayrı araçla gitmesi gerekiyorsa rezervasyonu noMerge: true ile oluşturun. Bu rezervasyon otomatik birleştirmeye, operasyonun elle birleştirmesine, kurumsal ve günlük planlamaya hiçbir koşulda girmez; aynı talebin diğer rezervasyonları normal kurallarla birleşebilir. Fiyat değişmez: birleştirme indirimi veya dağıtımı uygulanmaz.

  • noMerge isteğe bağlı bir boolean alandır; gönderilmezse veya null ise false sayılır. Rezervasyon oluşturma isteğinde ve Tek İstekte Rezervasyon isteğinde kullanılır.
  • Alan adı tam olarak noMerge'dür; istekte, yanıtta ve webhook'ta aynı ad kullanılır. Farklı yazılan bir alan hata vermeden yok sayılır ve rezervasyon korunmaz; entegrasyonunuzda adı birebir kullanın.
  • Alan yalnız oluşturmada okunur ve sonradan değiştirilemez; PUT /api/booking/{id} gövdesinde gönderilirse hata vermeden yok sayılır. Değiştirmek için rezervasyonu iptal edip yeniden oluşturun.
  • Gidiş-dönüş isteğinde iki bacağa da uygulanır.
  • Rezervasyon sorgularında (tek kayıt ve liste) noMerge alanı döner.
  • Her yolcu için ayrı teklif alın (passengerCount: 1) ve her rezervasyonu ayrı bir Idempotency-Key ile gönderin; teklif tek kullanımlıdır. Tek İstekte Rezervasyonda teklif ve Idempotency-Key yoktur: ayrı gidecek her yolcu için kendi customerReference değeriyle ayrı bir istek gönderin.
  • Aynı Idempotency-Key farklı bir noMerge değeriyle tekrar gönderilirse BOOKING_IDEMPOTENCY_CONFLICT (409) döner. Tek İstekte Rezervasyon uçunda aynı customerReference farklı noMerge ile tekrar gönderilirse QUICK_REFERENCE_CONFLICT (409) döner.
  • OpsPortal'daki kurumsal liste içe aktarma, birleştirilemeyen satırı önizlemede BOOKING_MERGE_PROHIBITED ile işaretler. Bu kod partner rezervasyon uçlarından dönmez.
  • Bu rezervasyonun webhook olayları her zaman kendi PNR'ı için gelir; rezervasyon hiçbir gruba girmez. Webhook data snapshot'ında noMerge alanı bulunur.

Oluşturma isteğinden örnek parça (diğer alanlar normal rezervasyonla aynıdır):

{
"passengerCount": 1,
"noMerge": true
}

GET /api/booking/{id} yanıtından örnek parça:

{
"pnr": "ABC123",
"noMerge": true
}