Ana içeriğe geç

Fiyatlar, para birimleri ve tarihler

Gösterim ve tahsilat​

AlanAnlamı
grossAmountGörüntüleme para birimindeki KDV dahil toplam
currencyGörüntüleme para birimi
netAmountGörüntüleme para birimindeki net tutar
vatRate / vatAmountKDV oranı (%) ve KDV tutarı
tollRoadFeeGörüntüleme para birimindeki geçiş ücreti
chargeAmount / chargeCurrencyTahsilat tutarı ve tahsilat para birimi

Toplamı sunucunun döndürdüğü grossAmount alanından okuyun. Geçiş ücretinin KDV ayrıştırması nedeniyle netAmount + vatAmount her teklifin toplamına eşit olmayabilir. tollRoadFee tutarını grossAmount üzerine yeniden eklemeyin.

chargeAmount mevcut akışta TRY tahsilatını ifade eder. Gösterilen fiyat EUR olsa bile tahsilat para birimi farklı olabilir; ikisini kullanıcıya açıkça gösterin. Ek hizmetlerin KDV oranları farklı olabilir.

Para birimini seçme​

Müsaitlik ve rezervasyon oluşturma çağrılarında X-Currency ile TRY, EUR, USD veya RUB seçebilirsiniz. Desteklenen bir override yoksa dil varsayılanı kullanılır:

Accept-LanguageVarsayılan para birimi
tr-TRTRY
en-USEUR
de-DEEUR
ru-RURUB

Arama, yeniden fiyatlama ve rezervasyon oluşturma boyunca aynı X-Currency ve Accept-Language başlıklarını gönderin. Rezervasyonun para birimi oluşturma isteğinin bağlamından belirlenir; aramadaki tercihin otomatik taşındığını varsaymayın. Sunucunun döndürdüğü currency ve chargeCurrency alanlarını kontrol edin.

Rezervasyon detayında totalNetAmount, totalVatAmount ve totalGrossAmount TRY cinsindedir. customerTotalNet, currency alanındaki müşteri para birimindedir. exchangeRate, 1 TRY karşılığındaki müşteri para birimi tutarını belirtir; ters kur olarak kullanmayın.

Webhook data'sındaki totalNetAmount, totalVatAmount, totalGrossAmount ve supplierFee de rezervasyonun TRY tutarlarıdır. Webhook currency alanı müşteri para birimidir ve yalnız customerTotalNet'in birimidir; total* tutarlarını bu döviz etiketiyle göstermeyin.

Ekstra, ara durak ve yeniden fiyatlama​

waypointNetAmount, waypointVatAmount ve waypointGrossAmount, toplam teklifin ara durak bileşenini açıklar; toplamın üzerine ikinci kez eklenmez. supplierExtraIds ile seçilen standart ekstraların fiyat/KDV bilgilerini ekstra kataloğundan kontrol edin; teklif fiyatının henüz seçmediğiniz bütün hizmetleri kapsadığını varsaymayın.

Dış ekstra veya alternatif rota seçimi yeni teklif üretebilir. En son dönen itemId, fiyat, para birimi ve hizmet koşullarını birlikte kullanın; fiyat değiştiyse rezervasyondan önce kullanıcıya tekrar gösterin. Çift yönde her bacağın teklifini ayrı takip edin. Farklı para birimlerindeki fiyatları doğrudan toplamayın.

API tutarları JSON sayılarıdır. Finansal hesap ve saklama için dilinizin ondalık para türünü kullanmanız, ikili kayan nokta yuvarlama farklarını önlemeniz önerilir. Ekran yuvarlaması rezervasyonun sunucu toplamını değiştirmemelidir.

Kişi başı fiyatlandırma​

Tedarikçi, hesabınıza veya carinize özel fiyat listesinde bir sabit fiyatı kişi başı tanımlayabilir. Bu tarifede tedarikçinin sözleşme fiyatı yolcu başınadır ve bir asgari toplamı vardır:

toplam = max(asgari toplam, kişi başı fiyat × yolcu sayısı)

Örnek: kişi başı 1.800 TRY, asgari 2.500 TRY.

YolcuTedarikçi neti
12.500 TRY (asgari uygulanır)
22 × 1.800 = 3.600 TRY
33 × 1.800 = 5.400 TRY
44 × 1.800 = 7.200 TRY

Bu tutarlar tedarikçi netidir. Size yansıyan fiyat, araç başı tekliflerde olduğu gibi bu nete hesabınızın markup'ı, hizmet bedeli ve KDV eklenerek hesaplanır; toplamı yine grossAmount alanından okuyun. Tarifedeki gece/sezon çarpanı toplamın tamamına uygulanır; araç başı ek bedeller yolcu sayısıyla çarpılmaz. Araç başı fiyatlar değişmez; aynı aramada iki türden teklif birlikte dönebilir.

Aramada yolcu sayısı​

Kişi başı teklifleri görmek için müsaitlik isteğinde passengerCount gönderin. Alan isteğe bağlıdır; gönderilirse 1–46 arasında olmalıdır.

{
"requestId": "d90a6d8b-4717-4c50-b38c-9e81d06d952f",
"pickUpDateTime": "2030-06-15T12:00:00+03:00",
"hour": 0,
"passengerCount": 3,
"pickUpLocation": { "name": "İstanbul Havalimanı", "latitude": 41.2611, "longitude": 28.7419, "isAirport": true },
"dropOffLocation": { "name": "Taksim Meydanı", "latitude": 41.0369, "longitude": 28.9850 }
}
  • passengerCount gönderilmezse kişi başı fiyatlı teklifler sonuçtan çıkarılır ve yerlerine araç başı bir fiyat gösterilmez. Yanıtın data.notices listesine PASSENGER_COUNT_REQUIRED kodlu uyarı eklenir; supplierId ve vehicleTypeId hangi teklifin bu yüzden gösterilmediğini belirtir. Araç başı teklifler normal döner.
  • Yolcu sayısı aracın koltuk sayısını aşarsa o kişi başı teklif dönmez.
  • notices hata değildir ve yalnız uyarı varsa yanıtta bulunur.
{
"notices": [
{ "code": "PASSENGER_COUNT_REQUIRED", "supplierId": 42, "vehicleTypeId": 3 }
]
}

notices listesinde başka kodlar da görülebilir:

KodAnlamı
PASSENGER_COUNT_REQUIREDYukarıdaki gibi: yolcu sayısı olmadığı için kişi başı teklif gösterilmedi.
SUPPLIER_VAT_MISSINGsupplierId ile belirtilen tedarikçinin KDV tanımı henüz girilmediği için o tedarikçinin teklifleri sonuçtan çıkarıldı. Diğer tedarikçilerin teklifleri normal döner; tedarikçi başına bir kayıt gelir.
CROSS_COUNTRY_FIXED_ROUTE_ONLYAlış ve bırakış farklı ülkelerde. Yalnız o güzergâh için tanımlı sabit fiyatlar sunulur; bölge, kilometre ve dinamik tarife fiyatı bu aramada kullanılmaz. Sonuç gelse de gelmese de eklenir; tedarikçiye özgü değildir.
{
"notices": [
{ "code": "SUPPLIER_VAT_MISSING", "supplierId": 42 },
{ "code": "CROSS_COUNTRY_FIXED_ROUTE_ONLY" }
]
}

Yanıtın data nesnesi güzergâhın ülkelerini de bildirebilir. Bu alanlar yalnız ülke çözüldüğünde bulunur; çözülemediyse yanıtta yer almaz.

AlanAnlamı
pickUpCountryCodeAlış noktasının ülke kodu (ör. TR; KKTC için XN).
dropOffCountryCodeBırakış noktasının ülke kodu. Saatlik aramada ya da bırakış çözülemediğinde bulunmaz.
uetdsApplicableYolculukta Türkiye'nin U-ETDS bildirimi uygulanıyorsa true, uygulanmıyorsa false. Belirsizse alan hiç gelmez; bu durumu false saymayın.
{
"pickUpCountryCode": "XN",
"dropOffCountryCode": "XN",
"uetdsApplicable": false
}

Kişi başı teklifte üç ek alan bulunur; araç başı tekliflerde bu alanlar yanıtta yer almaz:

AlanAnlamı
pricingBasisPerPerson. Alan yoksa teklif araç başıdır.
perPersonPricecurrency cinsinden kişi başı taban fiyat; baseFee ile aynı anlamdadır, müşteri toplamı değildir.
pricedPassengerCountToplamın hesaplandığı yolcu sayısı.

Kişi başı teklifte mevcut fixedPrice alanı asgari tutardır: tek yolcu için geçerli tedarikçi tabanı, currency cinsinden, gece/sezon çarpanı ve araç başı ek bedeller öncesi. Teklifin toplamı değildir; toplamı grossAmount alanından okuyun.

Rezervasyonda yolcu sayısı​

Kişi başı teklif arandığı yolcu sayısına bağlıdır. Rezervasyondaki passengerCount (gönderilmezse passengerRequests kayıt sayısı) teklifin pricedPassengerCount değerine eşit olmalıdır. Eşit değilse istek 400 doğrulama hatasıyla (errorCode: VALIDATION_ERROR) reddedilir. Hata gövdesi alan adı taşımaz: message ve errors yalnız metindir ve aynı errorCode başka doğrulama hatalarında da döner. Bu yüzden yolcu sayısını rezervasyondan önce teklifin pricedPassengerCount değeriyle kendiniz karşılaştırın; sayı değiştiyse yeni yolcu sayısıyla yeniden arayın. Çift yönde iki bacak aynı passengerCount değerini kullandığından iki teklifi de aynı yolcu sayısıyla arayın.

Kişi başı rezervasyonun detayında (GET /api/booking/{id}) pricingBasis, perPersonPrice ve pricedPassengerCount döner. Buradaki perPersonPrice rezervasyon anında kaydedilen kişi başı tedarikçi fiyatıdır ve TRY cinsindendir; rezervasyon toplamları gibi. Liste uçları bu alanları taşımaz; detayı sorgulayın. Aynı üç alan webhook data görüntüsünde de bulunur (webhook rehberi). pricedPassengerCount, adı girilmiş yolcu sayısından büyük olabilir.

Yolcu sayısı sonradan değişirse​

PUT /api/booking/{id} ile gönderilen yolcu listesi yolcu sayısını değiştirirse kişi başı rezervasyon otomatik yeniden fiyatlanır. Yeni toplam, rezervasyon anında kaydedilen kişi başı fiyat, asgari tutar, çarpan ve markup ile hesaplanır; güncel tarife kullanılmaz. Örnekteki rezervasyon 3 kişiden 4 kişiye çıkarsa tedarikçi neti 5.400 TRY'den 7.200 TRY'ye yükselir.

  • Beyan ettiğiniz grup büyüklüğü fiyatın tabanıdır. passengerCount: 3 ile yalnız lider yolcuyu gönderdiyseniz, diğer iki yolcunun adını sonradan eklemek fiyatı değiştirmez. Liste beyan edilen sayıyı aşarsa yeni sayıyla yeniden fiyatlanır.
  • Bütün yolcuları adlarıyla girilmiş bir rezervasyonda yolcu çıkarmak fiyatı düşürür. Adı eksik bir grupta yolcu çıkarmak grubu küçültmez. Böyle bir grubu küçültmek için iki PUT gönderin: önce beyan ettiğiniz sayı kadar yolcunun adını girin (fiyat değişmez), sonra ikinci istekte çıkacak yolcuları listeden kaldırın; rezervasyon yeni sayıyla yeniden fiyatlanır.
  • Yalnız ad, telefon gibi yolcu bilgilerini değiştirmek fiyatı değiştirmez.
  • Kartla ödenmiş rezervasyonda yolcu sayısı değiştirilemez; istek 400 (VALIDATION_ERROR) ile reddedilir. Rezervasyonu iptal edip yeni sayıyla yeniden oluşturun. Ödemesi bekleyen ya da başarısız kart rezervasyonu API'de görünmez; GET ve PUT istekleri 404 döner.
  • Bazı operasyon durumlarında da (fiyatı elle belirlenmiş, kesinleşmiş mutabakattaki, gruplanmış, tedarikçi havuzundaki, tedarikçisi atanmamış ya da tedarikçisi değiştirilmiş rezervasyon gibi) yolcu sayısı değişikliği 400 ile reddedilir. Dönen mesaj izlenecek yolu söyler; çoğu durumda yol, rezervasyonu iptal edip yeni sayıyla yeniden oluşturmaktır. Reddedilen istekte rezervasyon değişmez.

Yeniden fiyatlanan rezervasyonda PUT yanıtı güncel toplamları döner. transfer.updated webhook'u data'da değişen her alanı eski ve yeni değeriyle, data ile aynı tipte (sayı olarak) listeler. Yeniden fiyatlamada pricedPassengerCount ve değişen tutar alanları (totalNetAmount, totalVatAmount, totalGrossAmount gibi) gelir; yolcu listesi değiştiyse passengers dizisi bütün olarak ve yolcu satırı sayısı değiştiyse passengerCount ayrıca listelenir. pricedPassengerCount fiyatın yolcu sayısıdır, passengerCount adı girilmiş yolcu satırı sayısıdır: 3 kişi beyan edilip yalnız lider yolcu girilmiş rezervasyona dört yolcu adı gönderilirse pricedPassengerCount 3 → 4, passengerCount 1 → 4 olur.

Kişi başı fiyatlı rezervasyonlar cari bazlı otomatik birleştirmeye dahil edilmez.

Tarih ve saat​

Alış saatini ISO 8601 biçiminde, Z ya da alış noktasının doğru offset'iyle gönderin:

2030-06-15T12:00:00+03:00
2030-06-15T09:00:00Z

Bu iki değer aynı anı gösterir. Örneklerdeki +03:00 yalnız Türkiye'deki alışlar için doğrudur; başka bir ülkedeki alışta o noktanın o tarihteki offset'ini (yaz/kış saati dahil) kullanın ya da Z gönderin.

  • Offset'siz değer (2030-06-15T12:00:00): alış noktasının yerel saati sayılır. Türkiye'deki alışta Europe/Istanbul kullanılır (12:00 → 09:00Z). Türkiye için genel tarih-saat kuralıyla aynıdır; Türkiye dışındaki alışta o noktanın saat dilimi uygulanır. Açık bir an için Z veya doğru offset'i, açık yerel saat için pickUpLocalDateTime kullanabilirsiniz.
  • Uymayan offset: Türkiye dışındaki bir alışta gönderilen offset alış noktasının o andaki offset'ine uymuyorsa istek 400 ve PICKUP_TIME_OFFSET_MISMATCH ile reddedilir. Z ve +00:00 her zaman kabul edilir.
  • Yaz/kış saati geçişi: Türkiye dışındaki bir alışta offset'siz saat, saatlerin geri alındığı gece iki kez yaşanıyorsa PICKUP_TIME_AMBIGUOUS, ileri alındığı gece hiç yaşanmıyorsa PICKUP_TIME_NONEXISTENT (400) döner. Bu durumda saati offset'iyle gönderin.

Yerel saati açıkça göndermek: pickUpLocalDateTime​

Müsaitlik isteğinde pickUpDateTime yerine isteğe bağlı pickUpLocalDateTime alanını gönderebilirsiniz. Değer offset'siz yerel saattir (yyyy-MM-ddTHH:mm ya da yyyy-MM-ddTHH:mm:ss) ve her ülkede, Türkiye dahil, alış noktasının yerel saati olarak yorumlanır. İki alan birlikte gönderilemez; ikisinden biri zorunludur.

{
"pickUpLocalDateTime": "2030-06-15T12:00:00"
}

Yanıttaki saat alanları​

pickUpTime her zaman UTC'dir; adı, tipi ve anlamı değişmez. Rezervasyon yanıtları ve webhook snapshot'ları yanına şu ek alanları taşır:

AlanÖrnekAçıklama
pickUpTimeZoneIdAsia/FamagustaAlış noktasının IANA saat dilimi.
pickUpLocalDateTime2030-06-15T14:00:00Alış noktasındaki yerel saat, offset'siz. Doğrudan gösterilebilir.
pickUpTimeZoneLabelKKTCDilimin görünen adı (Türkiye, KKTC gibi).

Alış saatini kullanıcıya gösterirken pickUpLocalDateTime ve pickUpTimeZoneLabel kullanın; UTC değeri sabit bir offset'le (ör. +3 saat) çevirmeyin. Alış zamanı olmayan eski kayıtlarda üç alan da null gelebilir.

Müsaitlik yanıtındaki tekliflerde (data.vehicles) pickUpTimeZoneId artık iç tekliflerde de doludur: Türkiye'deki bir alış için null yerine Europe/Istanbul döner. Bu alanın boş olmasına göre iç/dış teklif ayrımı yapmayın.

Saat hataları​

KodNe zamanToparlanma
PICKUP_TIME_OFFSET_MISMATCHTürkiye dışı alışta offset, alış noktasının o andaki offset'ine uymuyor.Saati doğru offset'le (details.expectedOffset), Z ile ya da offset'siz (yerel saat) gönderin.
PICKUP_TIME_AMBIGUOUSOffset'siz yerel saat yaz/kış geçişinde iki kez yaşanıyor.Kullanıcıya details.candidates içindeki iki seçeneği sorun; seçileni offset'iyle pickUpDateTime alanında gönderin.
PICKUP_TIME_NONEXISTENTOffset'siz yerel saat yaz/kış geçişinde hiç yaşanmıyor.Kullanıcıdan geçişten sonraki bir saat isteyin (details.firstValidLocal).

Üç hata da 400 döner. Kararı errorCode ile, seçenekleri yanıtın details alanıyla verin; message Türkçe açıklamadır, kullanıcıya gösterilir ama ayrıştırılmaz. details yalnız bu üç kodda ve her ortamda dolu gelir; diğer hatalarda alan yoktur. Tarih-saatler offset'sizdir (yyyy-MM-ddTHH:mm:ss, alış noktasının yerel saati); utc alanları ISO 8601 UTC'dir.

PICKUP_TIME_AMBIGUOUS — iki aday, ilki saatler geri alınmadan önceki (yaz):

{
"success": false,
"message": "25.10.2026 03:30 alış noktasının saat diliminde iki kez yaşanıyor (saatler geri alınıyor). Lütfen saati saat farkıyla gönderin: +03:00 ya da +02:00 (örn. 2026-10-25T03:30:00+03:00).",
"errors": [],
"statusCode": 400,
"errorCode": "PICKUP_TIME_AMBIGUOUS",
"details": {
"timeZoneId": "Asia/Famagusta",
"local": "2026-10-25T03:30:00",
"candidates": [
{ "utc": "2026-10-25T00:30:00.0000000Z", "offset": "+03:00" },
{ "utc": "2026-10-25T01:30:00.0000000Z", "offset": "+02:00" }
]
}
}

Kullanıcıya iki adayı sorun; seçileni local + offset (örn. 2026-10-25T03:30:00+02:00) ya da utc değeriyle pickUpDateTime alanında yeniden gönderin.

PICKUP_TIME_NONEXISTENT — details: timeZoneId, local (gönderilen saat), firstValidLocal (geçişten sonraki ilk geçerli yerel saat, örn. 2027-03-28T04:00:00). Kullanıcıya firstValidLocal'ı ya da başka bir saati önerin.

PICKUP_TIME_OFFSET_MISMATCH — details: timeZoneId, sentOffset (gönderilen, örn. +03:00), expectedOffset (alış noktasının o andaki offset'i, örn. +02:00), localAtPickup (gönderilen anın alış noktasındaki yerel karşılığı). Saati expectedOffset ile, Z ile ya da offset'siz gönderin.

İptal koşulları​

freeCancellationUntilUtc doluysa teklifin bildirdiği cezasız iptal son zamanını kullanın. Null olması ücretsiz iptal garantisi değildir. Özellikle dış tedarikçi tekliflerinde serviceConditions içeriğini kontrol edin; sabit bir iptal süresi varsaymayın.

İptal endpoint'inin sonucu para tutarı değil kesinti yüzdesidir. İptal işlemi ve para iadesinin bankada tamamlanması farklı durumlardır. Hesabınıza ait iptal sonucunu ve rezervasyonun ödeme bilgilerini yaşam döngüsü rehberindeki şekilde kontrol edin.