Fiyatlar, para birimleri ve tarihler
Gösterim ve tahsilat
| Alan | Anlamı |
|---|---|
grossAmount | Görüntüleme para birimindeki KDV dahil toplam |
currency | Görüntüleme para birimi |
netAmount | Görüntüleme para birimindeki net tutar |
vatRate / vatAmount | KDV oranı (%) ve KDV tutarı |
tollRoadFee | Görüntüleme para birimindeki geçiş ücreti |
chargeAmount / chargeCurrency | Tahsilat 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-Language | Varsayılan para birimi |
|---|---|
tr-TR | TRY |
en-US | EUR |
de-DE | EUR |
ru-RU | RUB |
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.
| Yolcu | Tedarikçi neti |
|---|---|
| 1 | 2.500 TRY (asgari uygulanır) |
| 2 | 2 × 1.800 = 3.600 TRY |
| 3 | 3 × 1.800 = 5.400 TRY |
| 4 | 4 × 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 }
}
passengerCountgönderilmezse kişi başı fiyatlı teklifler sonuçtan çıkarılır ve yerlerine araç başı bir fiyat gösterilmez. Yanıtındata.noticeslistesinePASSENGER_COUNT_REQUIREDkodlu uyarı eklenir;supplierIdvevehicleTypeIdhangi 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.
noticeshata 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:
| Kod | Anlamı |
|---|---|
PASSENGER_COUNT_REQUIRED | Yukarıdaki gibi: yolcu sayısı olmadığı için kişi başı teklif gösterilmedi. |
SUPPLIER_VAT_MISSING | supplierId 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_ONLY | Alış 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.
| Alan | Anlamı |
|---|---|
pickUpCountryCode | Alış noktasının ülke kodu (ör. TR; KKTC için XN). |
dropOffCountryCode | Bırakış noktasının ülke kodu. Saatlik aramada ya da bırakış çözülemediğinde bulunmaz. |
uetdsApplicable | Yolculukta 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:
| Alan | Anlamı |
|---|---|
pricingBasis | PerPerson. Alan yoksa teklif araç başıdır. |
perPersonPrice | currency cinsinden kişi başı taban fiyat; baseFee ile aynı anlamdadır, müşteri toplamı değildir. |
pricedPassengerCount | Toplamı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: 3ile 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
PUTgö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;GETvePUTistekleri404dö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
400ile 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ıştaEurope/Istanbulkullanı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çinZveya doğru offset'i, açık yerel saat içinpickUpLocalDateTimekullanabilirsiniz. - Uymayan offset: Türkiye dışındaki bir alışta gönderilen offset alış noktasının
o andaki offset'ine uymuyorsa istek
400vePICKUP_TIME_OFFSET_MISMATCHile reddedilir.Zve+00:00her 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ıyorsaPICKUP_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 | Örnek | Açıklama |
|---|---|---|
pickUpTimeZoneId | Asia/Famagusta | Alış noktasının IANA saat dilimi. |
pickUpLocalDateTime | 2030-06-15T14:00:00 | Alış noktasındaki yerel saat, offset'siz. Doğrudan gösterilebilir. |
pickUpTimeZoneLabel | KKTC | Dilimin 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ı
| Kod | Ne zaman | Toparlanma |
|---|---|---|
PICKUP_TIME_OFFSET_MISMATCH | Tü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_AMBIGUOUS | Offset'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_NONEXISTENT | Offset'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.