Ada Vegas turlarını kendi sitenizde satın

1. Genel bakış

Partner API, HTTPS üzerinden çalışan JSON/REST bir API'dir. Müşteri portalınızda yapabildiğiniz her şey (turları görme, teklif alma, rezervasyon, iptal, bakiye sorgulama) programatik olarak da yapılabilir.

• Fiyatınız tur ve sezon başına tek bir mayorista/acenta fiyatıdır. Müşterinize ne kadara satacağınıza siz karar verirsiniz.
• Bakiyeniz her satışı öder. Bakiye biterse rezervasyon yine kabul edilir ama yükleme yapana kadar beklemede kalır (bkz. Kredi).
• Ada Vegas her satıştan anında haberdar olur: acentanız, tur, tarih, yolcu sayısı ve tutar.

2. Hızlı başlangıç

1. Portalınızda API ve Entegrasyon → Anahtarlar bölümünden anahtar oluşturun. Önce ücretsiz denemek için Sandbox anahtarı oluşturun. Secret yalnızca bir kez gösterilir.
2. İsterseniz anahtarı sunucu IP'lerinize kısıtlayın (Güvenilen IP).
3. API'yi çağırın:

curl "https://api.adavegastravel.com/v1/services?date=2026-11-10&pax=2" \
  -H "X-Api-Key: YOUR_KEY" \
  -H "X-Api-Secret: YOUR_SECRET" \
  -H "Accept-Language: tr"

Taban URL: https://api.adavegastravel.com/v1. Henüz hesabınız yok mu? Herkese açık demo bilgileriyle hemen deneyin: anahtar demo-key-adavegas, secret demo-secret-adavegas. Kendi canlı ve sandbox anahtarlarınız hesabınız onaylandığında verilir.

Tam örnek: teklif, rezervasyon, sorgu

# 1. 2 yetişkin + 1 çocuk için kesin fiyat
curl "$BASE/services/12/quote?date=2026-11-10&pax=2&children=1" -H "X-Api-Key: $KEY" -H "X-Api-Secret: $SECRET"

# 2. rezervasyonu oluştur (idempotency anahtarı sayesinde tekrar denemek güvenli)
curl -X POST "$BASE/bookings" \
  -H "X-Api-Key: $KEY" -H "X-Api-Secret: $SECRET" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: order-10045" \
  -d '{"service_id":12,"pax":2,"children":1,"service_date":"2026-11-10",
       "customer_name":"Ana Pérez","customer_email":"ana@example.com",
       "customer_phone":"+34600111222","notes":"Vejetaryen"}'

# 3. sonra: durum sorgusu
curl "$BASE/bookings/AB-2026-8DB0391E" -H "X-Api-Key: $KEY" -H "X-Api-Secret: $SECRET"

3. Kimlik doğrulama ve güvenlik

• API'yi yalnızca sunucunuzdan çağırın. Secret'ı tarayıcıya veya mobil uygulamaya asla koymayın.
• Anahtar başına Güvenilen IP (tek IP veya 203.0.113.0/24 gibi CIDR) tanımlanabilir; diğer IP'ler 403 alır.
• Ortam başına (canlı / sandbox) tek aktif anahtar vardır. Yenisini üretmek öncekini iptal eder.
• Her zaman HTTPS. İstek gövdesi en fazla 64 KB.

4. Genel kurallar

5. Kredi ve bakiye

Her satış ön ödemeli bakiyenizden ödenir (hesap para biriminiz: TRY, USD veya EUR).

• Rezervasyonda: toplam tutar anında bakiyenizden düşer (tur başka para biriminde fiyatlandıysa günlük kurla hesap para biriminize çevrilir).
• Bakiye yoksa? Bakiye eksiye düşer (borç yazılır) ve rezervasyon pending kalır, hold_reason: "insufficient_credit" döner. Borcunuz izin verilen sınıra inene kadar onaylanmaz.
• Yükleme portaldan (Bakiye → Kartla öde, 10 ile 50.000 arası) veya banka havalesiyle yapılır (Ada Vegas kaydeder). Otomatik onay sizde açıksa bekleyen rezervasyonlar kendiliğinden onaylanır, değilse Ada Vegas personeli onaylar.
• Bekleyen rezervasyonu iptal ederseniz tutarın tamamı anında bakiyenize döner.
• credit_limit, Ada Vegas'ın size tanıdığı borç sınırıdır (varsayılan 0). available = balance + credit_limit.
• Sandbox rezervasyonları bakiyenize hiç dokunmaz.

6. Rezervasyon yaşam döngüsü

İzin verilen geçişler: pending → confirmed, pending → cancelled, confirmed → cancelled (onaylı rezervasyon iptallerini Ada Vegas yapar; bizimle iletişime geçin). Her geçiş bir webhook tetikler.

Kanallar (channel alanı): api (entegrasyonunuz), portal (portaldan yapılan), site (kendi web sitenizden yapılan, bkz. 12. bölüm; bunları portalınızda siz onaylarsınız).

7. Fiyat ve teklif

• Fiyatlar sezonlar halinde tanımlıdır: yetişkin başına tek fiyat, isteğe bağlı child_price (boşsa yetişkinle aynı) ve isteğe bağlı min_pax / max_pax (yetişkin + çocuk üzerinden sayılır).
• Konaklamalı turlar occupancy (örn. single, double, triple) ve rooms ister; teklif oda başına geçerli seçenekleri listeler.
• Rezervasyondan önce her zaman /quote çağırın. POST /bookings ile birebir aynı hesabı yapar. /services içindeki unit_price ve pricing.applicable seçilen tarih için yetişkin fiyatını gösterir; çocuk, grup sınırları ve konaklama yalnızca teklifte bulunur.

8. Uç noktalar

Hesabınız, para biriminiz, webhook durumu ve kredi özeti.

{"data":{"id":22,"name":"Acentanız","status":"active","currency":"EUR","sandbox":false,
 "contact":{"name":"...","email":"...","phone":null},"webhook_configured":false,
 "credit":{"balance":825.28,"currency":"EUR","credit_limit":0,"available":825.28,"can_confirm":true}}}

Dönüşümlerde kullanılan kurlar (taban TRY).

{"data":{"base":"TRY","rates":{"USD":32.1,"EUR":35.2,"TRY":1},"supported":["TRY","USD","EUR"]}}

Size açık tur kategorileri ve ek alan tanımları (key, label, type, required, options).

Satabileceğiniz turlar ve bir tarih için fiyatınız.

Her tur şunları içerir:

Tek tur, aynı yapıda. Yoksa veya size açık değilse 404 service_not_found.

{"data":{"ok":true,"date":"2026-10-29","pax":2,"children":1,"min_pax":null,"max_pax":null,
 "currency":"EUR","season":"Sonbahar 2026",
 "tour":{"unit":58.24,"child_unit":58.24,"total":174.72},
 "options":[],"accommodation":null,"total":174.72}}

Konaklamalı turda options {occupancy,label,per_room} listeler, accommodation seçilen seçeneği otel bazında breakdown ile verir; total = tur + konaklama. Hatalar: 422 ile no_price_for_date, pax_below_min / pax_above_max (ve limit), invalid_occupancy, no_accommodation_price.

201 döner:

{"data":{"booking_ref":"AB-2026-8DB0391E","service_id":1,"service_name":"Istanbul Classics",
  "pax":2,"children":1,"currency":"EUR","unit_price":58.24,"total_price":174.72,
  "service_date":"2026-10-29","customer_name":"Ana Pérez","status":"confirmed",
  "sandbox":false,"channel":"api","sale_total":null,"customer_lang":null,
  "credit_charged":"174.72","hold_reason":null,"created_at":"2026-10-26T10:44:12+00:00"},
 "credit":{"balance":825.28,"currency":"EUR","credit_limit":0,"available":825.28,"can_confirm":true}}

credit_charged, hesap para biriminizde bakiyenizden düşen tutardır. status yalnızca sizde otomatik onay açıksa ve krediniz yeterliyse hemen confirmed olur; aksi halde pending (hold_reason'a bakın).

Rezervasyonlarınız, en yeniden eskiye. Süzgeçler: status (pending|confirmed|cancelled), customer_email, channel (api|portal|site), from / to (oluşturma tarihi), page, per_page.

Tek rezervasyon (aynı yapıda). 404 booking_not_found.

Beklemedeki rezervasyonu iptal eder ve tutarın tamamını bakiyenize iade eder. Onaylı rezervasyon için 409 not_cancellable döner: Ada Vegas ile iletişime geçin.

Bakiye özeti ve son hesap hareketleri (?limit=1..100, varsayılan 20).

{"data":{"balance":825.28,"currency":"EUR","credit_limit":0,"available":825.28,"can_confirm":true,
 "transactions":[
  {"type":"charge","amount":-174.72,"currency":"EUR","balance_after":825.28,"booking_ref":"AB-2026-8DB0391E","reference":null,"created_at":"..."},
  {"type":"topup","amount":1000,"currency":"EUR","balance_after":1000,"booking_ref":null,"reference":"BANK-2210","created_at":"..."}]}}

Tipler: topup (+), charge (−), refund (+), adjust (±, Ada Vegas'ın elle düzeltmesi).

Portalda tanımladığınız web sitesi yapılandırması (ad, diller, renkler, sayfalar, hangi turların gösterildiği ve kâr payınız). Hazır web sitesi paketi kullanır; yayına alana kadar 404 site_disabled. Bkz. 12. bölüm.

9. Webhook

Sürekli sorgulamak yerine portalda (API ve Entegrasyon → Webhook) bir Webhook URL tanımlayın. Sizin için bir imza anahtarı üretilir.

POST https://your-site.example/hooks/adavegas
Content-Type: application/json
X-Agency-Webhook-Event: booking.confirmed
X-Agency-Webhook-Signature: sha256=3b1f...e9

{"event":"booking.confirmed","booking_ref":"AB-2026-8DB0391E","status":"confirmed",
 "service_id":1,"service_name":"Istanbul Classics","customer_name":"Ana Pérez","customer_email":"ana@example.com",
 "channel":"api","credit_charged":"174.72","pax":2,"children":1,"service_date":"2026-10-29",
 "currency":"EUR","total_price":174.72,"sandbox":false,"occurred_at":"2026-10-26T10:44:12+00:00"}

İmzayı doğrulama

İmza = HMAC-SHA256(ham istek gövdesi, webhook secret), hex olarak, başına sha256= eklenir. Sabit zamanlı karşılaştırın ve yeniden kodlanmış JSON değil ham gövdeyi kullanın.

// PHP
$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_AGENCY_WEBHOOK_SIGNATURE'] ?? '')) { http_response_code(401); exit; }

// Node.js (Express, express.raw({type:'application/json'}) ile)
const crypto = require('crypto');
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(req.body).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.get('X-Agency-Webhook-Signature') || ''));

Teslimat

• 10 saniye içinde herhangi bir 2xx ile yanıtlayın. Aksi halde artan beklemeyle en fazla 5 kez yeniden denenir (yaklaşık 2, 4, 8 ve 16 dakika). Sonra olay bırakılır; uzlaştırmak için GET /bookings kullanın.
• Teslimatlar kuyruğa alınır ve yaklaşık bir dakika içinde gönderilir. Olaylar birden fazla kez veya sırasız gelebilir: "X rezervasyonu değişti, durumunu çek" diye ele alın ve işleyicinizi idempotent yapın.

10. Sandbox

Portalda bir Sandbox anahtarı oluşturun. Canlı gibi davranır ancak: rezervasyonlar "sandbox": true işaretlenir, bakiyenizden hiç düşülmez veya iade edilmez ve Ada Vegas personeline bildirim gitmez. Webhook'lar yine gönderilir (sandbox: true ile); böylece alıcınızı uçtan uca test edebilirsiniz. Canlıyla aynı taban URL'yi kullanır; yalnızca anahtar farklıdır. Hesap açmadan hızlıca bakmak için herkese açık demoyu kullanın (örnek veri, hiçbir şey saklanmaz).

11. Tipik entegrasyon (sunucu tarafı)

// PHP 8, cURL
function av(string $method, string $path, ?array $body = null, array $headers = []): array {
    $ch = curl_init('https://api.adavegastravel.com/v1' . $path);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => $method, CURLOPT_TIMEOUT => 20,
        CURLOPT_HTTPHEADER => array_merge(['X-Api-Key: ' . getenv('AV_KEY'), 'X-Api-Secret: ' . getenv('AV_SECRET'),
            'Content-Type: application/json', 'Accept-Language: tr'], $headers),
        CURLOPT_POSTFIELDS => $body ? json_encode($body, JSON_UNESCAPED_UNICODE) : null,
    ]);
    $out = curl_exec($ch); $code = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch);
    return [$code, json_decode((string) $out, true)];
}

[$c, $q] = av('GET', '/services/12/quote?date=2026-11-10&pax=2&children=1');
if ($c === 200) {
    [$c, $b] = av('POST', '/bookings', ['service_id' => 12, 'pax' => 2, 'children' => 1, 'service_date' => '2026-11-10',
        'customer_name' => 'Ana Pérez'], ['X-Idempotency-Key: order-10045']);
    // $b['data']['status'] "confirmed" veya "pending"; müşterinize kendi fiyatınızı gösterin, $b['data']['booking_ref']'i saklayın
}

12. Kendi web sitenizde satış

İki yol var, ikisi de aynı API'yi kullanır:

A. Hazır web sitesi paketi ("Vitrin")

Kendi hostinginize yüklediğiniz, yalnızca önyüzden oluşan bir seyahat sitesidir (PHP 8.1+, veritabanı gerekmez). Site adı, renkler, metinler (ES/EN/TR), sayfalar, hangi turların görüneceği ve kâr payı % portaldan (Web sitem) yönetilir. Ziyaretçi sizin fiyatınızı = Ada Vegas fiyatı + kâr payınız görür, bizim fiyatımızı asla görmez. Ziyaretçinin talebi hesabınızda bir rezervasyona dönüşür (Ada Vegas fiyatı üzerinden bakiyenizden düşer) ve Rezervasyonlar → Web sitem altında görünür; onayı veya iptali siz yaparsınız. Yolcu kendi dilinde e-posta alır ve "Rezervasyonlarım" sayfasını kullanır. Güncellemeler portaldan tek tıkla uygulanır.

B. Kendi siteniz veya sisteminiz

Sayfalarınızı /services ve /quote ile kendiniz yapın, rezervasyonları sunucudan oluşturun. Yayındaki web sitesi yapılandırmanızın kâr payı ve e-posta özelliklerini kullanmak için POST /bookings isteğine şunları ekleyin:

13. Hatalar

Kabul edilip krediyi bekleyen rezervasyon bir hata değildir: 201 ve status: "pending", hold_reason: "insufficient_credit" alırsınız.

14. İyi uygulamalar

• Rezervasyondan hemen önce teklif alın; fiyat ve sezonlar değişebilir.
• Her zaman X-Idempotency-Key gönderin; zaman aşımında aynı isteği aynı anahtarla tekrarlayın.
• İstek sınırının çok altında kalmak için tur içeriğini (/services) birkaç dakika önbelleğe alın; her sayfa gösteriminde API çağırmayın.
• pending durumunu yönetin: booking.confirmed webhook'u gelene kadar müşterinize "talebiniz alındı" gösterin.
• credit.can_confirm alanını izleyin ve yoğun dönemlerden önce bakiye yükleyin; elden müdahalesiz onay için Ada Vegas ile otomatik onayı açtırın.
• Her çağrının booking_ref değerini kaydedin. Portaldaki İstek günlüğü her çağrıyı saat, IP ve durumla gösterir.
• Secret sızmış olabilirse anahtarı yenileyin (portal → yeni anahtar üret).

15. Destek

Sorular, onaylı rezervasyon iptali, limit artırımı, otomatik onay veya entegrasyon yardımı için Ada Vegas hesap yöneticinizle iletişime geçin. Mesajınıza booking_ref ve isteğin saatini ekleyin.

Ada Vegas Partner API v1