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
  }
}

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.

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

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