Ana içeriğe geç

İlk rezervasyon

Önce oturum açın. Aşağıdaki çağrılar aynı test hesabının erişim token'ıyla yapılmalıdır.

1. Müsait araçları sorgulayın​

curl 'https://test-api.yolcugo.com/api/availability' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--header 'Accept-Language: tr-TR' \
--header 'X-Currency: TRY' \
--data '{
"requestId": "d90a6d8b-4717-4c50-b38c-9e81d06d952f",
"bestPrice": true,
"pickUpDateTime": "2030-06-15T12:00:00+03:00",
"hour": 0,
"pickUpLocation": {
"name": "İstanbul Havalimanı",
"latitude": 41.2611,
"longitude": 28.7419,
"isAirport": true
},
"dropOffLocation": {
"name": "Taksim Meydanı",
"latitude": 41.0369,
"longitude": 28.9850
}
}'

Her arama için yeni requestId üretin ve alış tarihini senaryonuza göre değiştirin. Örnekteki +03:00 Türkiye'deki alış içindir; başka ülkedeki alışta Z, o noktanın offset'i ya da yerel saati taşıyan pickUpLocalDateTime kullanın (tarih ve saat kuralları).

Partner hesabıyla alış zamanı en erken arama anından 6 saat sonrası olabilir; daha yakın bir alış için arama 400 doğrulama hatası döner. Müsaitlik yanıtındaki data.vehicles içinden uygun aracı seçin. itemId değerini, fiyatı ve hizmet koşullarını birlikte alın. Örnekteki adresler ve kişiler sentetiktir. Aracın seat ve baggage kapasitesini yolculuk ihtiyacınızla karşılaştırın; fiyatı tek seçim ölçütü olarak kullanmayın.

not

Araç listesi boşsa rezervasyon oluşturmayın. Rota, tarih veya hesabınızın kapsamı için uygun teklif bulunmamış olabilir.

2. Ekstra ve rota seçimini tamamlayın​

Standart tedarikçi ekstraları için teklifin supplierId değeriyle ekstra listesini alın; seçilen kimlikleri supplierExtraIds alanında gönderin.

Dış tedarikçi teklifi kullanıyorsanız externalExtras ve serviceConditions alanlarını inceleyin. Ekstraları yeniden fiyatladıktan sonra dönen teklifin itemId ve fiyatlarını kullanın.

Ara durak, çift yön, saatlik kiralama veya dış tedarikçi kullanıyorsanız ileri rezervasyon rehberindeki koşullu alanları tamamlayın. Ara duraklar rezervasyon öncesinde arama isteğinde de bulunmalıdır.

Alternatif rota için rota seçeneklerini alın. Rezervasyona seçilen seçeneğin teklif anahtarıyla devam edin.

Teklifler sınırlı süre geçerlidir; mevcut araç teklif süresi 30 dakikadır. İşleme devam ederken sunucunun yanıtını esas alın. 410 alırsanız yeniden arayın; eski teklifle devam etmeyin.

3. Rezervasyonu oluşturun​

curl 'https://test-api.yolcugo.com/api/booking' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: 88709931-780b-4a11-ae3d-d1d370263de5' \
--header 'Accept-Language: tr-TR' \
--header 'X-Currency: TRY' \
--data '{
"itemId": "SECILEN_TEKLIF_ITEM_ID",
"passengerRequests": [
{
"firstName": "Demo",
"lastName": "Yolcu",
"phone": "+905000000000",
"email": "demo@example.com",
"isLeadPassenger": true
}
],
"note": "Dokümantasyon test rezervasyonu"
}'
  • itemId yerine bir önceki adımda seçilen teklif anahtarını yazın.
  • Aramada seçtiğiniz para birimi ve dili rezervasyon çağrısında da gönderin.
  • 1–46 yolcu kaydı gönderin; tam olarak bir lider yolcu belirtin. Toplam kişi sayısı kayıt sayısından farklıysa passengerCount (1–46) gönderin; seçilen araç kapasitesini aşmayın.
  • Lider yolcunun telefonu zorunludur. Dış teklifte uluslararası telefon, havalimanı bacağı için uçuş numarası ve güncel koşulların kabulü gerekir. E-posta opsiyoneldir; gönderiliyorsa geçerli olmalıdır.
  • Kendi sisteminizdeki rezervasyon numarasını isteğe bağlı customerReference alanında gönderebilirsiniz (en çok 100 karakter). Numara rezervasyon detayında (GET /api/booking/{id}) ve webhook data.customerReference alanında döner; operasyon ekibi rezervasyonu bu numarayla bulur. Numarayı yalnız siz ve YolcuGo operasyonu görürsünüz; transferi yapan tedarikçiye gösterilmez. Tekil olması gerekmez; çift yönde dönüş bacağına da yazılır, dönüş için farklı numara returnLeg.customerReference ile gönderilir. Numaraya kişisel veri (yolcu adı, telefon) koymayın. Baştaki ve sondaki boşluk kırpılır; satır sonu veya kontrol karakteri 400 döner. Liste uçları (GET /api/booking ve benzerleri) bu alanı her zaman null döndürür; numarayı detaydan veya webhook'tan okuyun. Aynı Idempotency-Key ile yapılan tekrar gönderim numarayı değiştirmez; değiştirmek için PUT /api/booking/{id} kullanın.
  • Örnekteki Idempotency-Key yerine yeni bir anahtar üretin. Aynı isteği ağ hatası nedeniyle tekrarlarken aynı anahtarı koruyun. Yeni rezervasyon veya değişen rezervasyon niyeti için eski anahtarı kullanmayın.

Bu minimal örnek standart tek yön akışını gösterir. Dış tedarikçi tekliflerinde acceptedServiceConditionsVersion ve externalRequirementsAcknowledged gibi kabul alanlarını teklifin gerekliliklerine göre tamamlayın.

4. Sonucu saklayın ve sorgulayın​

Rezervasyon oluşturma başarılıysa HTTP 200 döner:

AlanKullanımı
data.transferReservationIdDetay, güncelleme ve iptal işlemlerindeki id
data.pnrRezervasyon takip kodu
data.failedWaypointsEklenemeyen ara duraklar; null veya boşsa sorun yok
data.returnReservationId / data.returnPnrÇift yön rezervasyonda dönüş bilgileri
curl 'https://test-api.yolcugo.com/api/booking/RESERVATION_ID' \
--header 'Authorization: Bearer ACCESS_TOKEN'

RESERVATION_ID yerine transferReservationId yazın. Burada PNR kullanılmaz. Başarı, kaydın oluştuğunu gösterir; tedarikçi/sürücü ataması ve seyahat durumu yaşam döngüsü rehberinde açıklanmıştır. Otomatik takip için webhook bağlantısı kurabilirsiniz.

5. İptal senaryosunu test edin​

İptal koşullarını kontrol ettikten sonra iptal işlemini çağırabilirsiniz:

curl --request POST \
'https://test-api.yolcugo.com/api/booking/RESERVATION_ID/cancel' \
--header 'Authorization: Bearer ACCESS_TOKEN'

Yanıttaki data bir kesinti yüzdesidir. 25 değeri yüzde 25 kesinti anlamına gelir; 25 TRY veya iade tutarı olarak yorumlamayın. Bu çağrı gerçek iptal yapar; yalnız ücret öğrenmek için kullanmayın.