İş ortağı API'si

1.1 Nedir?

İş ortağı API'si, kendi rezervasyon sisteminizden Tourwix fiyatı almanızı ve rezervasyon açmanızı sağlayan bir REST arayüzüdür. Ürünler: transfer, saatlik araç ve gezi transferi. Ödeme yalnız şirket carinizden yapılır; iptal ve değişiklikler Tourwix onaylı talep olarak iletilir.

1.2 Kimler için?

Kendi rezervasyon ya da satış sistemi olan, Tourwix ile cari hesapla çalışan onaylı iş ortakları içindir: acente, otel, kurumsal firma ve operatör. API ekranı portalda yalnız şirket carisine rezervasyon yetkisi olan kişilere açıktır; Tourwix bu özelliği firma bazında kapatabilir.

1.3 Neden Tourwix?

• Test (sandbox) erişimi başvuru anında açılır; gerçek rezervasyon açmadan entegrasyonu deneyebilirsiniz.
• Fiyat, portalda gördüğünüz net fiyatla aynı hesapla üretilir.
• Her istekte açık hata kodları ve istek numarası (request_id); portalda istek kaydı.
• Tekrar korumalı rezervasyon (Idempotency-Key) ve kendi referans numaranız (partner_reference).
• API rezervasyonları Rezervasyonlarım listesinde "API" kaynağıyla görünür.

2.1 Çalışma kuralları

1. 1

   1. Erişim adımları

   Portaldan başvurursunuz; test (sandbox) erişimi hemen açılır. Canlı erişimi Tourwix, sözleşme imzalandıktan ve cari limitiniz tanımlandıktan sonra açar. Reddedilen başvuruyu yalnız Tourwix yeniden açabilir.

2. 2

   2. Anahtarlar

   Anahtarlar tw_test_… (sandbox) ve tw_live_… (canlı) biçimindedir ve her istekte Authorization: Bearer <anahtar> başlığıyla gönderilir. Anahtar yalnız oluşturulduğu an bir kez gösterilir; Tourwix anahtarın kendisini saklamaz. Her anahtara yalnız gereken yetkileri verin.

3. 3

   3. Anahtar güvenliği

   Anahtarı tarayıcıda, mobil uygulamada ya da herkese açık kodda kullanmayın; yalnız kendi sunucunuzda saklayın. Sızdığından şüphelenirseniz hemen "İptal et" deyin (geri alınamaz). "Döndür" yeni anahtar üretir; eski anahtar en çok 7 gün daha çalışır.

4. 4

   4. Kimin adına işlem yapılır

   API rezervasyonları firmanızın carisine ve firma sahibinin adına açılır.

5. 5

   5. Fiyat

   API fiyatı, firmanızın portaldaki net fiyatıdır (firma ekleri dahil, kişisel ek yok). net_total carinizden düşülecek tutardır. API kanalı için kâr payı tanımlarsanız yalnız misafir fiyatına (guest_total) eklenir; net fiyat değişmez. Boş dönüş ilanları API'de satılmaz.

6. 6

   6. Teklif süresi

   Teklif 15 dakika geçerlidir. Süresi dolan teklifle rezervasyon açılmaz (quote_expired); fiyat değiştiyse yanıtta yeni teklif gelir (price_changed).

7. 7

   7. Tekrar koruması

   POST /v1/bookings isteğinde benzersiz bir Idempotency-Key (8–128 karakter) zorunludur. Aynı anahtar ve aynı gövdeyle tekrar gelen istek ilk yanıtı aynen döndürür; aynı anahtar farklı gövdeyle 422, ilk istek hâlâ işleniyorsa 409 döner. partner_reference firma içinde tekil olmalıdır.

8. 8

   8. Sınırlar

   Varsayılan: dakikada 60 istek, dakikada 20 adres araması, günde 50 rezervasyon. Sınır aşılınca 429 döner; Retry-After başlığındaki saniye kadar bekleyin. Tourwix sınırları ve açık ürünleri firma bazında değiştirebilir.

9. 9

   9. Ödeme ve cari

   Ödeme yalnız şirket carisinden yapılır. Limit yetmezse rezervasyon açılmaz (402 insufficient_credit).

10. 10

    10. İptal ve değişiklik

    API rezervasyonu doğrudan iptal edilmez veya değiştirilmez; talep açılır ve Tourwix onaylar. Bir rezervasyonda aynı anda tek bekleyen talep olabilir. API rezervasyonlarında B2B iptal kuralı uygulanır.

11. 11

    11. Durum takibi

    Webhook yoktur. Rezervasyonun ve taleplerin durumunu GET /v1/bookings/{id} ile makul aralıklarla sorgulayın. GET /v1/bookings yalnız API ile açılan rezervasyonları listeler.

12. 12

    12. Sandbox

    Test anahtarıyla açılan rezervasyonlar gerçek transfer oluşturmaz ve cariden düşmez; yalnız test kaydıdır.

13. 13

    13. Veri kuralları (KVKK / GDPR)

    Misafirden yalnız rezervasyon için gereken bilgiyi gönderin (baş yolcu adı ve telefonu zorunlu, e-posta isteğe bağlı). Şoför telefonu API'den gönderilmez; misafir bilgilendirmesini Tourwix yapar. Yanıtlarda baş yolcunun yalnız adı döner.

14. 14

    14. Bildirim ve görünürlük

    API ile açılan her rezervasyon firmanıza bağlanır; firmada sahip ve tüm personel görür. Yeni rezervasyonda firmanıza e-posta ve anlık bildirim gider (Tourwix gönderim ayarları açıkken).

15. 15

    15. Askıya alma

    Tourwix API erişimini askıya alabilir ve yeniden açabilir; askıdayken anahtarlar çalışmaz.

3.1 Başlangıç

1. 1

   1. Ekranı açın

   İş ortağı portalınızda menüden "API erişimi" sayfasına girin.

2. 2

   2. Başvurun

   "API erişimi için başvurun" formunda kullanım amacını yazıp "Başvuruyu gönder" deyin. Test (sandbox) erişimi hemen açılır.

3. 3

   3. Anahtar oluşturun

   "Anahtarlar" sekmesinde "Yeni anahtar" deyin; ad, ortam (Test) ve yetkileri seçip "Oluştur"a basın. Anahtarı kopyalayıp güvenli bir yere kaydedin.

4. 4

   4. Kılavuzu izleyin

   "Hızlı başlangıç" sekmesindeki adres ve örneklerle ilk isteğinizi gönderin. Tüm alanlar /v1/openapi.json adresindedir.

5. 5

   5. Canlıya geçin

   Sözleşme ve cari limitiniz tamamlanınca Tourwix canlı erişimi açar; ardından Canlı ortamda yeni anahtar oluşturun.

3.2 Rezervasyon akışı

1. 1

   1. Nokta bulun

   GET /v1/locations ile alış ve bırakış noktalarını arayın (gezi için GET /v1/excursion-destinations).

2. 2

   2. Fiyat alın

   POST /v1/quotes ile teklif alın. Yanıttaki her seçenekte guest_total ve net_total yer alır; teklif 15 dakika geçerlidir.

3. 3

   3. Rezervasyon açın

   POST /v1/bookings ile teklif ve seçenek kimliğini, yolcu bilgilerini ve partner_reference'ı gönderin; Idempotency-Key başlığını ekleyin.

4. 4

   4. Durumu izleyin

   GET /v1/bookings/{id} ile durumu, bacakları ve talepleri okuyun.

5. 5

   5. Talep açın

   Gerekirse cancellation-requests ya da amendment-requests ile talep açın; Tourwix'in kararını aynı uçtan izleyin.

6. 6

   6. Kaydı inceleyin

   Portaldaki "İstek kaydı" sekmesinde isteklerinizi, sonuçlarını ve sürelerini görün.

Hata yanıtları type, title, status, code, detail ve request_id alanlarını içerir. Destek isterken request_id değerini iletin.

Sürüm 1.1.0 (2026-10-18): teklif yanıtına geriye uyumlu warnings alanı eklendi (uyarı yoksa boş dizi). lead_time_too_short: alış, en kısa rezervasyon sürenizden (min_lead_minutes) daha yakın; bu teklifle canlı rezervasyon açılmaz.

Sürüm 1.2.0 (2026-10-19): Rota Fırsatı API'de. Tourwix hesabınızda açarsa (varsayılan kapalı) tek yön transfer teklifine uygun Rota Fırsatı seçenekleri route_deal alanıyla eklenir (valid_from, valid_until, one_time, label). Alış saati ilanın 30 dakikalık dilimlerinden biri ve ilan bölgesi içinde olmalı; yalnız cari ödeme; API kârınız mevcut tavanla uygulanır. Tek seferlik satılır: başkası önce alırsa rezervasyon 409 offer_unavailable döner. İptal normal iptal talebiyle.

Sürüm 1.3.0 (2026-10-19): ücretli SMS bilgilendirme paketi. Teklif yanıtında sms_notification (available, price — EUR cariye yazılan tutar, diğer para birimleri bilgi). Rezervasyonda isteğe bağlı sms_notification: true; misafire yalnız işlem SMS'i gider (onay, şoför kısa adı + plaka + Tourwix 7/24 hattı — şoför telefonu yok, alıştan 24 saat önce hatırlatma, alış saati / şoför değişikliği). Rezervasyon başına tek ücret (gidiş-dönüş tek); ücret diğer ekler gibi carinize yazılır, üzerinde kâr payı yoktur; net_total ve guest_total ücreti içerir, yanıtta sms_fee. Rota Fırsatı tekliflerinde yok. Satışta değilse / cep numarası uluslararası biçimde geçerli değilse 422 sms_notification_unavailable. Tam iadede ücret de iade edilir, kısmi iadede edilmez. Alan gönderilmezse davranış değişmez.