Transfer arama endpoint'leri, iki nokta arasında belirli bir saatte uygun transfer araçlarını bulmanızı sağlar. Arama, fiyatlandırma, kurallar ve iptal politikalarıyla birlikte araç tekliflerinin listesini döndürür; her teklif, sipariş adımında kullanılan searchId + code ikilisiyle tanımlanır.
Belirtilen güzergâh, saat ve yolcu sayısı için uygun transfer araçlarını arar.
POST /transfer/searchBu endpoint kimlik doğrulama gerektirir. Authorization başlığında JWT erişim jetonunuzu ekleyin:
Authorization: Bearer ERIŞIM_JETONUNUZpickup ve dropoff koordinatlarını kendi geocoding çözümünüz yerine Lokasyonlar endpoint'lerinden (yer arama + yer detayı) alın. Transfer tedarikçileri verilen koordinatları kendi hizmet bölgelerine eşler; bir tedarikçinin bölgesinin biraz dışına düşen ham koordinatlar sonuçlardan sessizce elenir. Bu nedenle aynı arama, koordinatlar yakındaki ham bir noktadan değil de /locations ilgi noktasından (havalimanı, otel, semt) geldiğinde belirgin şekilde daha fazla araç döndürür.
| Alan | Tür | Gerekli | Açıklama |
|---|---|---|---|
type | string | Evet | Yolculuk tipi: oneway veya round |
pickup | object | Evet | Alış noktası |
pickup.lat | number | Evet | Enlem (-90 ile 90 arası) |
pickup.lon | number | Evet | Boylam (-180 ile 180 arası) |
pickup.name | string | Hayır | Alış noktasının okunabilir adı |
dropoff | object | Evet | Bırakış noktası (pickup ile aynı yapı) |
pickupTime | datetime | Evet | Alış tarihi ve saati (saat dilimli RFC 3339 formatı). Gelecekte olmalı |
returnPickupTime | datetime | Koşullu | Dönüş bacağı alış saati. type round olduğunda zorunlu; pickupTime sonrasında olmalı |
passengerCount | integer | Evet | Yolcu sayısı (en az 1) |
commission | object | Hayır | Net fiyatın üzerine eklenecek acente komisyonu |
commission.type | string | Evet* | Komisyon tipi: percentage veya fixed |
commission.percentage | number | Koşullu | Komisyon yüzdesi (0-100). Tip percentage olduğunda zorunlu |
commission.fixed | object | Koşullu | {amount, currency} biçiminde sabit komisyon. Tip fixed olduğunda zorunlu |
Örneklerdeki tarihler temsilidir; kendi isteğinizde gelecekte bir alış zamanı kullanın.
curl -X POST https://api.pro.yolcu360.com/api/v1/transfer/search \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ERIŞIM_JETONUNUZ" \
-d '{
"type": "oneway",
"pickup": {"lat": 41.276146, "lon": 28.728735, "name": "Istanbul Airport (IST)"},
"dropoff": {"lat": 41.037003, "lon": 28.985092, "name": "Taksim Square"},
"pickupTime": "2027-06-15T10:00:00+03:00",
"passengerCount": 2,
"commission": {"type": "percentage", "percentage": 10}
}'Başarılı Yanıt (200 OK):
{
"searchId": "0ba0fea9-1e98-43ce-a69b-e895e2bc68a6",
"products": [
{
"code": "9972a93a-707e-403e-928e-cbb68a65584f",
"appointment": {
"pickup": {
"lat": 41.276146,
"lon": 28.728735,
"name": "Istanbul Airport (IST)"
},
"dropoff": {
"lat": 41.037003,
"lon": 28.985092,
"name": "Taksim Square"
},
"pickupTime": "2027-06-15T10:00:00+03:00",
"passengerCount": 2
},
"onewayDistance": 41662,
"onewayDuration": 2727,
"vehicle": {
"name": "Minivan",
"seatCount": 6,
"baggageCount": 6,
"image": "https://cdn.example.com/assets/images/van.png"
},
"pricing": {
"currency": "TRY",
"fees": [
{
"amount": 132000,
"currency": "TRY",
"type": "oneway",
"charge": "advance",
"description": "Outbound Trip Amount"
},
{
"amount": 13200,
"currency": "TRY",
"type": "commission",
"charge": "advance",
"description": "commission"
}
],
"vendorTotal": {
"amount": 0,
"currency": "TRY"
},
"paymentTotal": {
"amount": 145200,
"currency": "TRY"
},
"discountTotal": {
"amount": 0,
"currency": "TRY"
},
"total": {
"amount": 145200,
"currency": "TRY"
}
},
"rules": [
{
"type": "freeCancellation",
"description": "Free Cancellation"
},
{
"type": "waitForFree",
"description": "First 15 minutes of waiting free"
},
{
"type": "safeTripWithInvoice",
"description": "Safe trip with invoice"
}
],
"cancellationPolicies": [
{
"type": "freeCancel",
"until": "2027-06-15T09:00:00+03:00",
"description": "You can cancel your transfer free of charge up to 1 hour before departure."
}
]
}
]
}| Alan | Tür | Açıklama |
|---|---|---|
searchId | string | Sipariş oluşturmada kullanılan arama oturumu kimliği |
products | array | Uygun araç teklifleri |
| Alan | Tür | Açıklama |
|---|---|---|
code | string | Sipariş oluşturmada searchId ile birlikte kullanılan teklif kodu |
appointment | object | Yolculuğun tedarikçi tarafından anlaşıldığı hâli (noktalar, saatler, yolcu sayısı) |
onewayDistance | integer | Gidiş mesafesi, metre cinsinden |
onewayDuration | integer | Gidiş süresi, saniye cinsinden |
returnDistance | integer | Dönüş mesafesi, metre cinsinden (yalnızca gidiş-dönüş) |
returnDuration | integer | Dönüş süresi, saniye cinsinden (yalnızca gidiş-dönüş) |
vehicle | object | Araç adı, koltuk sayısı, bagaj sayısı ve görseli |
pricing | object | Fiyat dökümü (aşağıya bakın) |
rules | array | {type, description} biçiminde hizmet kuralları |
cancellationPolicies | array | {type, until, description} biçiminde iptal politikası pencereleri |
Tüm tutarlar en küçük para birimindedir (TRY için kuruş).
| Alan | Tür | Açıklama |
|---|---|---|
currency | string | Dökümün para birimi |
fees | array | Fiyat kalemleri: oneway ve return yolculuk tutarları, acente komisyonu istendiğinde ek commission kalemi |
vendorTotal | object | Tedarikçiye araç başında ödenecek tutar (şu an her zaman peşin tahsil edilir) |
paymentTotal | object | Ödeme adımında tahsil edilecek tutar |
discountTotal | object | Uygulanan toplam indirim |
total | object | Komisyon dahil genel toplam |
type alanını round yapın ve returnPickupTime gönderin. Yanıt, ek returnDistance ve returnDuration alanlarını ve bir return fiyat kalemini içerir:
curl -X POST https://api.pro.yolcu360.com/api/v1/transfer/search \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ERIŞIM_JETONUNUZ" \
-d '{
"type": "round",
"pickup": {"lat": 41.276146, "lon": 28.728735, "name": "Istanbul Airport (IST)"},
"dropoff": {"lat": 41.037003, "lon": 28.985092, "name": "Taksim Square"},
"pickupTime": "2027-06-15T10:00:00+03:00",
"returnPickupTime": "2027-06-20T14:00:00+03:00",
"passengerCount": 2
}'{
"searchId": "9635f52b-e0f9-4b5e-8b23-0986be44b88b",
"products": [
{
"code": "e96d7154-e0c8-45c6-81c6-54db5506bfaf",
"appointment": {
"pickup": {
"lat": 41.276146,
"lon": 28.728735,
"name": "Istanbul Airport (IST)"
},
"dropoff": {
"lat": 41.037003,
"lon": 28.985092,
"name": "Taksim Square"
},
"pickupTime": "2027-06-15T10:00:00+03:00",
"returnPickupTime": "2027-06-20T14:00:00+03:00",
"passengerCount": 2
},
"onewayDistance": 41662,
"returnDistance": 41662,
"onewayDuration": 2727,
"returnDuration": 2727,
"pricing": {
"currency": "TRY",
"fees": [
{
"amount": 132000,
"currency": "TRY",
"type": "oneway",
"charge": "advance",
"description": "Outbound Trip Amount"
},
{
"amount": 132000,
"currency": "TRY",
"type": "return",
"charge": "advance",
"description": "Return Trip Amount"
}
]
}
}
]
}Yukarıdaki örnek gidiş-dönüşe özgü alanlarla sınırlandırılmıştır; ürün yapısının tamamı tek yön yanıtıyla aynıdır.
Daha önceki bir aramadan tek bir teklifi searchId ve code ile yeniden alır. Kullanıcının seçtiği teklifi tüm arama yanıtını oturumunuzda tutmadan yeniden göstermek için kullanışlıdır.
GET /transfer/search/{searchId}/{code}Bu endpoint kimlik doğrulama gerektirir. Authorization başlığında JWT erişim jetonunuzu ekleyin.
| Parametre | Tür | Gerekli | Açıklama |
|---|---|---|---|
searchId | string | Evet | Aramadan gelen arama kimliği |
code | string | Evet | Aramadan gelen teklif kodu |
curl -X GET https://api.pro.yolcu360.com/api/v1/transfer/search/0ba0fea9-1e98-43ce-a69b-e895e2bc68a6/9972a93a-707e-403e-928e-cbb68a65584f \
-H "Authorization: Bearer ERIŞIM_JETONUNUZ"Başarılı Yanıt (200 OK):
Arama yanıtındaki products dizisinin bir öğesiyle tamamen aynı yapıda tek bir ürün nesnesi döndürür.
Arama teklifleri yaklaşık 30 dakika geçerlidir. Süresi dolmuş veya bilinmeyen bir teklif istendiğinde şu yanıt döner:
{
"code": 8003,
"description": "Transfer product not found or expired",
"details": "The search result was not found or has expired, please search again."
}Bu durumda yeni bir arama yapın ve güncel teklifleri gösterin.