İ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.
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"
}'
itemIdyerine 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ı
customerReferencealanında gönderebilirsiniz (en çok 100 karakter). Numara rezervasyon detayında (GET /api/booking/{id}) ve webhookdata.customerReferencealanı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ı numarareturnLeg.customerReferenceile 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 karakteri400döner. Liste uçları (GET /api/bookingve benzerleri) bu alanı her zamannulldöndürür; numarayı detaydan veya webhook'tan okuyun. AynıIdempotency-Keyile yapılan tekrar gönderim numarayı değiştirmez; değiştirmek içinPUT /api/booking/{id}kullanın. - Örnekteki
Idempotency-Keyyerine 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:
| Alan | Kullanımı |
|---|---|
data.transferReservationId | Detay, güncelleme ve iptal işlemlerindeki id |
data.pnr | Rezervasyon takip kodu |
data.failedWaypoints | Eklenemeyen 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.