API Kullanım Kılavuzu

Tranigo ağındaki havalimanı ve şehir içi transferleri kendi sisteminizden aramak, satmak ve takip etmek için.

Bu sayfa akışı ve kuralları anlatır. Her alanın tam tanımı için Swagger sayfasına bakın; oradan istekleri doğrudan deneyebilirsiniz.

Kimlik doğrulama

Sunucudan sunucuya entegrasyonda API anahtarı kullanılır. Anahtarı acenta panelinde API & Webhook sayfasından üretirsiniz; anahtar yalnızca bir kez gösterilir, bizde saklanmaz.

Anahtarı iki şekilde gönderebilirsiniz:

Authorization: Bearer ctt_live_xxxxxxxxxxxxxxxx
# ya da
X-Api-Key: ctt_live_xxxxxxxxxxxxxxxx

Bağlantıyı denemek için:

curl https://api.citytransferturkey.com/v1/me \
  -H "Authorization: Bearer ctt_test_xxxxxxxx"

Yanıtta firma bilginiz, modunuz (live/test), komisyon oranınız ve cari hesabınızın açık olup olmadığı döner.

Hızlı başlangıç

Bir rezervasyon dört çağrıdır. Önce ctt_test_ anahtarıyla deneyin.

1. Konum bulun — havalimanı ya da otel bölgesinin kimliği:

   curl "https://api.citytransferturkey.com/v1/locations?q=antalya" \
     -H "Authorization: Bearer $CTT_KEY"

2. Teklif alın — güzergah, tarih ve yolcu sayısına göre araçlar ve fiyatlar (30 dakika geçerli):

   curl -X POST https://api.citytransferturkey.com/v1/quotes \
     -H "Authorization: Bearer $CTT_KEY" -H "Content-Type: application/json" \
     -d '{"fromRegionId":"…","toRegionId":"…","date":"2026-11-20","passengers":2}'

3. Rezervasyon açın — seçtiğiniz teklif, yolcu bilgisi ve kendi rezervasyon numaranızla:

   curl -X POST https://api.citytransferturkey.com/v1/bookings \
     -H "Authorization: Bearer $CTT_KEY" -H "Content-Type: application/json" \
     -d '{
       "quoteId": "…",
       "paymentMethod": "OnAccount",
       "externalReference": "ACN-2026-0042",
       "pickupDate": "2026-11-20",
       "pickupTime": "14:30",
       "passenger": { "firstName": "Ayşe", "lastName": "Yılmaz", "phoneCode": "+90",
                      "phone": "5551112233", "email": "ayse@example.com" },
       "passengerCount": 2,
       "flightCode": "TK2412",
       "hotelAddress": "Lara Cd. No:1, Antalya"
     }'

4. Takip edin — GET /v1/bookings/{code} ile ya da webhook'larla durum değişikliklerini alın.

Konumlar ve teklif

GET /v1/locations?q=… en az 2 karakterle havalimanı/bölge arar. GET /v1/locations/{regionId}/destinations o bölgeden fiyatı olan varış noktalarını verir.

POST /v1/quotes uygun araçları döner. Her teklifte:

Sağlayıcının kapalı günü olan ya da en az rezervasyon süresine (ör. 12 saat önceden) yetişmeyen araçlar teklifte hiç görünmez. İsteğe "currency": "EUR" ekleyerek fiyat dövizini seçebilirsiniz (TRY, EUR, USD); verilmezse hesabınızın dövizi kullanılır.

Rezervasyon açma

POST /v1/bookings — yeni rezervasyon 201, aynı externalReference ile daha önce açılmış rezervasyon 200 döner.

Tekrar deneme güvenliği (idempotency)

externalReference sizin rezervasyon numaranızdır ve hesabınızda benzersizdir. Ağ hatasında isteği aynı numarayla tekrar göndermeniz yeterli: ikinci kez rezervasyon açılmaz, mevcut olan döner. Bu alanı her zaman göndermenizi öneririz.

Dönüş transferi

İsteğe "return": {"date":"2026-11-25","time":"10:00","flightCode":"TK2413","hotelAddress":"…"} ekleyin. Dönüş ayrı bir rezervasyon kodu (…-R) alır; yanıtta return alanında gelir. Gidişi iptal etmek dönüşü de iptal eder.

Yanıt

{
  "booking": { "code": "CTT7K2M9Q", "externalReference": "ACN-2026-0042", "status": "Pending",
               "scheduledDate": "2026-11-20", "scheduledTime": "14:30", "price": 120.00, "currency": "EUR",
               "commission": 12.00, "commissionCurrency": "EUR", "isTest": false, … },
  "return": null,
  "payment": { "method": "OnAccount", "status": "Paid", "online": null }
}

Ödeme seçenekleri

Kartla ödeme beklenen rezervasyon

"payment": {
  "method": null, "status": null,
  "online": {
    "url": "https://citytransferturkey.com/en/Pay/Ab3dEf7hJk9m",
    "paidBy": "passenger",            // "passenger" | "partner"
    "amount": 120.00, "currency": "EUR",
    "dueAt": "2026-11-12T09:14:00Z",
    "status": "awaiting_payment",     // awaiting_payment | paid | cancelled | expired
    "paidAt": null
  }
}

Sitenizde kartla ödeme

CreditCard (yolcu öder) rezervasyonda yolcuyu bizim ödeme sayfamıza göndermek yerine kart formunu kendi sitenizde gösterebilirsiniz. Kart bilgisi sunucunuzdan bize iletilir; sitenizden çıkılan tek adım bankanın 3D Secure sayfasıdır, ardından müşteri sizin sayfanıza döner.

curl -X POST https://api.citytransferturkey.com/v1/bookings/CTT7K2M9Q/payments/card \
  -H "Authorization: Bearer ctt_live_xxxxxxxx" -H "Content-Type: application/json" \
  -d '{ "cardHolderName": "Ali Veli", "cardNumber": "5528790000000008",
        "expireMonth": "12", "expireYear": "2030", "cvc": "123",
        "returnUrl": "https://www.siteniz.com/en/booking/confirmation/ABC123",
        "customerIp": "203.0.113.7" }'

Yanıt (200)

{ "status": "redirect",   // redirect | paid | failed
  "html": "<form …>…",    // yalnızca redirect: bankanın 3D Secure sayfası
  "message": null, "errorCode": null }

• redirect: html'i müşterinin tarayıcısına olduğu gibi (text/html) gönderin. Banka doğrulamasından sonra tarayıcı returnUrl'e döner; sorgu dizesine payment=success, payment=failed ya da payment=pending eklenir. Bu parametre yalnızca bilgi içindir — sonucu her zaman GET /v1/bookings/{code} ile doğrulayın (payment.online.status = "paid"). Ödeme gelince booking.paid webhook'u da gider.
• paid: ödeme alındı (sandbox'ta her zaman bu döner).
• failed: message'ı müşteriye gösterin. errorCode: invalid_card_holder, invalid_card_number, invalid_card_expiry, invalid_card_cvc, card_declined, three_ds_failed, payment_pending, payment_unknown (sonuç doğrulanamadı — tekrar denetmeyin, rezervasyon durumunu kontrol edin), payment_unavailable, too_many_attempts (bir rezervasyonda son bir saatte 5 başarısız ya da 10 deneme).

Sitenizde PayPal ile ödeme

Aynı CreditCard (yolcu öder) rezervasyonda PayPal butonlarını (PayPal JS SDK, Smart Buttons) kendi sayfanızda gösterebilirsiniz. Siteden çıkılan tek şey PayPal'ın kendi penceresidir; order açma ve parayı çekme (capture) sunucunuzdan bize gelir. Dönüş alan adı gerekmez. Ödeme koşulları, deneme sınırı ve hatalar kartla ödeme ile aynıdır.

1. SDK bilgisi

curl https://api.citytransferturkey.com/v1/bookings/CTT7K2M9Q/payments/paypal \
  -H "Authorization: Bearer ctt_live_xxxxxxxx"

{ "simulated": false, "clientId": "AXk…", "amount": 120.00, "currency": "EUR", "intent": "capture" }

Sayfanıza https://www.paypal.com/sdk/js?client-id={clientId}&currency={currency}&intent=capture yükleyin. amount / currency PayPal'da çekilecek tutardır (TRY rezervasyonda EUR'ya çevrilmiş olabilir). PayPal kapalıysa ya da bu para biriminde kullanılamıyorsa 422 errors/paypal_not_available döner — PayPal butonunu göstermeyin.

2. Order (butonun createOrder'ı)

curl -X POST https://api.citytransferturkey.com/v1/bookings/CTT7K2M9Q/payments/paypal/order \
  -H "Authorization: Bearer ctt_live_xxxxxxxx" -H "Content-Type: application/json" \
  -d '{ "customerIp": "203.0.113.7" }'

{ "orderId": "5O190127TN364715T" }

Tutar ve ödeyici (yolcu) rezervasyondan alınır; gövde isteğe bağlıdır. Müşteri PayPal penceresini kapatıp yeniden açarsa aynı açık order döner. orderId'yi createOrder'dan döndürün.

3. Capture (butonun onApprove'u)

curl -X POST https://api.citytransferturkey.com/v1/bookings/CTT7K2M9Q/payments/paypal/capture \
  -H "Authorization: Bearer ctt_live_xxxxxxxx" -H "Content-Type: application/json" \
  -d '{ "orderId": "5O190127TN364715T" }'

{ "status": "paid", "message": null, "errorCode": null }   // paid | pending | failed

• paid: ödeme alındı; booking.paid webhook'u gider. Aynı orderId tekrar gönderilirse PayPal'a gidilmeden yine son durum döner (idempotent).
• pending: payment_pending (PayPal incelemesinde) ya da payment_unknown (sonuç doğrulanamadı) — müşteriye tekrar ödetmeyin, durumu GET /v1/bookings/{code} ile izleyin.
• failed: payment_retry → PayPal ödeme kaynağını reddetti; SDK'da actions.restart() çağırın, müşteri başka kaynak seçsin. payment_declined → message'ı gösterin.

Durumlar ve iptal

POST /v1/bookings/{code}/cancel gövde: {"reason":"Müşteri vazgeçti"} (isteğe bağlı). Sözleşmenizdeki ücretsiz iptal süresi geçtiyse (ör. alıştan 24 saat öncesine kadar) geç iptal ücreti cari hesabınıza yazılır; cari rezervasyonun borcu ters kaydedilir. Tamamlanmış ya da zaten iptal edilmiş rezervasyon iptal edilemez (422).

GET /v1/bookings listeleme: status, dateFrom, dateTo, search, page, pageSize (en fazla 100).

Sandbox (test)

ctt_test_ anahtarıyla her şeyi gerçek veri üretmeden deneyin. Test rezervasyonları canlı kayıtlarınızla karışmaz (ayrı listelenir), sağlayıcıya gitmez, cariye yazılmaz. Webhook'lar "livemode": false ile gönderilir.

Kartlı test rezervasyonunda gerçek ödeme linki oluşmaz (payment.online.url = null). Ödemeyi taklit etmek için:

curl -X POST https://api.citytransferturkey.com/v1/bookings/CTT7K2M9Q/simulate-payment \
  -H "Authorization: Bearer ctt_test_xxxxxxxx"

Bu uç nokta canlı anahtarla 403 döner.

Sitenizde kartla ödeme (POST /v1/bookings/{code}/payments/card) sandbox'ta da çalışır: kart alanları canlıdaki gibi doğrulanır (Luhn, son kullanma, CVC) ve dönüş alan adı kontrol edilir, ama bankaya gidilmez — ödeme simulate-payment ile aynı yoldan işlenir ve yanıt doğrudan "paid" olur (3D Secure adımı yoktur). Test için Luhn'u geçen herhangi bir numara (ör. 4111111111111111) kullanılabilir.

Sitenizde PayPal ile ödeme sandbox'ta PayPal'a gitmez: GET …/payments/paypal "simulated": true ve clientId: null döner (SDK yüklemeyin; PayPal ayarından bağımsız, tutar rezervasyonun tutarıdır). …/paypal/order TEST- ile başlayan bir orderId döner; bunu …/paypal/capture'a gönderince ödeme simulate-payment ile aynı yoldan işlenir ve "paid" döner. Sayfanızda SDK yerine "Test: PayPal ile öde (taklit)" gibi bir buton gösterip bu iki çağrıyı yapabilirsiniz.

Webhook'lar

Panelde API & Webhook sayfasından bir HTTPS adresi girin; rezervasyonlarınızdaki her değişiklik bu adrese imzalı POST olarak gelir. İmza sırrı (whsec_…) yalnızca oluşturulduğunda bir kez gösterilir.

İstek

POST /ctt-webhook HTTP/1.1
Content-Type: application/json
User-Agent: CityTransferTurkey-Webhooks/1.0
X-CTT-Event: booking.confirmed
X-CTT-Delivery: 6f1c…            (her gönderimin kimliği — tekrarları ayıklamak için)
X-CTT-Signature: t=1763630000,v1=5a0d…

{ "id": "…", "event": "booking.confirmed", "createdAt": "2026-11-12T08:00:00Z",
  "livemode": true, "data": { "code": "CTT7K2M9Q", "status": "Confirmed", … } }

İmzayı doğrulama

v1 = hex( HMAC-SHA256( sır, t + "." + ham_gövde ) ). Gövdeyi JSON olarak çözmeden önce, ham haliyle doğrulayın ve t'nin son 5 dakika içinde olduğunu kontrol edin (tekrar saldırısına karşı).

const crypto = require("crypto");

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map(p => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

static bool Verify(string rawBody, string header, string secret)
{
    var parts = header.Split(',').Select(p => p.Split('=', 2)).ToDictionary(p => p[0], p => p[1]);
    if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - long.Parse(parts["t"])) > 300) return false;
    var hash = HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), Encoding.UTF8.GetBytes($"{parts["t"]}.{rawBody}"));
    var expected = Convert.ToHexString(hash).ToLowerInvariant();
    return CryptographicOperations.FixedTimeEquals(Encoding.ASCII.GetBytes(expected), Encoding.ASCII.GetBytes(parts["v1"]));
}

function verify(string $rawBody, string $header, string $secret): bool {
    parse_str(str_replace(',', '&', $header), $parts);
    if (abs(time() - (int)$parts['t']) > 300) return false;
    $expected = hash_hmac('sha256', $parts['t'] . '.' . $rawBody, $secret);
    return hash_equals($expected, $parts['v1']);
}

Teslim ve tekrar

Adresiniz 10 saniye içinde 2xx dönmelidir; dönmezse 1 dk, 5 dk, 15 dk, 30 dk, 1 sa, 3 sa, 6 sa, 12 sa aralıklarla 8 kez tekrar denenir. Yönlendirmeler (3xx) izlenmez. Aynı olay birden fazla gelebilir — X-CTT-Delivery ya da gövdedeki id ile ayıklayın; olaylar sırasız gelebilir, karar verirken data.status'a bakın. Başarısız gönderimleri panelden tekrar kuyruğa alabilirsiniz.

Cari hesap

GET /v1/account — bakiye (pozitif: bize borcunuz, negatif: alacağınız), kredi limiti, kullanılabilir tutar, vadesi geçmiş borç.

GET /v1/account/statement?from=…&to=…&page=1&pageSize=100 — hareket dökümü: rezervasyon borcu, komisyon alacağı, ödeme, geç iptal ücreti, ters kayıtlar ve yürüyen bakiye. Aylık ekstre ayrıca e-postanıza gönderilir.

Hatalar

Hatalar RFC 9457 application/problem+json biçimindedir; detail alanı insan için açıklamadır.

{ "type": "https://api.citytransferturkey.com/errors/business_rule",
  "title": "Business rule violation", "status": 422,
  "detail": "Kredi limiti aşılıyor. Kullanılabilir: 40,00 EUR, gereken: 108,00 EUR.",
  "traceId": "00-…" }

Hız sınırları

Sınır aşılınca 429 ve Retry-After başlığı döner. Teklif sonuçlarını kısa süre (≤30 dk) önbelleğe alarak istek sayınızı azaltabilirsiniz.

Acenta kullanıcı girişi

Kendi mobil uygulamanız ya da panel arayüzünüz için API anahtarı yerine acenta panelindeki kullanıcı e-posta/şifresiyle token alın. Token'la bütün /v1 uç noktaları aynı çalışır (yalnızca canlı mod).

POST /v1/auth/login     { "email": "ops@acenta.com", "password": "…", "deviceName": "iPhone" }
→ 200 { "accessToken": "cttm_…", "tokenType": "Bearer", "expiresAt": "…",
        "refreshToken": "cttr_…", "refreshTokenExpiresAt": "…" }

GET  /v1/bookings       Authorization: Bearer cttm_…
POST /v1/auth/refresh   { "refreshToken": "cttr_…" }   → yeni token çifti
POST /v1/auth/logout    { "refreshToken": "cttr_…" }   → 204

POST /v1/auth/2fa       { "challenge": "…", "code": "123456", "deviceName": "iPhone" }   → 200 token çifti

Mobil müşteri API'si

Tranigo mobil uygulaması içindir; web sitesindeki müşteri hesabıyla aynı hesap kullanılır. Tam referans: Swagger · Mobile API.

Dil: uygulama her isteğe X-App-Language: tr|en|de|es|fr başlığını ekler; sunucunun gönderdiği e-postalar (doğrulama kodu, şifre sıfırlama, talep onayı) bu dilde gider.

Uygulama bağlantıları: site /.well-known/apple-app-site-association (Apple Team ID + Bundle ID: Admin → Ayarlar → Apple ile Giriş) ve /.well-known/assetlinks.json (paket adı + imza SHA-256: Admin → Mobil Uygulama → Sürüm ayarları) dosyalarını yayınlar. E-postadaki rezervasyon ve değerlendirme bağlantıları uygulama kuruluysa uygulamada açılır.

Hız sınırı: uygulama her isteğe X-Installation-Id: <installationId> başlığını ekler. Giriş yapmamış mobil istekler IP yerine kurulum başına sınırlanır (dakikada 120; aynı IP için toplam 600 üst sınır). Başlık yoksa IP başına dakikada 30 geçerlidir.

Kurulum ve bildirimler: uygulama ilk açılışta bir installationId (GUID) üretip güvenli depoda saklar. Push token Firebase'den (FCM) alınır, iOS'ta da FCM token'ı gönderilir. Admin → Mobil Uygulama ekranı bu kayıtlarla hangi sürümde kimlerin olduğunu gösterir ve bildirim gönderir. Bildirimin data.url alanı uygulama içi adrestir (ör. /tours/…) ya da https bağlantısıdır.

Ödeme: rezervasyon yanıtındaki payment.url adresini uygulama içi tarayıcıda açın; müşteri kart, ön ödeme ya da nakit seçer. Durum payment.status alanındadır: awaiting_payment, paid, deposit_paid, pay_driver, refunded, none. Turda nakit seçilmişse pay_driver yerine pay_on_tour gelir (ücret turda ödenir).

Turlar

Akış: suggest ile şehir ya da kategori seçilir → tours listesi → tours/{id} detayı → quote ile kesin fiyat → tour-bookings. Fiyat her zaman sunucuda hesaplanır; rezervasyon da quote ile aynı hesabı kullanır. Tarih verilmezse bugün (Türkiye saati) kullanılır. Dil: en, tr, de, fr, es; tur o dilde yayında değilse İngilizcesi döner (fallbackCulture: "en").

Rezervasyonda tur birden çok kalkış saatine sahipse startTime (HH:mm), birden çok rehber diline sahipse guideLanguage zorunludur. Alış noktası olan turda pickupRegionId ya da pickupAddress verilmelidir. Ödenmemiş tur rezervasyonu kontenjanda 10 dakika yer tutar. 422 nedenleri: NotAvailable, InvalidPax, Closed, OverCapacity (remainingCapacity), TooLate, NoPrice, InvalidName, InvalidEmail, InvalidPhone, InvalidStartTime, InvalidGuideLanguage, InvalidPickup, TooLong, Busy (aynı anda başka rezervasyon işleniyor, tekrar deneyin), TooManyPending (müşterinin ödenmemiş 3 tur rezervasyonu var; birini ödeyin ya da 10 dakika bekleyin).

Uç nokta listesi (Partner API)

Sorularınız ve canlıya geçiş için: support@citytransferturkey.com