Fiyat ve rezervasyon

Akış

1. POST /quotes — yolculuğu tarif edin, teklifleri alın (her araç tipi için bir teklif).
2. Teklifleri müşterinize gösterin. Her teklif 30 dakika geçerlidir (expires_at).
3. POST /bookings — seçilen offer_id değerini yolcu bilgileriyle gönderin.
4. Bizim reference numaramızı saklayın, rezervasyonu bildirimlerle ya da GET /bookings/{reference} ile takip edin.

Teklifteki fiyat rezervasyonun fiyatıdır: teklifler imzalıdır, fiyat sorgu ile rezervasyon arasında değişemez.

Yerler

from ve to üç biçimden birini alır:

Havalimanı için iata tercih edin. Otel ve adreslerde kendi adres aracınızdan (Google Places vb.) lat + lng + address gönderin: fiyat hizmet bölgelerimizden gelir, bölge içindeki her nokta kayıtlı bir otel gibi fiyatlanır. GET /locations test ve canlıda aynı listedir, otel rehberi değildir; otel adına boş sonuç gelmesi normaldir.

Uçuştan alış saati

Yolcular çoğu zaman uçuş numarasını bilir ama doğru alış saatini bilmez. POST /flights/pickup-time uçuşu bulur ve alış saatini önerir:

POST /flights/pickup-time
{
  "flight_number": "TK1937",
  "date": "2026-11-20",
  "from": { "lat": 41.0369, "lng": 28.9850, "address": "Taksim Meydanı, İstanbul" },
  "to": { "iata": "IST" }
}

{
  "data": {
    "flight_number": "TK1937", "airline": "Turkish Airlines",
    "departure": { "airport": "IST", "scheduled_at": "2026-11-20T07:40", "terminal": "1" },
    "arrival": { "airport": "BRU", "scheduled_at": "2026-11-20T10:10", "terminal": null },
    "domestic": false, "trip": "to_airport", "airport_match": true,
    "airport_before_minutes": 180, "drive_minutes": 50, "rush_minutes": 0,
    "suggested_pickup_at": "2026-11-20T03:50"
  }
}

• Havalimanına (trip: to_airport): yolcu dış hatta kalkıştan 3 saat, iç hatta 1,5 saat önce havalimanında olacak şekilde en geç alış; yol süresi ve yoğun saat payı dahil. Erken uçuşlarda saat önceki güne düşebilir.
• Havalimanından (trip: from_airport): iniş saati.
• Bütün saatler yereldir. airport_match: false, uçuşun bu transferin havalimanını kullanmadığını gösterir; uçuş numarasını kontrol edin.
• Uçuş bulunduğu halde alış saati önerilemiyorsa suggested_pickup_at null olur: uçuş bu transferin havalimanını kullanmıyordur (airport_match: false) ya da transfer havalimanında başlamıyor / bitmiyordur (trip: null).
• Hatalar: 404 flight_not_found (o tarihte böyle bir uçuş yok), 503 flight_data_unavailable. Yalnız yardımcıdır: önerilen saati POST /quotes isteğinizde kullanın.

Transfer fiyatı

POST /quotes
{
  "service": "transfer",
  "from": { "iata": "AYT" },
  "to": { "address": "Rixos Premium Belek", "lat": 36.8571, "lng": 31.0418, "country": "TR" },
  "date": "2026-11-20",
  "time": "14:30",
  "passengers": { "adults": 2, "children": 1, "infants": 0 },
  "luggage": 3
}

• date ve time alış yerinin yerel saatidir. Havalimanından alışta planlanan iniş saatini gönderin; şoför uçuşu takip eder.
• passengers.adults 1–99 arasıdır. Çocuk ve bebekler araç kapasitesine sayılır.
• Tarih bugünden 400 gün sonrasına kadar olabilir.

{
  "data": {
    "service": "transfer",
    "currency": "EUR",
    "distance_km": 34.8,
    "timezone": "Europe/Istanbul",
    "out_of_service_area": false,
    "offers": [
      {
        "offer_id": "of_eyJ2Ijo…",
        "vehicle_type": { "id": 2, "code": "MINIVAN", "name": "Minivan", "max_passengers": 6, "max_luggage": 6 },
        "price": 54.0,
        "currency": "EUR",
        "confirmation": "instant",
        "free_cancellation_hours": 24,
        "expires_at": "2026-11-01T09:30:00+00:00"
      }
    ]
  }
}

Teklifler fiyata göre sıralıdır. Boş offers listesi yolculuğa hizmet veremediğimiz anlamına gelir — sonuç bekliyorduysanız bize yazın.

Saatlik şoförlü araç fiyatı

POST /quotes
{ "service": "hourly", "from": { "iata": "IST" }, "date": "2026-11-20", "time": "09:00", "hours": 4, "passengers": { "adults": 2 } }

hours 1–48 arasıdır. to kullanılmaz.

Rezervasyon

POST /bookings
Idempotency-Key: order-10045

{
  "items": [
    { "offer_id": "of_eyJ2Ijo…", "flight_number": "TK2412", "note": "3 yaşında çocuk için koltuk" }
  ],
  "lead_passenger": { "name": "Anna Peeters", "phone": "+32 470 12 34 56", "email": "anna@example.com" },
  "passengers": [ { "name": "Tom Peeters", "type": "adult" }, { "name": "Lise Peeters", "type": "child" } ],
  "reference": "ORDER-10045",
  "note": "VIP müşteri"
}

• Bir rezervasyonda en fazla 10 items (transfer / saatlik) ve 10 services (havalimanı hizmeti) — örneğin geliş ve dönüş transferi birlikte.
• lead_passenger.name zorunludur. Cep telefonu şoförün yolcuya ulaşmasını sağlar; lütfen her zaman gönderin.
• Havalimanından alışlarda flight_number (örneğin TK2412) şiddetle önerilir.
• reference sizin kendi numaranızdır (en çok 80 karakter). Rezervasyon yanıtlarında customer_reference olarak döner (bizim numaramız reference, örneğin PXT-01234). GET /bookings?reference= ile arayabilirsiniz.
• GET /bookings şirket hesabınızın bütün rezervasyonlarını listeler: anahtarlarınızdan herhangi biriyle API'den yapılanlar ve şirketiniz için müşteri portalından ya da operasyon ekibimizce açılanlar.
• Her zaman Idempotency-Key gönderin; bkz. Hatalar ve sınırlar.

Cevap (201 Created) rezervasyondur:

{
  "data": {
    "reference": "PXT-01234",
    "status": "confirmed",
    "customer_reference": "ORDER-10045",
    "currency": "EUR",
    "total": 54.0,
    "paid": 0.0,
    "payment_url": null,
    "lead_passenger": { "name": "Anna Peeters", "phone": "+32 470 12 34 56", "email": "anna@example.com" },
    "items": [
      {
        "id": 1, "type": "transfer", "status": "scheduled",
        "pickup_at": "2026-11-20T14:30", "timezone": "Europe/Istanbul",
        "from": { "iata": "AYT", "name": "Antalya Airport" },
        "to": { "name": "Rixos Premium Belek", "lat": 36.8571, "lng": 31.0418 },
        "vehicle_type": { "id": 2, "code": "MINIVAN", "name": "Minivan" },
        "passengers": { "adults": 2, "children": 1, "infants": 0 },
        "luggage": 3, "flight_number": "TK2412", "price": 54.0, "driver": null
      }
    ],
    "cancellation": { "fee_if_cancelled_now": 0.0 },
    "created_at": "2026-11-01T09:05:12+00:00"
  }
}

Teklif hataları

Yalnız anında onay (B2C)

Son yolcuya satış (B2C) yapıyorsanız genellikle "onay bekliyor" gösteremezsiniz. Her rezervasyonun anında onaylanmasını sağlamanın iki yolu var:

• İstek başına: POST /quotes ve POST /bookings isteğinde "instant_only": true gönderin. Fiyat sorgusu yalnız confirmation: instant teklifleri döner (yanıtta "instant_only": true).
• Bütün hesap için: hesabınızı yalnız anında onay olarak ayarlamamızı isteyin; instant_only her zaman açık olur, sizde on_request / offered rezervasyon hiç oluşmaz.

POST /bookings
{ "items": [{ "offer_id": "of_…" }], "lead_passenger": { "name": "Jane Smith" }, "instant_only": true }

Rezervasyon anında onaylanamıyorsa hiçbir şey oluşturulmaz, 409 not_instant ve error.details.reason döner:

Kartla ödeyen hesaplarda kontrol ödeme alınmadan önce yapılır; yolcu onaylanmamış bir rezervasyon için ödeme yapmaz.

Kartla ödeme

Hesabınız rezervasyon başına kartla ödüyorsa yeni rezervasyon pending_payment durumunda ve bir payment_url ile döner. Yolcuyu (ya da kendi ödeme adımınızı) bu güvenli sayfaya yönlendirin. Ödeme tamamlanınca rezervasyon confirmed olur ve booking.updated bildirimi gelir. Ödenmemiş rezervasyonlar gerçekleştirilmez.

Aylık faturayla çalışan hesaplar pending_payment durumunu hiç görmez.

Sandbox'ta payment_url bir test ödeme sayfası açar: Ödemeyi tamamla (test) düğmesine basınca rezervasyon canlıdaki gibi confirmed olur (bildirim dahil). Aynı sonucu POST /test/bookings/{reference}/simulate ile {"event": "payment_completed"} göndererek de alabilirsiniz.

İptal

curl -X POST https://paxvelhub.com/api/v1/bookings/PXT-01234/cancel \
  -H "Authorization: Bearer $PAXVEL_KEY" -H "Content-Type: application/json" \
  -d '{ "reason": "Yolcu seyahati iptal etti" }'

Rezervasyonun tamamı iptal edilir. Ücretsiz iptal süresi içinde iptal edilen kalemler ücretsizdir; daha geç iptaller iptal kurallarınıza göre ücretlendirilir — kalem başına cancellation_fee ve total alanında görünür. İptal etmeden önce beklenen ücreti GET /bookings/{reference} cevabındaki cancellation.fee_if_cancelled_now alanından okuyabilirsiniz.

Rezervasyonu değiştirmek için (saat, adres, yolcu) ücretsiz iptal süresindeyken iptal edip yeniden rezerve edin; daha sonraki değişiklikler için Sorular bölümünden yazın.