Rezervasyon yaşam döngüsü

Oluşturma yanıtındaki transferReservationId bir UUID'dir; detay, güncelleme ve iptalde bu kimliği kullanın. PNR kullanıcıya gösterilen takip kodudur. Çift yönde returnReservationId ile dönüşü ayrı takip edin.

Listeleme ve sayfalama

curl 'https://test-api.yolcugo.com/api/booking?year=2030&month=6&dateFilter=upcoming&page=1&pageSize=50' \
  --header 'Authorization: Bearer ACCESS_TOKEN'

GET /api/booking ve GET /api/booking/user giriş yapan kullanıcının kayıtlarını listeler. Bunları tüm şirket kayıtlarının dökümü olarak değerlendirmeyin.

Parametre	Davranış
year	Alış tarihinin yılı; tek başına kullanılabilir.
month	Yılla birlikte gönderin; 1–12. Takvim filtreleri Türkiye saatine göre uygulanır.
dateFilter=all	Varsayılan; ek zaman/durum filtresi yok.
dateFilter=upcoming	Alış zamanı şimdi veya sonrasında; tarih artan sıralanır.
dateFilter=past	Alış zamanı geçmiş; tarih azalan sıralanır.
dateFilter=today	Türkiye takviminde bugünkü alışlar.
dateFilter=active	Durumu 7, 8 veya 9 olanlar; tarih artan sıralanır.
page	İlk sayfa 1.
pageSize	Varsayılan ve üst sınır 200; geçerli bir pozitif değer gönderin.

Filtre değerlerini küçük harfle gönderin. Yanıt data içinde bir dizidir; totalCount, hasMore veya cursor beklemeyin. Bir sayfa seçtiğiniz boyuttan az kayıt içerene kadar page değerini artırın. Okuma sırasında yeni kayıtlar ve güncellemeler olabileceğinden kimlikle tekilleştirin; sayfaları değişmez bir anlık görüntü gibi kullanmayın. Bilinen bir rezervasyonun güncel bilgisi için detay çağrısını kullanın.

Durumların anlamı

Güncel isimleri durum kataloğundan alın. status değerini iş mantığında, durum metnini gösterimde kullanın.

Kod	Anlamı
1	Yeni transfer
2	Tedarikçi ataması bekliyor
3	Tedarikçi onayı bekliyor
4	Konfirme edildi
5	Konfirme edilmedi
6	Sürücü ataması bekliyor
7	Seyahate hazır; sürücü atandı
8	Sürücü alış noktasına doğru yola çıktı
9	Yolcu alındı
10	Yolcu bırakıldı
11	İptal edildi
12	Tamamlandı

Her rezervasyon bütün durumları sırasıyla geçmek zorunda değildir. 200 ile rezervasyon oluşturulması, sürücünün atandığı veya transferin tamamlandığı anlamına gelmez. Partner referansında genel durum değiştirme işlemi bulunmaz; operasyon ilerlemesini sorgulama veya webhook ile takip edin.

Durum 1–7 için güncelleme/iptal durum açısından mümkün olabilir; yetki, tedarikçi ve grup kuralları ayrıca uygulanır. Durum 8–12 için partner güncelleme ve iptal işlemleri reddedilir. Ekranda butonu kapatmak yeterli değildir; sunucunun işlem anındaki yanıtını da değerlendirin.

Kısmi güncelleme

Güncelleme endpoint'i PUT kullanır ancak aşağıdaki alanların kısmi güncelleme davranışı vardır:

Alan	Gönderilmedi / null / boş	Değer gönderildi
pickUpTime	Mevcut zamanı korur.	Tam ISO 8601 zamanına günceller.
flightNo	Mevcut uçuşu korur.	Uçuşu değiştirir; en fazla 20 karakter.
note	Mevcut notu korur.	Notu değiştirir; en fazla 500 karakter.
passengerRequests	Gönderilmezse, null veya boş diziyse mevcut liste korunur.	Tam istenen yolcu listesini gönderin; yalnız değişen yolcuyu göndermeyin.

Uçuşu silmek için clearFlightNo: true, notu silmek için clearNote: true kullanın. Temizleme bayrağı aynı istekte gönderilen yeni değere göre önceliklidir.

curl --request PUT \
  'https://test-api.yolcugo.com/api/booking/RESERVATION_ID' \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "pickUpTime": "2030-06-15T13:00:00+03:00",
    "clearFlightNo": false,
    "note": "Yeni buluşma noktası: ana giriş",
    "clearNote": false
  }'

Yeni istemciler yalnız saat (HH:mm) yerine açık saat dilimli tam tarih göndermelidir. Yolcu güncelliyorsanız mevcut yolcuların passengerId değerlerini detay yanıtından taşıyın, tam bir lider yolcu ve kapasite kurallarını koruyun. Güncelleme yetkisi rezervasyonu oluşturan kullanıcıyla sınırlandırılmıştır.

Bu işlem araç, tedarikçi, alış/bırakış konumu, rota, ara durak, ekstra veya fiyat değiştirme endpoint'i değildir. Dış tedarikçi değişikliği reddedebilir; gruba birleştirilmiş kayıt için önce destekle görüşmek gerekebilir. Başarıdan sonra dönen kaydı yeniden gösterin; başarısız isteği istemcide olmuş gibi kaydetmeyin.

İptal ve sonuç kontrolü

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

Bu çağrı iptali gerçekleştirir; ön fiyatlama veya iptal ücreti sorgusu değildir. Başarılı yanıtta data kesinti yüzdesidir: 0 kesintisiz, 25 yüzde 25, 100 yüzde 100 kesinti demektir. Bu değer para tutarı veya bankaya iadenin tamamlandığına dair bir onay değildir.

İptal öncesinde teklifin koşullarını gösterin. Her partner rezervasyonunda aynı ücretsiz iptal penceresi varmış gibi davranmayın. Dış tedarikçi koşulları ve hesap politikası belirleyicidir. İşlem yetkisi bulunmalı ve kayıt hesabın erişim kapsamında olmalıdır.

Çift yön için her bacakta ayrı iptal çağrısı yapın ve iki sonucu ayrı takip edin. İlk bacak iptal olup diğeri başarısız olabilir. Aynı iptali tekrar çağırmak başarı dönecek diye varsaymayın; ağ hatasından sonra önce detayı okuyup status: 11 olup olmadığını kontrol edin.

Operasyonel uyarılar ve eşitleme

operationalAttention: true veya dolu serviceIssueCode varsa işlemi yalnızca durum kodundan sorunsuz kabul etmeyin; bilgiyi operasyon ekibinize gösterin ve support@yolcugo.com ile paylaşın.

Önerilen yaklaşım, webhook ile değişikliği öğrenmek ve gerekirse detayı yeniden okumaktır. Webhook kullanmıyorsanız ilgilendiğiniz rezervasyonları aralıklı sorgulayın; başarısızlıklarda beklemeyi artırın ve gereksiz sık döngü kurmayın. Terminal kayıtlar için sürekli sorgulamayı durdurun. Periyodik liste mutabakatı kaçırılan bildirimleri yakalamanıza yardımcı olur.