Ana içeriğe geç

Tek İstekte Rezervasyon

POST /api/booking/quick (API referansı) adres çözümleme, availability, araç seçimi ve rezervasyon oluşturmayı tek istekte yapar. Mevcut availability ve booking endpoint'leri kullanılmaya devam eder.

Mevcut kimlik doğrulama yöntemi ve Reservations.Create izni kullanılır. Şirket token'dan belirlenir. Hesabınız aynı anda birden çok tedarikçiyle çalışabilir (ör. Ankara'da üç, İstanbul'da iki): tedarikçi seçmezsiniz, bu uç hesabınızın aktif çalıştığı tedarikçiler arasından seçer. partnerSubAccountCode ile bir cari gönderdiğinizde de bütün tedarikçileriniz aday kalır; cari yalnız fiyatı belirler: tedarikçi o cari için özel fiyat tanımladıysa o fiyat, tanımlamadıysa hesabınızın fiyatı kullanılır. Tedarikçi ilişkileri ve cari fiyat listeleri YolcuGo operasyonu tarafından kurulur.

Fiyat kapsamı​

partnerSubAccountCode isteğe bağlıdır ve fiyatın nereden okunacağını belirler:

DurumFiyatpriceScope
Kod hesabınızdaki aktif bir cariye karşılık gelir ve tedarikçi bu cari için bu güzergâh ve araç tipinde özel fiyat tanımlamıştırCarinin fiyatıAccount
Kod aktif bir cariye karşılık gelir ama tedarikçinin bu güzergâh ve araç tipi için cariye özel fiyatı yokHesabınızın fiyatı; rezervasyon yine o cariye bağlanırCustomer
Kod gönderilmedi, tanımsız, pasif ya da başka hesaba aitHesabınızın carisiz fiyatı; rezervasyon carisiz oluşurCustomer

Tanımsız kod hata vermez; müsaitlik ve standart rezervasyonla aynı kural geçerlidir. Bu uç yanıtta fiyat döndürmediği için hangi kapsamın uygulandığını webhook data.quickBooking.priceScope alanından izleyin. Cari, hesabınızın bir müşterisi gibi fiyatlanır: tedarikçi cariye özel fiyat tanımladığı güzergâhta o fiyatı, tanımlamadığı güzergâhta hesabınızın fiyatını uygular; standart müsaitlik aramasıyla aynıdır. priceScope rezervasyonun gerçekte hangi fiyatla kesildiğini gösterir. Cari ve bir tedarikçi için birden çok aktif fiyat listesi tanımlıysa o tedarikçinin fiyatı belirsizdir ve tedarikçi aday olmaz; hiçbir tedarikçi kalmazsa istek 400 QUICK_PRICE_LIST_AMBIGUOUS ile reddedilir.

{
"customerReference": "TRANSFER-12345",
"partnerSubAccountCode": "ACME",
"airportCode": "IST",
"direction": "AirportToAddress",
"address": "Caferağa Mh. Moda Cd. No:10 Kadıköy İstanbul",
"pickUpDateTime": "2030-12-10T10:00:00+03:00",
"flightNo": "TK123",
"passengerCount": 2,
"passengerRequests": [
{
"firstName": "Örnek",
"lastName": "Yolcu",
"phone": "+905551234567",
"isLeadPassenger": true
}
],
"note": "Karşılama notu",
"language": "tr"
}

partnerSubAccountCode, flightNo (en çok 20 karakter), note (en çok 600 karakter), language ve direction isteğe bağlıdır; diğer alanlar zorunludur. Cari kodu yoksa alanı göndermeyin; boş veya null değer de aynı kabul edilir. Uçuş numarası yoksa alanı göndermeyin; boş veya null değer de aynı kabul edilir. customerReference kendi sisteminizdeki rezervasyon numarasıdır ve normal rezervasyondaki customerReference ile aynı alandır; bu uçta zorunludur. En çok 100 karakterdir; başında veya sonunda boşluk, satır sonu veya başka kontrol karakteri olamaz. partnerSubAccountCode en çok 10, address en çok 1000 karakterdir. Numara rezervasyon detayında ve webhook data.customerReference alanında döner, operasyon bu numarayla arar. Numara sonradan PUT ile değiştirilse de tekrar gönderim kontrolü ilk gönderilen customerReference ile yapılır. direction, AirportToAddress veya AddressToAirport olabilir; verilmezse havalimanından adrese kabul edilir. pickUpDateTime transferin alış saatidir; Z veya saat farkı içermeli ve en az 6 saat ileride olmalıdır. Saat farkı alış noktasının o tarihteki yerel farkına uymalıdır (ör. KKTC'de kış saati +02:00); uymazsa PICKUP_TIME_OFFSET_MISMATCH döner. passengerCount toplam yolcu sayısıdır; isim listesi daha kısa olabilir. Tam olarak bir ana yolcu ve onun telefonu gerekir. supplierId ve vehicleTypeId alanları yoktur.

Fiyat seçimi, yukarıdaki fiyat kapsamı içinde şu sırayla yapılır:

  1. Adres tek bir kesin konuma çözümlenirse mevcut availability çalışır. Aday tedarikçilerin, her birinin fiyat kapsamındaki (carinin listesi ya da hesabınızın carisiz fiyatı), kapasiteye uygun ve şirket politikasınca engellenmemiş teklifleri arasından en ucuzu seçilir.
  2. Uygun teklif yoksa her aday tedarikçinin, kendi fiyat kapsamında, havalimanı ve yön için sabit tarifeleri okunur. Adresin eşleştiği bölgede tarifesi olan tedarikçi varsa yalnız onlar değerlendirilir: her biri için o bölgenin en yüksek fiyatı alınır ve bunların en ucuzu satılır.
  3. Adres/bölge çözülemezse veya hiçbir tedarikçinin o bölgede tarifesi yoksa yolculuğun nereye düştüğü bilinmez: bütün aday tedarikçilerin ilgili havalimanı yönündeki kapasiteye uygun tarifeleri arasından en yüksek fiyat satılır. Carisiz kapsamda her araç tipi ve güzergâh için önce hesabınıza özel tarife, yoksa hesabınıza atanmış liste, o da yoksa tedarikçinin genel tarifesi geçerlidir; en yüksek fiyat bu seçimden sonra aranır. Karşılaştırma; zaman kuralları, ofisten alış noktasına boş sürüş ücreti, maliyet tabanı ve mevcut fiyat hesabı uygulandıktan sonra yapılır.
  4. Hiçbir tedarikçide sabit tarife yoksa rezervasyon oluşturulmaz. Başka cari, aday olmayan tedarikçi veya havalimanının tarifesi kullanılmaz; carisiz kapsamda cari listeleri okunmaz. Yetki, şirket politikası ve fiyatlama servisi hataları fallback ile aşılmaz. Fiyat koruması aday tedarikçilerden birinin teklifini reddettiyse fallback yapılmaz. Fiyat koruması bir sabit tarifeyi reddederse o tarife seçilmez; tedarikçinin kalan tarifelerinin en yükseği alınır. Bir tedarikçinin bütün tarifeleri reddedilirse o tedarikçi değerlendirmeden çıkar; hiçbiri kalmazsa rezervasyon oluşturulmaz.

Adres çözülemezse rezervasyon yine oluşturulur (havalimanının en yüksek tarifesiyle), ama bazı kontroller yapılamaz: mesafe bilinmediği için maliyet tabanı uygulanmaz. Adresten havalimanına yönde alış noktası da bilinmediği için hizmet kapsamı havalimanı noktasıyla denetlenir ve ofisten alışa boş sürüş ücreti uygulanmaz. Bu rezervasyonlar operasyon ekranında işaretlidir; adresi ve gerekirse fiyatı operasyon düzeltir.

Fiyat her zaman TRY'dir; Accept-Language veya para birimi başlığı fiyatı değiştirmez.

Adres çözülemediğinde gönderilen metin saklanır ve operasyon sorgularında gösterilir; eksik uç için koordinat üretilmez. Fallback fiyatı, kaynak tarife ve karar nedeni rezervasyonla birlikte kaydedilir. Fallback rezervasyonları otomatik birleştirmeye alınmaz. Quick endpoint sonradan kendiliğinden yeniden fiyatlamaz.

Başarılı HTTP yanıtı (200) mevcut ApiResponse<BookingCreatedResponse> biçimindedir; data.transferReservationId ve data.pnr içerir. Sonraki durumlar mevcut transfer.created, transfer.updated ve diğer webhook olaylarıyla takip edilir. Ek callback endpoint'i gerekmez. Rezervasyon numaranız webhook data.customerReference alanında döner. Webhook data.quickBooking alanı fiyat kararını taşır:

{
"pricingSource": "AirportMaximum",
"fallbackReason": "AddressUnresolved",
"address": "Caferağa Mh. Moda Cd. No:10 Kadıköy İstanbul",
"addressResolved": false,
"priceScope": "Account",
"requestedAccountCode": "ACME"
}

priceScope: rezervasyonun gerçekte hangi fiyatla kesildiği — Account (tedarikçinin cariye özel fiyatı) veya Customer (hesabınızın fiyatı; cari gönderildiyse bu güzergâhta cariye özel fiyat yok demektir). requestedAccountCode: istekte gönderdiğiniz cari kodu (göndermediyseniz null); kod bir cariye karşılık gelmese de burada döner. pricingSource: Availability, RegionMaximum veya AirportMaximum. fallbackReason: normal seçimde null, diğer durumlarda AddressUnresolved veya NoMatchingOffer. addressResolved oluşturma anındaki karardır ve fallbackReason ile tutarlıdır; operasyon adresi sonradan düzeltirse bu transfer.updated olayıyla bildirilir, alan değişmez. Normal teklifin mevcut birleştirme/webhook kuralları korunur. Fallback oluşturma olayı birleştirme bekleme süresine alınmaz. Mevcut webhook imzası, kalıcı teslimat ve yeniden deneme mekanizması kullanılır.

Birleştirilmeyecek Rezervasyon (noMerge)​

İsteğe bağlı noMerge boolean alanı (yok veya null = false) yalnız oluşturmada verilir; true ise rezervasyon hiçbir birleştirme veya plana girmez. Alan adı tam olarak noMerge'dür; farklı yazılan alan yok sayılır. Ayrı gidecek her yolcu için kendi customerReference değeriyle ayrı bir istek gönderin. Ayrıntı için Birleştirilmeyecek Rezervasyon bölümüne bakın. Aynı customerReference farklı noMerge değeriyle tekrar gönderilirse 409 QUICK_REFERENCE_CONFLICT döner.

Tekrar gönderim​

Bu uçta tekrar güvenliğini customerReference sağlar; Idempotency-Key başlığı okunmaz. Aynı şirket ve customerReference ile aynı istek tekrar gönderilirse aynı rezervasyon döner; ikinci PNR veya oluşturma olayı üretilmez. Cari kodu ve IATA büyük/küçük harften bağımsız karşılaştırılır; gönderilmeyen, boş ve null cari kodu aynı istek sayılır; customerReference büyük/küçük harf duyarlıdır. Aynı referans farklı içerikle gönderilirse ya da referansın rezervasyonu iptal edilmiş veya silinmişse 409 QUICK_REFERENCE_CONFLICT döner. Eşzamanlı çağrılar şirket kilidi ve kalıcı unique index ile korunur; aynı referansla eşzamanlı iki çağrıdan biri rezervasyonu oluşturur, diğeri aynı rezervasyonu döner.

Aynı istekle (aynı customerReference) tekrar deneyin: zaman aşımı veya bağlantı hatası, 409 QUICK_PRICING_CHANGED, 503 QUICK_ADDRESS_SERVICE_UNAVAILABLE, diğer 5xx yanıtlar ve 429 (istek hızı sınırı; varsa Retry-After başlığındaki süre kadar bekleyin, bkz. Güvenilir istemci). Bu uçta tekrar güvenliği referansa bağlı olduğundan 5xx sonrasında aynı referansla yeniden denemek ikinci rezervasyon oluşturmaz. Bunlar dışındaki 4xx yanıtlar isteği düzeltmeden tekrar göndermekle değişmez. Toplu gönderimde istekleri hız sınırının altında tutun; 429 alan istek işlenmemiştir ve aynı referansla yeniden gönderilmelidir.

Tekrar denemeyi sınırlı tutun: en fazla 3 deneme, aralarda artan bekleme (örneğin 2, 5 ve 15 saniye). Hata sürerse referansla birlikte operasyon ekibine bildirin. Aynı referans kullanıldığı sürece arka arkaya denemeler ikinci rezervasyon oluşturmaz.

Hata kodları​

Alan doğrulama hataları (eksik/uzun alan, Z veya saat farkı olmayan pickUpDateTime, yolcu kuralları) 400 ile ve gövdede errors listesiyle döner; bunlarda errorCode yoktur. Alış saati yorumlama hataları 400 ile PICKUP_TIME_OFFSET_MISMATCH, PICKUP_TIME_AMBIGUOUS veya PICKUP_TIME_NONEXISTENT kodunu ve details alanını taşır. Quick'e özgü kodlar:

KodHTTPAnlam
QUICK_DISABLED400Quick rezervasyon platformda şu an kullanılamıyor; operasyonla iletişime geçin.
QUICK_SUPPLIER_NOT_FOUND400Hesabınız için rezervasyona uygun aktif tedarikçi tanımlı değil; operasyonla iletişime geçin.
QUICK_PRICE_LIST_AMBIGUOUS400Aday tedarikçilerin hepsinde cari için birden çok aktif fiyat listesi tanımlı; operasyonla iletişime geçin.
QUICK_AIRPORT_NOT_FOUND400Aktif IATA havalimanı bulunamadı.
QUICK_LEAD_TIME400Alış saati 6 saatten daha yakın.
QUICK_ADDRESS_SERVICE_UNAVAILABLE503Adres servisine geçici olarak ulaşılamadı; aynı istekle tekrar deneyin.
QUICK_OUT_OF_SERVICE400Alış noktası hizmet dışında.
QUICK_POLICY_BLOCKED400Rezervasyon şirket politikasıyla engellendi; gerekçe mesajdadır.
QUICK_PRICING_GUARD_BLOCKED400Fiyat koruması (boş sürüş ücreti hesaplanamadı, olası tarife veri hatası) teklifi reddetti; operasyonla iletişime geçin.
QUICK_FALLBACK_PRICE_NOT_FOUND400Kapsam ve kapasiteye uygun sabit tarife bulunamadı.
BOOKING_PRICE_OUT_OF_RANGE400Seçilen tarifenin fiyatı bir rezervasyonun alabileceği en yüksek tutarı (99.999.999,99 TL) aşıyor (tarife veri hatası); aynı istekle tekrar denemeyin, operasyonla iletişime geçin.
QUICK_PRICING_CHANGED409Hazırlık ile kayıt arasında teklif, konum veya fiyat kapsamı (cari tanımı, fiyat listesi) değişti; aynı istekle tekrar deneyin.
QUICK_REFERENCE_CONFLICT409Referans farklı bir istek için ya da sonradan iptal edilmiş veya silinmiş bir rezervasyon için kullanılmış; yeni referans gönderin.

Tedarikçi hesabıyla, başka müşteri adına (X-External-Company-Id) veya white-label oturumuyla yapılan çağrı 403 ile reddedilir.