Skip to content
/
Siparişler
Son güncelleme

Transfer Siparişleri

Transfer sipariş endpoint'leri, arama tekliflerinden rezervasyon oluşturur ve sonrasını yönetir: güncel durumu alma, iptal uygunluğunu kontrol etme ve iptal etme.

Sipariş Oluştur

Bir arama teklifinden transfer rezervasyonu oluşturur. Sipariş pendingPayment durumunda başlar; yanıt, ödeme adımında ödenecek tam tutarı içerir.

Endpoint

POST /transfer/orders

Kimlik Doğrulama

Bu endpoint kimlik doğrulama gerektirir. Authorization başlığında JWT erişim jetonunuzu ekleyin:

Authorization: Bearer ERIŞIM_JETONUNUZ

Son Kullanıcı IP Adresi

Entegre acente sistemleri, son kullanıcının IP adresini X-Forwarded-For başlığı ile iletmelidir. Bu bilgi denetim ve güvenlik amaçları için gereklidir.

İstek Gövdesi

AlanTürGerekliAçıklama
searchIdstringEvetTransfer aramasından gelen arama kimliği
codestringEvetArama sonuçlarından seçilen teklif kodu
passengersarrayEvetYolcu listesi; tam olarak bir yolcu primary: true olmalı
billingobjectHayırÖzel fatura bilgileri (aşağıdaki Fatura bölümüne bakın)
flightNumberstringHayırGidiş alışı için uçuş numarası (havalimanı alışlarında şiddetle tavsiye edilir)
returnFlightNumberstringHayırDönüş alışı için uçuş numarası (gidiş-dönüşlerde)

Uçuş Numarası (Şiddetle Tavsiye Edilir)

Alış bir havalimanındaysa flightNumber gönderin. Tedarikçiler bu bilgiyle uçağın gerçek varış saatini takip eder ve rötarlarda alışı ayarlar; verilmezse sürücü yalnızca planlanan saatte bekler.

Yolcular

Tam olarak bir yolcu primary: true olarak işaretlenmelidir; bu, yolculuğun iletişim yolcusudur. Her yolcunun bir adı ve tam olarak bir kimlik belgesi (identityNumber veya passportNo) olmalıdır. Kalan alanlar yalnızca birincil yolcu için zorunludur.

AlanTürGerekliAçıklama
primarybooleanEvetİletişim yolcusu işareti. Tam olarak biri true olmalı
firstNamestringEvetYolcu adı
lastNamestringEvetYolcu soyadı
genderstringYalnız birincilM veya F
birthDatestringYalnız birincilDoğum tarihi (YYYY-MM-DD formatı)
nationalitystringYalnız birincilISO ülke kodu (2 karakter)
emailstringYalnız birincilGeçerli e-posta adresi
phonestringYalnız birincilE.164 formatında telefon numarası
identityNumberstringİkisinden biri11 haneli kimlik numarası (Türk vatandaşları için)
passportNostringİkisinden biriPasaport numarası (uluslararası yolcular için)

Fatura

billing isteğe bağlıdır. Gönderilmediğinde fatura, organizasyonunuzun kayıtlı fatura adresine kesilir; organizasyon için kayıtlı fatura adresi yoksa istek 5003 hatasıyla reddedilir.

billing göndermek için acenteniz adına özel fatura (custom billing) yetkisinin açık olması gerekir. Bu yetki yoksa fatura nesnesi geçerli olsa bile istek 5004 hatasıyla reddedilir. Özel fatura yetkisi için Yolcu360 ile iletişime geçin.

Gönderildiğinde transfer faturası araç kiralama faturasından daha katıdır: taxIdentifier ve zipCode her zaman zorunludur (bireysel faturada kimlik numarasını kullanın) ve line en az 5 karakter olmalıdır.

AlanTürGerekliAçıklama
typestringEvetAdres tipi: individual, privateCompany veya corporateCompany
firstNamestringEvetFatura adı (corporateCompany için şirket adı)
lastNamestringKoşulluFatura soyadı. Tip corporateCompany değilse zorunlu
emailstringEvetFatura e-posta adresi
phonestringEvetE.164 formatında fatura telefonu
countryCodestringEvetISO ülke kodu (2 karakter)
countryNamestringEvetTam ülke adı
adm1stringEvet1. seviye idari bölge (il)
adm2stringHayır2. seviye idari bölge (ilçe)
linestringEvetAdres satırı (en az 5 karakter)
zipCodestringEvetPosta kodu
taxIdentifierstringEvetVergi numarası (bireysel için kimlik numarası)
taxDivisionstringŞirket tipleriVergi dairesi. privateCompany ve corporateCompany için zorunlu

Örnek İstek

curl -X POST https://api.pro.yolcu360.com/api/v1/transfer/orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ERIŞIM_JETONUNUZ" \
  -H "X-Forwarded-For: 203.0.113.195" \
  -d '{
    "searchId": "0ba0fea9-1e98-43ce-a69b-e895e2bc68a6",
    "code": "9972a93a-707e-403e-928e-cbb68a65584f",
    "flightNumber": "TK2021",
    "passengers": [
      {
        "primary": true,
        "firstName": "John",
        "lastName": "Doe",
        "gender": "M",
        "birthDate": "1990-01-15",
        "nationality": "US",
        "passportNo": "AB1234567",
        "email": "john.doe@example.com",
        "phone": "+905551234567"
      },
      {
        "primary": false,
        "firstName": "Jane",
        "lastName": "Doe",
        "identityNumber": "11111111110"
      }
    ],
    "billing": {
      "type": "individual",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "phone": "+905551234567",
      "countryCode": "TR",
      "countryName": "Turkey",
      "adm1": "Istanbul",
      "adm2": "Beyoglu",
      "line": "Kocatepe Mah. Taksim Square No:1",
      "zipCode": "34437",
      "taxIdentifier": "11111111110"
    }
  }'

Yanıt

Başarılı Yanıt (201 Created):

Yanıt siparişin kendisidir; sipariş detayı ve ödeme yanıtıyla aynı şekildedir. product burada kısaltılmıştır; yapısı aşağıdaki sipariş detayındakiyle aynıdır.

{
  "orderId": "YLPB_0503",
  "status": "pendingPayment",
  "paymentRequirement": {
    "amount": 145200,
    "currency": "TRY"
  },
  "flightNumber": "TK2021",
  "product": {
    "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
    },
    "vehicle": {"name": "Minivan", "seatCount": 6, "baggageCount": 6},
    "pricing": {"currency": "TRY", "total": {"amount": 145200, "currency": "TRY"}},
    "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."}
    ]
  },
  "passengers": [
    {"primary": true, "firstName": "John", "lastName": "Doe", "gender": "M", "birthDate": "1990-01-15", "nationality": "US", "passportNo": "AB1234567", "email": "john.doe@example.com", "phone": "+905551234567"},
    {"primary": false, "firstName": "Jane", "lastName": "Doe", "identityNumber": "11111111110"}
  ]
}

Yanıt Alanları

AlanTürAçıklama
orderIdstringTransfer sipariş kimliği (YLPB_xxxx). Sonraki tüm transfer çağrılarında bunu kullanın
statusstringSipariş yaşam döngüsü durumu; oluşturmanın hemen ardından her zaman pendingPayment
paymentRequirementobjectÖdeme adımında ödenecek tam tutar, en küçük para biriminde. Yalnızca oluşturma yanıtında döner
flightNumberstringİstekte verilen uçuş numarası
returnFlightNumberstringİstekte verilen dönüş uçuş numarası (gidiş-dönüşlerde)
productobjectRezerve edilen teklif, arama yanıtındaki ürünle aynı yapıda
passengersarrayİstekte verilen yolcu bilgileri

Sipariş artık pendingPayment durumundadır ve ödeme gelmezse oluşturmadan yaklaşık bir saat sonra sona erer. Transfer Ödemesi ile devam edin.

Sipariş Detayı Al

Bir transfer siparişinin güncel durumunu alır: yaşam döngüsü durumu, rezerve edilen ürün ve yolcular.

Endpoint

GET /transfer/orders/{orderId}

Kimlik Doğrulama

Bu endpoint kimlik doğrulama gerektirir. Authorization başlığında JWT erişim jetonunuzu ekleyin.

Yol Parametreleri

ParametreTürGerekliAçıklama
orderIdstringEvetTransfer sipariş kimliği

Örnek İstek

curl -X GET https://api.pro.yolcu360.com/api/v1/transfer/orders/YLPB_0503 \
  -H "Authorization: Bearer ERIŞIM_JETONUNUZ"

Yanıt

Başarılı Yanıt (200 OK):

{
  "orderId": "YLPB_0503",
  "status": "reserved",
  "vendorReservationId": "227699",
  "flightNumber": "TK2021",
  "product": {
    "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."
      }
    ]
  },
  "passengers": [
    {
      "primary": true,
      "firstName": "John",
      "lastName": "Doe",
      "gender": "M",
      "birthDate": "1990-01-15",
      "nationality": "US",
      "passportNo": "AB1234567",
      "email": "john.doe@example.com",
      "phone": "+905551234567"
    },
    {
      "primary": false,
      "firstName": "Jane",
      "lastName": "Doe",
      "identityNumber": "11111111110"
    }
  ]
}

Yanıt Alanları

AlanTürAçıklama
orderIdstringTransfer sipariş kimliği
statusstringSipariş yaşam döngüsü durumu (aşağıdaki tabloya bakın)
vendorReservationIdstringTedarikçi rezervasyon referansı. Sipariş reserved olduktan sonra döner; pendingPayment'ta alan yoktur
flightNumberstringSipariş oluşturmada verilen uçuş numarası
returnFlightNumberstringSipariş oluşturmada verilen dönüş uçuş numarası (gidiş-dönüşlerde)
productobjectRezerve edilen teklif, arama yanıtındaki ürünle aynı yapıda
passengersarraySipariş oluşturmada verilen yolcu bilgileri

Sipariş Durumu Değerleri

DurumAçıklama
pendingPaymentSipariş oluşturuldu, ödeme bekleniyor. Ödenmezse yaklaşık bir saat sonra sona erer
reservedÖdeme tamamlandı ve transfer tedarikçi ile onaylandı
canceledSipariş acente veya tedarikçi tarafından iptal edildi
expiredSipariş zamanında ödenmedi ve otomatik olarak sona erdi
failedRezervasyon tamamlanamadı

Durum Takibi Tavsiyesi

Ödeme yanıtı, tahsilat sonrası geri okunan güncel siparişi zaten taşır; ödemeden sonra ayrıca detay çağrısı gerekmez. Bu endpoint'i siparişi sonradan yeniden kontrol etmek için kullanın: reserved bir sipariş sonradan da düşebilir (örneğin tedarikçi tarafı iptal); bu nedenle alış saatinden önce durumu yeniden kontrol etmeniz önerilir.

vendorReservationId reserved durumundan itibaren mevcuttur ve iptal sonrasında da siparişte kalır. Tedarikçi tarafında sonradan düşen siparişte eksik olabilir.

İptal Uygunluğunu Kontrol Et

Siparişin iptal edilip edilemeyeceğini ve ne kadar iade yapılacağını kontrol eder. Bu endpoint siparişi değiştirmez.

Endpoint

POST /transfer/orders/{orderId}/cancel_eligibility

Kimlik Doğrulama

Bu endpoint kimlik doğrulama gerektirir. Authorization başlığında JWT erişim jetonunuzu ekleyin.

Yol Parametreleri

ParametreTürGerekliAçıklama
orderIdstringEvetKontrol edilecek siparişin kimliği

Örnek İstek

curl -X POST https://api.pro.yolcu360.com/api/v1/transfer/orders/YLPB_0503/cancel_eligibility \
  -H "Authorization: Bearer ERIŞIM_JETONUNUZ"

Yanıt

Başarılı Yanıt (200 OK):

{
  "orderId": "YLPB_0503",
  "cancellable": true,
  "refundAmount": {
    "amount": 145200,
    "currency": "TRY"
  }
}

Yanıt Alanları

AlanTürAçıklama
orderIdstringTransfer sipariş kimliği
cancellablebooleanSiparişin şu anda iptal edilip edilemeyeceği
refundAmountobjectSipariş şimdi iptal edilirse iade edilecek tutar, en küçük para biriminde. Uygulanamadığında dönmez

refundAmount, varsa iptal cezası uygulanmış hâlidir (teklifin cancellationPolicies alanına bakın) ve fiilen ödenen tutarla sınırlıdır. Transfer uygunluk yanıtının araç kiralamadakinden daha zengin olduğunu unutmayın: refundable bayrağı yerine somut iade tutarını döndürür.

Siparişi İptal Et

Bir transfer siparişini iptal eder. İptal tedarikçiye iletilir; 200 yanıtı yalnızca tedarikçi iptali kabul ettiğinde döner. İade, kredi limitinize otomatik olarak yapılır.

Endpoint

POST /transfer/orders/{orderId}/cancel

Kimlik Doğrulama

Bu endpoint kimlik doğrulama gerektirir. Authorization başlığında JWT erişim jetonunuzu ekleyin.

Yol Parametreleri

ParametreTürGerekliAçıklama
orderIdstringEvetİptal edilecek siparişin kimliği

Örnek İstek

curl -X POST https://api.pro.yolcu360.com/api/v1/transfer/orders/YLPB_0503/cancel \
  -H "Authorization: Bearer ERIŞIM_JETONUNUZ"

Yanıt

Başarılı Yanıt (200 OK):

{
  "orderId": "YLPB_0503",
  "status": "canceled"
}

Tedarikçi iptali reddederse veya sipariş iptal edilebilir bir durumda değilse (örneğin zaten iptal edilmişse) endpoint 8012 hatası döndürür:

{
  "code": 8012,
  "description": "Transfer order cannot be canceled",
  "details": {
    "orderId": "YLPB_0503",
    "status": "canceled"
  }
}

Sürprizlerden kaçınmak için iptalden önce yukarıdaki iptal uygunluğu endpoint'ini çağırın ve 8012 hatasını yeniden denenebilir bir durum olarak görmeyin: iptal gerekli olduğu hâlde sürekli başarısız oluyorsa destek ile iletişime geçin.

Search

Payment