Ç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–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. |
passengerCount | Toplam 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 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. KKTC uyruğu için XN kullanılır. |
language | Opsiyonel; 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. |
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.
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.
- Gidiş için müsaitlik arayın ve bir teklif seçin.
- Dönüş için alış/bırakış noktalarını ve tarihi değiştirerek ayrı bir arama yapın.
- Her iki teklifin fiyatını, ekstralarını ve koşullarını ayrı ayrı kabul ettirin.
- Tek
POST /api/bookingisteğinde dönüş teklifinireturnLegiç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.
noMergeisteğe bağlı bir boolean alandır; gönderilmezse veyanullisefalsesayı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)
noMergealanı döner. - Her yolcu için ayrı teklif alın (
passengerCount: 1) ve her rezervasyonu ayrı birIdempotency-Keyile gönderin; teklif tek kullanımlıdır. Tek İstekte Rezervasyonda teklif veIdempotency-Keyyoktur: ayrı gidecek her yolcu için kendicustomerReferencedeğeriyle ayrı bir istek gönderin. - Aynı
Idempotency-Keyfarklı birnoMergedeğeriyle tekrar gönderilirseBOOKING_IDEMPOTENCY_CONFLICT(409) döner. Tek İstekte Rezervasyon uçunda aynıcustomerReferencefarklınoMergeile tekrar gönderilirseQUICK_REFERENCE_CONFLICT(409) döner. - OpsPortal'daki kurumsal liste içe aktarma, birleştirilemeyen satırı önizlemede
BOOKING_MERGE_PROHIBITEDile 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
datasnapshot'ındanoMergealanı 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
}