Geliştiriciler için Tur API Dokümantasyonu

Başlarken

API, HTTPS üzerinden JSON dönen düz bir REST API’dir; erişiminiz onaylandıktan sonra kendiniz ürettiğiniz tek bir API key ile doğrulanır. Aşağıdaki örneklerde {BASE_URL} yer tutucu olarak kullanılıyor — kendi base URL’iniz geliştirici panelinde, key’inizin yanında yazar.

1
Başvurun
Platformunuzu anlatın. Her başvuruyu elle inceliyoruz, genellikle 1–2 iş günü içinde.
2
Key’inizi üretin
Onaydan sonra API key’inizi geliştirici panelinden oluşturun. Yalnızca bir kez gösterilir.
3
API’yi çağırın
Key’i her istekte X-API-Key header’ı olarak gönderin. Tüm el sıkışma bundan ibaret.

Kimlik doğrulama

Key’inizi her istekte X-API-Key header’ında gönderin. OAuth akışı, token değişimi ve son kullanma tarihi yok — key’i yenileyene ya da iptal edene kadar geçerli kalır.

curl

curl -X GET '{BASE_URL}/b2b/api/apiv2/b2c/tours/search?term=cappadocia&page_size=5' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Accept: application/json'

node

const res = await fetch(
  '{BASE_URL}/b2b/api/apiv2/b2c/tours/search',
  {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.TSB_API_KEY,
      'Content-Type': 'application/json',
      Accept: 'application/json',
    },
    body: JSON.stringify({ term: 'cappadocia', page_size: 5 }),
  },
)

const data = await res.json()

API’yi sunucunuzdan çağırın, asla tarayıcı kodundan — tarayıcıya gönderilen key artık herkese açıktır. Key’inizin yalnızca hash’lenmiş bir kopyasını sakladığımız için key tam olarak bir kez, oluşturduğunuz anda gösterilir. Kaybettiyseniz yenisini üretin; eskisi o anda geçersiz olur.

Rate limit ve kotalar

Birbirinden bağımsız iki limit var; ikisi de partner başına sayılır, kimseyle paylaşılmaz.

Dakikada 240 istek

Ani yüklenme limiti. Her yanıt X-RateLimit-Limit ve X-RateLimit-Remaining header’larını taşır; hızınızı ona göre ayarlayabilirsiniz.

Günde 20000 istek

Onayda verilen varsayılan günlük kota. UTC gece yarısı sıfırlanır; talep üzerine yükseltiyoruz — beklediğiniz hacmi söyleyin, ona göre ayarlayalım.

İki limitten birini aşmak 429 döndürür. Endpoint kırılımıyla güncel kullanımınızı geliştirici panelinizden görebilirsiniz.

İçerik kuralları

Yeni turlar 30 gün bekletilir. Kataloğumuza eklenen bir tur, 30 günlük olana kadar partner arama sonuçlarında ve tur detay yanıtlarında görünmez. Böylece tur önce kendi sitemizde indekslenir ve arama motorları asıl kaynağı doğru görür. Bundan eski her şey size tamamen açıktır.

Fiyat, tarih ve içerik her gün yeniden doğrulanır. İsterseniz yanıtları cache’leyin ama fiyat ve müsaitliği günde en az bir kez tazeleyin — ve rezervasyon oluşturmadan hemen önce müsaitliği mutlaka yeniden kontrol edin.

Tur arama ve içerik

Katalogda arama yapın ve turun tüm içeriğini çekin. Entegrasyonların çoğu bu endpoint’lerle başlar.

GET | POST/b2b/api/apiv2/b2c/tours/search

Tur arama

Filtreli tam katalog araması. Filtreleri query parametresi (GET) ya da JSON gövde (POST) olarak gönderin — dizi filtresi kullanmaya başlayınca POST önerilir.

Parametre	Tip	Açıklama
`term`	string	Tur başlıkları ve içeriğinde serbest metin araması.
`destination`	string	Aramayı sınırlayacak destinasyon slug’ı.
`category`	string	Tek bir kategori slug’ı.
`categories`	string[]	Aynı anda birden fazla kategori slug’ı.
`activities`	string[]	Aktivite slug’ları (activities endpoint’ine bakın).
`languages`	string[]	Rehberlik dili kodları.
`price`	[min, max]	İki elemanlı dizi olarak fiyat aralığı (EUR).
`duration`	[min, max]	Gün cinsinden süre aralığı (varsayılan 1–28).
`rating`	number	En düşük yorum puanı.
`start_location`	integer	Alış noktası location id’si.
`end_location`	integer	Bırakış noktası location id’si.
`transports`	string[]	Ulaşım tipi slug’ları.
`accommodations`	string[]	Konaklama tipi id’leri.
`physical_ratings`	integer[]	Fiziksel zorluk derecesi id’leri.
`ids`	integer[]	Sonucu belirli tur id’leriyle sınırlar.
`order`	string	Sıralama alanı. Varsayılan created_at.
`page`	integer	Sayfa numarası, 1’den başlar.
`page_size`	integer	Sayfa başına sonuç. Varsayılan 10.

Sonuçlar içerik ambargosuna tabidir — aşağıdaki İçerik kuralları bölümüne bakın.

GET/b2b/api/apiv2/b2c/tours/detail/{slug}

Tur detayı

Turun tüm kaydı: rota, dahil olanlar, görseller, hareket kuralları ve yorum özeti. {slug}, aramanın döndürdüğü tur slug’ıdır.

GET | POST/b2b/api/apiv1/b2c/quicksearch/tours

Hızlı tur arama

Arama kutuları için yazdıkça öneri. Tam aramayla aynı motor, kısa ve hızlı sorgular için ayarlı.

Parametre	Tip	Açıklama
`term`	string	Kullanıcının o ana kadar yazdığı metin.

Fiyat ve müsaitlik

Canlı fiyat ve hareket müsaitliği. Her yolun bir b2c bir de b2b karşılığı var: b2c perakende fiyatı, b2b sizin net (operatör) fiyatınızı döner.

GET/b2b/api/apiv2/b2c/availability/{slug}

Bir turun müsaitliği ve fiyatı

Tek bir turun hareket müsaitliği ve fiyatlaması. Net fiyat için /b2b/api/apiv2/b2b/availability/{slug} kullanın.

Parametre	Tip	Açıklama
`roomType`	string	sng, dbl veya trp. Varsayılan dbl.
`date`	YYYY-MM-DD	Tek bir hareket tarihi.
`startDate`	YYYY-MM-DD	Tarih aralığının başlangıcı.
`endDate`	YYYY-MM-DD	Tarih aralığının bitişi.
`pax`	integer	Yolcu sayısı.
`service_type`	string	Servis seviyesi. Varsayılan regular.
`rooms`	array	Oda dağılımı: [{ id, pax, count }].
`include_prices`	yes \| no	Fiyat kırılımını da döndürür.
`include_rooms`	yes \| no	Oda seçeneklerini de döndürür.

POST/b2b/api/apiv2/b2c/prices/{type}

Toplu fiyat

Bir id listesi için tur başına tek fiyat — liste ve kategori sayfalarının ihtiyacı budur. Net fiyat için b2b yolunu kullanın.

Parametre	Tip	Açıklama
`ids`zorunlu	integer[]	Fiyatlanacak tur id’leri.
`roomType`	string	sng, dbl veya trp. Varsayılan dbl.
`startDate`	YYYY-MM-DD	Varsayılan bugün.
`endDate`	YYYY-MM-DD	İsteğe bağlı aralık bitişi.

GET/b2b/api/apiv2/b2c/pricemonths/{type}/{id}

Aylık fiyat takvimi

Bir tur için ay başına en ucuz fiyat — “Mayıs’ta €X’ten başlayan” takvimi için. Net fiyat için b2b karşılığı mevcut.

Destinasyonlar ve sınıflandırma

Filtrelerin, menülerin ve arama kutularının arkasındaki referans veri.

GET/b2b/api/apiv1/b2c/countries/list

Ülkeler

Tüm ülkeler; id, ad, slug ve telefon koduyla birlikte.

GET/b2b/api/apiv1/b2c/quicksearch/locations

Lokasyon arama

Destinasyonları ada göre arayın — şehir, bölge ve ülke.

Parametre	Tip	Açıklama
`q`	string	Arama terimi.
`ids`	string	Virgülle ayrılmış id’ler: arama yerine bilinen lokasyonları çözmek için.
`limit`	integer	En fazla sonuç, 1–50. Varsayılan 20.

GET/b2b/api/apiv1/location-parents/{id}

Lokasyonun üst zinciri

Bir lokasyonun üst zinciri (şehir → bölge → ülke); breadcrumb için.

GET/b2b/api/apiv1/b2c/quicksearch/tour-categories

Tur kategorileri

Terimle eşleşen kategori sayfaları; başlık ve URL’leriyle.

Parametre	Tip	Açıklama
`term`	string	Arama terimi.

GET/b2b/api/apiv1/b2c/quicksearch/activities

Aktiviteler

Aktivite listesi (hiking, diving, …); id, ad ve slug ile — activities filtresinin kabul ettiği değerler.

Parametre	Tip	Açıklama
`term`	string	Arama terimi.

GET/b2b/api/apiv1/b2c/tours/available-destinations

Turu olan destinasyonlar

Şu an rezerve edilebilir turu bulunan destinasyonlar.

Talepler ve rezervasyonlar

Kendi platformunuzdan bizim tarafta talep oluşturun. Burada oluşturduğunuz her kayıt partner hesabınıza atfedilir ve panelinizde görünür.

POST/b2b/api/apiv1/bookings/new-enquiry

Talep oluştur

Bir yolcunun tur hakkındaki sorusu. Talep kaydı oluşturur ve operatöre bildirim gider.

Parametre	Tip	Açıklama
`tour_id`zorunlu	integer	Sorulan tur.
`contact_name`zorunlu	string	Yolcunun adı.
`contact_email`zorunlu	string	Yolcunun e-posta adresi.
`message`zorunlu	string	Soru metni, en fazla 5000 karakter.
`phone_code`	integer	Telefon ülke kodunun location id’si.
`contact_phone`	string	Ülke kodu olmadan telefon numarası.
`buyer_currency`	USD \| EUR	Fiyatlamanın yapılacağı para birimi. Varsayılan EUR.

API key ile gelen isteklerde captcha aranmaz — kapı zaten key, kota ve rate limit’tir.

POST/b2b/api/apiv1/bookings/new-booking

Rezervasyon oluştur

Yolcular ve odalarla birlikte tam rezervasyon. Ödemede kullanacağınız reference_id ve token ile birlikte rezervasyonu döner.

Parametre	Tip	Açıklama
`tour_id`zorunlu	integer	Rezerve edilen tur.
`pax`zorunlu	integer	Yolcu sayısı.
`date`zorunlu	YYYY-MM-DD	Hareket tarihi; bugün veya sonrası.
`service_type`zorunlu	string	Servis seviyesi; availability’nin döndürdüğü değer.
`seller_currency`zorunlu	string	Turun satıldığı para birimi.
`buyer_currency`zorunlu	string	Yolcunun ödeme yapacağı para birimi.
`rooms`	array	Konaklamalı turlarda zorunlu: [{ id: "dbl", pax, count }].
`customers`zorunlu	array	Yolcular. İlki lider yolcudur; title, first_name, last_name, email, phone_code ve phone zorunludur.

GET/b2b/api/apiv1/bookings/{referenceId}

Rezervasyon detayı

Tek bir rezervasyonu okur. Rezervasyon token’ını ?token= ile gönderin — token erişimi yalnız o rezervasyonla sınırlar.

Parametre	Tip	Açıklama
`token`zorunlu	string	Rezervasyon oluşturulurken dönen token.

POST/b2b/api/apiv1/bookings/{referenceId}/payment-request

Tahsilat talebi aç

Kendi ön yüzünüzde barınan bir ödeme sayfası için rezervasyon üzerinden tahsilat başlatır. Tutar rezervasyondan hesaplanır — istemci belirleyemez.

Parametre	Tip	Açıklama
`token`zorunlu	string	Rezervasyon token’ı.
`payment_model`	total \| deposit	Kalan tutarın tamamı mı yoksa yalnız kapora mı tahsil edilecek.

GET/b2b/api/apiv1/bookings/{referenceId}/payment-request/{id}

Tahsilat talebinin durumu

Bir tahsilat talebinin durumunu sorgular. Aynı token gerekir.

Parametre	Tip	Açıklama
`token`zorunlu	string	Rezervasyon token’ı.

POST/b2b/api/apiv1/bookings/abandoned-cart

Terk edilen sepeti bildir

Bir yolcunun rezervasyona başlayıp tamamlamadığını bildirir; ekibimiz takip eder. Rezervasyon kaydı oluşturmaz.

Parametre	Tip	Açıklama
`source`zorunlu	tsb \| tst	Sepetin hangi vitrinden geldiği.
`tour`zorunlu	string	Tur slug’ı.
`name`	string	Yolcunun adı.
`email`	string	Yolcunun e-posta adresi.
`phone_code`	integer	Telefon ülke kodunun location id’si.
`phone`	string	Telefon numarası.
`date`	YYYY-MM-DD	Planlanan hareket tarihi.
`pax`	integer	Yolcu sayısı.

Hatalar

Hatalar standart HTTP durum kodlarını kullanır; gövdede bir message ve — doğrulama hatalarında — alan adlarıyla anahtarlanmış bir errors nesnesi döner.

Kod	Anlamı	Ne yapmalı
200	OK	İstek başarılı.
401	Unauthorized	X-API-Key header’ı yok ya da key tanınmıyor. Ürettiğiniz key’i gönderdiğinizden emin olun — yerine geçtiği eskisini değil.
403	Forbidden	API erişiminiz askıya alınmış ya da henüz onaylanmamış. Bir hata olduğunu düşünüyorsanız bize yazın.
404	Not found	Tur, rezervasyon ya da lokasyon yok — token ile sınırlı endpoint’lerde token eşleşmiyor olabilir.
422	Unprocessable	Doğrulama başarısız. Gövdede bir message ve alan adlarıyla anahtarlanmış bir errors nesnesi döner.
429	Too many requests	Dakikalık rate limit’i ya da günlük kotanızı aştınız. X-RateLimit-Remaining header’ına bakıp hızınızı düşürün.
500	Server error	Bizim tarafta bir şey hata verdi. Artan aralıklarla tekrar deneyin; sürerse isteğin saatiyle birlikte bize ulaşın.

422 yanıtı

{
  "message": "The given data was invalid.",
  "errors": {
    "tour_id": ["The selected tour id is invalid."],
    "customers.0.email": ["The customers.0.email must be a valid email address."]
  }
}

Sürümleme

Sürüm yolun bir parçasıdır: /b2b/api/apiv1/… ve /b2b/api/apiv2/…. İkisi de canlı ve bakımdadır; bir endpoint’in hangisinin altında olduğu tarihsel bir ayrımdır, kalite farkı değil.

Bir sürüm içinde yalnızca ekleme yaparız — yeni alan, yeni endpoint. Halihazırda kullandığınız alanları yeniden adlandırmaz ya da kaldırmayız. Entegrasyonu bozacak her şey yeni bir sürüm yolunda yayına girer ve bir sürüm emekliye ayrılmadan önce tüm aktif partnerlara e-posta göndeririz.

Geliştirmeye hazır mısınız?

Erişim için başvurun ve key’inizi üretin. Hangi entegrasyonun size uyduğunu mu merak ediyorsunuz? Ekibimiz yardımcı olmaktan memnun olur.

Erişim için başvurun Ekibimizle görüşün

TravelShop Booking API