Giriş

Turasistan API; tur kataloğu, cari kayıtları, rezervasyon, tahsilat–ödeme ve muhasebe aktarımlarını tek bir REST arayüzünde sunar. Bu doküman kimlik doğrulama, uç noktalar, veri modelleri ve canlıya geçiş adımlarını kapsar.

Base URL

prod.turasistan.com

Yol öneki

/api/v2

Kimlik

APIKEY · Bearer JWT

Biçim

application/json

Limit

100 istek / dakika

Tarih

ISO-8601

Hızlı başlangıç

Aşağıdaki dört adımı tamamladığınızda canlı veriye erişen çalışan bir istemciniz olur.

1. Anahtar üretin

   Turasistan uygulamasında Ayarlar → API Anahtarlarım → API Anahtarı Üret. Form iki zorunlu alan ister:

   • Şirket(ler) — anahtarın hangi şirket kapsamında veri göreceği.
   • İzin verilen IP adresleri — isteği yapacak sunucunuzun çıkış (egress) IP'si, virgülle ayrılmış.

   Anahtar üretimi kullanıcı oturumu (JWT) gerektirir; bir API Key ile yeni API Key üretilemez. Firma (tenant) başına en fazla 5 aktif anahtar tutulabilir ve profilden üretilen anahtarların ömrü 1 yıldır.

2. Bağlantıyı doğrulayın

   Hafif bir uç ile başlayın. 200 dönüyorsa anahtar geçerli, IP izinli ve uç erişiminize açıktır.

   cURLGoNode.jsPythonC#

   curl -s -i "https://prod.turasistan.com/api/v2/UsedCurrencies?take=5" \
     -H "APIKEY: $TURASISTAN_API_KEY" \
     -H "Accept: application/json"

   // Minimal connectivity check.
   package main
   
   import (
   	"fmt"
   	"net/http"
   	"os"
   	"time"
   )
   
   func main() {
   	client := &http.Client{Timeout: 30 * time.Second}
   
   	req, _ := http.NewRequest(http.MethodGet,
   		"https://prod.turasistan.com/api/v2/UsedCurrencies?take=5", nil)
   	req.Header.Set("APIKEY", os.Getenv("TURASISTAN_API_KEY"))
   	req.Header.Set("Accept", "application/json")
   
   	resp, err := client.Do(req)
   	if err != nil {
   		panic(err)
   	}
   	defer resp.Body.Close()
   
   	fmt.Println("status:", resp.StatusCode)
   }

   // Minimal connectivity check.
   const res = await fetch(
     "https://prod.turasistan.com/api/v2/UsedCurrencies?take=5",
     { headers: { APIKEY: process.env.TURASISTAN_API_KEY, Accept: "application/json" } }
   );
   
   console.log(res.status, await res.json());

   # Minimal connectivity check.
   import os, requests
   
   res = requests.get(
       "https://prod.turasistan.com/api/v2/UsedCurrencies",
       params={"take": 5},
       headers={"APIKEY": os.environ["TURASISTAN_API_KEY"]},
       timeout=30,
   )
   print(res.status_code, res.json())

   // Minimal connectivity check.
   using var client = new HttpClient { BaseAddress = new Uri("https://prod.turasistan.com/") };
   client.DefaultRequestHeaders.Add("APIKEY", Environment.GetEnvironmentVariable("TURASISTAN_API_KEY"));
   
   var response = await client.GetAsync("api/v2/UsedCurrencies?take=5");
   Console.WriteLine((int)response.StatusCode);

3. Bir liste ucundan veri çekin

   Liste uçları aynı ızgara (grid) sözleşmesini kullanır: skip/take ile sayfalama, alan_operatör biçiminde filtre, alan_sort ile sıralama.

   curl -s "https://prod.turasistan.com/api/v2/Tours?take=20&skip=0&isActive_eq=true&startDate_gte=2026-08-01&startDate_sort=asc" \
     -H "APIKEY: $TURASISTAN_API_KEY"

   {
     "data": [
       {
         "id": 4821,
         "name": "Umre Programı — Ağustos",
         "tourCode": "UMR-0825",
         "startDate": "2026-08-14T00:00:00",
         "finishDate": "2026-08-28T00:00:00",
         "capacity": 90,
         "customerCount": 63,
         "remainingQuota": 27,
         "currencyId": 2,
         "currencySymbol": "$",
         "isActive": true,
         "isClosed": false,
         "tourPricePackages": [
           { "id": 9912, "name": "4 Kişilik Oda", "price": 1850, "discountStudentPrice": 1700 }
         ]
       }
     ],
     "count": 137
   }

4. Yazma işlemine geçin

   Yazma uçları application/json gövde bekler ve doğrulama hatalarını gövdede döner. Rezervasyon akışının tamamı için Rezervasyon oluşturma senaryosuna bakın.

   curl -s -X POST "https://prod.turasistan.com/api/v2/Customers" \
     -H "APIKEY: $TURASISTAN_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "name": "Ahmet", "surname": "Yılmaz", "isActive": true, "isDealer": false }'

   { "id": 51204, "customerNumber": 10387 }

Kimlik doğrulama

API iki şema destekler. Sunucudan sunucuya entegrasyonlarda API Key kullanın; JWT yalnızca son kullanıcı oturumu olan uygulamalar içindir.

Şemalar

Başlıkta anahtar yoksa istek anonim sayılır ve korumalı uçlar 401 döner.

Yetki kapsamı

Anahtar, oluşturulduğu tenant ve seçilen şirketler ile sınırlıdır. İsteklerde tenant veya şirket parametresi göndermezsiniz; kapsam anahtardan çözülür. Farklı şirketler için ayrı anahtar üretin — bu, bir anahtarın sızması durumundaki etkiyi de sınırlar.

IP kısıtlaması

• Liste virgülle ayrılır: 203.0.113.10,203.0.113.11
• Karşılaştırma birebir metin eşleşmesidir. CIDR (203.0.113.0/24), aralık veya joker desteklenmez.
• Sunucunun gördüğü istemci IP'si ile karşılaştırılır. NAT, proxy veya yük dengeleyici arkasındaysanız listeye çıkış (egress) IP'nizi yazın, yerel adresi değil.
• IPv6 üzerinden çıkıyorsanız IPv6 adresini de ekleyin; aksi halde istek bloklanır.

IP değiştirme: profil akışında var olan bir anahtarın IP listesini güncelleyen bir uç yoktur. Çıkış IP'niz değişecekse yeni IP ile ikinci bir anahtar üretip geçiş yapın, sonra eskisini silin. Silme anında etkilidir.

Anahtar yaşam döngüsü

İstek kuralları

Adresleme

Tüm uçlar https://prod.turasistan.com/api/v2 altındadır. Yol segmentleri büyük/küçük harf duyarlıdır: /api/v2/Tours doğrudur, /api/v2/tours yönlendirme yapılandırmasına göre farklı davranabilir — spesifikasyondaki yazımı birebir kullanın.

Başlıklar

* Anonim erişime açık bir uç kullanmıyorsanız zorunludur.

Veri türleri

Yanıt biçimleri

API'de üç yanıt kalıbı vardır. İstemcinizde önce HTTP durum kodunu, sonra gövdeyi okuyun; gövde biçimi kalıba göre değişir.

1 · Izgara sonucu (GridResult)

Sayfalanabilir tüm liste uçları bu kalıbı döner. count filtreye uyan toplam satır sayısıdır, sayfadaki satır sayısı değil.

{
  "data": [ { "id": 1, "name": "..." } ],
  "count": 137
}

/AccountingDebitCredits gibi bazı uçlar ek olarak bir summary nesnesi taşır:

{
  "data": [ /* ... */ ],
  "count": 4210,
  "summary": {
    "totalDebit": 1284500.00,
    "totalCredit": 1190320.50,
    "totalBalance": 94179.50,
    "currencyId": 1,
    "currencyCode": "TRY"
  }
}

2 · Servis sonucu (ServiceResult)

Zarflı kalıp. /Tours/active-tours gibi uçlarda ve doğrulama geri bildiriminde kullanılır.

{
  "isSuccess": true,
  "message": "İşlem başarılı",
  "data": [ /* ... */ ],
  "meta": { "totalCount": 137, "page": 1, "pageSize": 20, "totalPages": 7, "hasNext": true, "hasPrevious": false },
  "validationErrors": null
}

3 · Çıplak nesne / dizi

Detay uçları (GET /Tours/{id}), autocomplete uçları ve hesaplama uçları zarfsız döner: doğrudan nesne, dizi veya skaler (ör. /ExChangeRates/rate bir double döner).

Boş yanıtlar

Sayfalama, filtreleme ve sıralama

Izgara uçları tek bir sorgu dili paylaşır: alan + _operatör. Aynı kural bütün liste uçlarında geçerlidir; alan adları yanıt DTO'sundaki alan adlarıyla birebir aynıdır.

Ortak parametreler

Operatör soneki tablosu

Örnekler

# Belirli tarih aralığında, kotası kalan, arşivlenmemiş turlar
GET /api/v2/Tours?startDate_gte=2026-08-01&startDate_lte=2026-09-30
    &remainingQuota_gt=0&isArchive_eq=false&startDate_sort=asc&take=50

# Yalnızca toplam sayı (satır dönmez)
GET /api/v2/Customers?count=true&isBlacklist_eq=true

# TCKN ile cari hareket araması, tur adına göre azalan
GET /api/v2/AccountingDebitCredits?customerNationalityNumber_eq=11111111110
    &documentDate_gte=2026-01-01&tourName_sort=desc&take=100

# Çoklu kimlik filtresi + özet
GET /api/v2/AccountingDebitCredits?accountingTagIds_in=1,2,7&includeSummary=true
    &summaryCurrencyId=2

Deterministik sayfalama

Sıralama vermezseniz sayfalar arasında satır tekrarlanabilir veya atlanabilir. Sayfalı gezinmede daima tekil bir alan üzerinden sıralayın — genelde id_sort=asc yeterlidir.

Hata yönetimi

Durum kodları

Hata gövdeleri

Kimlik doğrulama hataları ile iş katmanı hataları farklı gövde biçimi kullanır.

Yeniden deneme politikası

• Tekrar deneyin: 429 (kısa bekleme sonrası), 500/502/503/504, ağ zaman aşımları. Üstel geri çekilme + jitter kullanın.
• Tekrar denemeyin: 400, 401, 403, 404. Bunlar istek düzeltilmeden çözülmez.
• Yazma uçlarında dikkat: API sunucu tarafı idempotency anahtarı taşımaz. Zaman aşımına uğrayan bir POST'u körlemesine tekrarlamak çift kayıt üretebilir. Önce ilgili liste ucunda kendi referans numaranızla (documentNumber, transactionNumber, voucherNo) arama yapıp kaydın oluşup oluşmadığını doğrulayın.

// Retry policy: only transient failures are retried.
func shouldRetry(status int) bool {
	return status == 429 || status >= 500
}

// Before retrying a write, verify the record was not already created.
// Search by your own reference: documentNumber / transactionNumber / voucherNo.

Limitler ve performans

Hız limiti

Hacim sınırları

Verimli kullanım

• Referans verisini önbellekleyin. /AdminDatas/cache, /Places/from-cache, /Languages, /UsedCurrencies ve /Translates/locale-messages nadiren değişir; günde bir kez çekip kendi tarafınızda saklayın.
• Delta çekin. Tam senkron yerine createdDate_gte / editedDate_gte ile son çalıştırmadan bu yana değişenleri alın.
• Toplu uçları tercih edin. Gider, virman ve görsel yüklemeleri dizi kabul eder; N istek yerine tek istek gönderin.
• Sadece sayıyı istiyorsanız count=true kullanın; satır taşımayın.
• Toplu veri çekiminde istekler arasına gecikme koyun ve skip/take ile sayfalayın.

Uçtan uca senaryolar

B2B entegrasyonlarının büyük çoğunluğu aşağıdaki altı akıştan birine denk gelir. Her akış, çağrı sırası ve dikkat edilecek noktalarla birlikte verilmiştir.

1 · Tur kataloğu senkronu

Kendi web sitenizde veya acente panelinizde satılabilir turları göstermek için.

Kendi web sitenizi besliyorsanız domain tabanlı uç daha pratiktir: GET /Tours/tourism-web?domain=example.com lisansı domainden çözer ve web'de gösterilmek üzere işaretlenmiş turları tam fiyat/güzergâh grafiğiyle döner. Kontenjan göstergeleri için GET /Tours/tourism-web/reservation-counts?domain=example.com.

curl -s "https://prod.turasistan.com/api/v2/Tours/sales?StartDate=2026-08-01&Category=umre" \
  -H "APIKEY: $TURASISTAN_API_KEY"

2 · Rezervasyon oluşturma

Turasistan'da rezervasyon TravelGroup (seyahat grubu) olarak modellenir: bir fatura müşterisi, bir tur ve bir veya daha fazla yolcu satırı.

{
  "tourId": 4821,
  "dealerId": 3310,
  "tourReservationStatusId": 121,
  "invoiceCustomer": {
    "id": 0,
    "name": "Ahmet",
    "surname": "Yılmaz",
    "nationalityNumber": "11111111110",
    "gsm": "5321112233",
    "email": "ahmet@example.com"
  },
  "travelGroupCustomers": [
    {
      "tourId": 4821,
      "tourPricePackageId": 9912,
      "noBed": false,
      "customer": {
        "id": 0,
        "name": "Ahmet",
        "surname": "Yılmaz",
        "nationalityNumber": "11111111110",
        "birthDate": "1985-03-14T00:00:00",
        "genderId": 41,
        "passportNumber": "U01234567",
        "passportExpiryDate": "2030-06-01T00:00:00"
      },
      "travelGroupCustomer_VisaTypes": [ { "tourVisaTypeId": 77 } ],
      "travelGroupCustomer_TourExtras": [ { "tourTourExtraId": 512 } ]
    }
  ],
  "travelGroupHotelInfos": [],
  "travelGroupFlightInfos": []
}

• tourPricePackageId, satır isDelete ile işaretlenmediği sürece zorunludur.
• Var olan müşteri için customerId gönderin; yeni müşteri için customer nesnesini id: 0 ile gönderin.
• mahramId / mahramTypeId, mahramControl açık turlarda gereklidir.
• calculate-amount yanıtındaki totalAmount ve satır amount/discount değerlerini olduğu gibi kaydetme isteğine taşıyın.

3 · Tahsilat ve ödeme kaydı

Ödeme aracına göre ayrı uçlar vardır; hepsi aynı borç/alacak gövdesini paylaşır.

Hesap (kasa/banka/POS) kimliklerini önce çözün:

GET /api/v2/AccountCasePoses?isActive_eq=true&companyId_eq=7&take=100
GET /api/v2/AccountCasePoses/my-account-cases?typeId=3

// POST /api/v2/CaseDebitCredits — cash collection
{
  "documentNumber": "THS-2026-000412",
  "transactionNumber": "ERP-88121",
  "documentDate": "2026-07-31T00:00:00+03:00",
  "description": "Umre programı 1. taksit",
  "isCollect": true,
  "debit": null,
  "credit": 15000.00,
  "currencyId": 1,
  "exchangeRate": 1,
  "accountCasePosId": 44,
  "customerId": 51204,
  "tourId": 4821,
  "companyId": 7,
  "isLegal": true,
  "tags": [ { "id": 0, "accountingTagId": 3 } ]
}

• isCollect: true → tahsilat (makbuz); false → ödeme.
• Bir satırda ya debit ya da credit dolu olur.
• Yabancı para girişlerinde currencyId + exchangeRate gönderin; raporlama tutarını sunucunun hesaplaması için reportingCurrencyId bırakılabilir.
• documentNumber kendi referansınızdır; mutabakat ve tekrar denemede bunu kullanın.

4 · Cari hareket ve bakiye

Muhasebe hareketleri tek bir ızgara ucundan okunur; özet blok filtrelenmiş küme için toplam borç, alacak ve bakiyeyi verir.

GET /api/v2/AccountingDebitCredits
    ?customerId_eq=51204
    &documentDate_gte=2026-01-01&documentDate_lte=2026-12-31
    &includeSummary=true&summaryCurrencyId=1
    &documentDate_sort=desc&take=100

5 · Kur ve parite

6 · Logo ERP aktarımı

Muhasebe entegrasyonu iki yönlüdür: aktarılacak kayıtları çekersiniz, aktarım sonrası referans kodunu geri yazarsınız.

1. Aktarılacakları çekin

   GET /api/v2/AccountingDebitCreditsBeyGroup/GetLogoTransferDatas
       ?startDate=2026-07-01T00:00:00&endDate=2026-08-01T00:00:00
       &onlyNotTransfered=true&logoFirmCode=001

   Tarih aralığı başlangıç dahil, bitiş hariçtir. Yanıt en fazla 10.000 kayıt içerir; aşarsa istek reddedilir, aralığı daraltın.

2. Referans kodunu geri yazın

   PUT /api/v2/AccountingDebitCreditsBeyGroup/{id}
   { "logoReferenceCode": "MUH-2026-000913" }   // max 128 karakter; boş göndermek değeri temizler

3. Aktarım durumunu izleyin

   GET /api/v2/LogoUpdatedRecordss?transferred_eq=false&documentsDate_gte=2026-07-01
   GET /api/v2/LogoUpdatedRecordss/current-transactions/{tckn}

   İkinci uç, aktif şirketlere bağlı Logo veritabanlarını sorgular. Kimlik numarası biçimi geçersizse boş liste döner.

Uç nokta dizini

Tüm public uçlar. Bir satırı açtığınızda solda parametreler ve yanıt tipi, sağda çalıştırılabilir kod örneği (cURL · Node.js · Python · C#) görünür. Genel ızgara parametreleri (skip, take, count, includeInactive, includeSummary) ve operatör sonekleri her liste ucunda geçerlidir — tekrar edilmemiştir.

Örneklerdeki gövdeler temsilîdir: sık kullanılan alanları gösterir, şemanın tamamı değildir. Alanların tam listesi için Swagger şemasına bakın. Anahtarı ortam değişkeninden okuyun (TURASISTAN_API_KEY); koda gömmeyin.

Veri modelleri

En sık kullanılan gövde ve yanıt nesneleri. Alan adları yanıtta ve filtrede birebir aynıdır.

Tur (TourResponseDto — liste)

Detay yanıtı (TourReadDto) bunlara ek olarak tourItineraries, tourHotelItineraries, tourTravelPackages, tourVisaTypes, tourChildAges, tourGifts ve tour_Dealers koleksiyonlarını taşır.

Müşteri (CustomerResponseDto — liste)

Borç/alacak gövdesi (tahsilat–ödeme uçları)

Rezervasyon (TravelGroup)

Yolcu satırı (travelGroupCustomers[]) başlıca alanları: customerId veya customer, tourPricePackageId, amount, discount, noBed, mahramId, mahramTypeId, togetherCustomerId, nearsideCode, vehicleNumber, giftId, notlar (flightDescription, roomingDescription, visaDescription, invoiceDescription) ve bağ dizileri (_VisaTypes, _TourExtras, _Discounts, customerVisaDocuments).

Sabit listeler

Kimlik değerleri tenant'a göre değişebildiğinden sayısal kimlikleri koda gömmeyin. Sabit listeleri ilgili uçtan çekip önbelleğe alın.

Nereden çekilir

dataType değerleri (AdminDataType)

Unit MartialStatus CompanyType TransportType Gender AccountCaseType MilitaryStatus HRStatus DisabledStatus Graduation HotelContractType HotelContractPriceCalculateMethod PricePreference CustomerTitle ItineraryType MofaAccountType SalaryPeriod WorkingMode HotelRequestStatus TaskList TypeByAge MahramType PassportStatus VisaSalesStatus FlyingType ReservationStatus MealBoardType TourReservationStatus RoomType Meal CustomerType AccountingDCType Education FormType DayType ChatType TourType OfferStatus DiscountType EmailType PassportType SaleType StokActionType StokType AccountActionType DibAccountType OperationType QueryType InvoiceType StokKind FlightPassengerType GearBoxType FuelType CustomerRecordType ReservationRecordType TypeOfModule ContractType Priority TourDiscountType VisaEntryType VehicleType PricingTiers RavzaPricingTiers RavzaAppointmentStatus CouponSaasAppFilterType RavzaGroupStatus ConversationStatus ConversationType HowFindUs Job

Ayrıca tenant'a özel listeler (SaasAppDataType) vardır: AccountingTag, DealerZone, RoomKind, VisaType, TourSeason, DocumentName, CustomerGroup, MealFood, LeavesType vb.

Kod içi sabitler

Alan sözlüğü

API'de sık geçen ve alan adından anlaşılmayan kavramlar.

Canlıya geçiş kontrol listesi

SSS

Base URL /api/v2 ama sürüm v3 yazıyor, hangisi doğru?

Yol öneki /api/v2'dir ve tüm uçlar bunun altındadır. Spesifikasyon başlığındaki sürüm etiketi dokümantasyon sürümüdür; istek adresini değiştirmez.

Bir anahtarla birden fazla şirketin verisini görebilir miyim?

Evet, anahtar üretilirken seçilen şirketler kapsam olur. Ancak izolasyon ve sızıntı etkisini sınırlamak için şirket başına ayrı anahtar önerilir.

Var olan bir anahtarın IP listesini nasıl güncellerim?

Profil akışında güncelleme ucu yoktur. Yeni IP ile ikinci bir anahtar üretip geçiş yapın, sonra eskisini silin.

Bir uç 403 dönüyor, anahtarım geçerli.

403 ucun public API kapsamında olmadığını gösterir. Swagger'daki listeyi kontrol edin; benzer işi yapan bir public uç genellikle vardır (ör. dahili ızgara yerine /Tours/sales).

Fiyatı kendim hesaplayabilir miyim?

Hesaplamayın. İndirim, çocuk fiyatı, yataksız, vize ve ekstra kombinasyonları sunucuda çözülür. POST /TravelGroups/calculate-amount ile hesaplatın ve dönen değerleri kaydedin.

count alanı sayfadaki satır sayısıyla uyuşmuyor.

Beklenen davranış. count, filtreye uyan toplam satır sayısıdır; data ise geçerli sayfadır.

Sayfalar arasında aynı kaydı iki kez görüyorum.

Sıralama vermemişsiniz. id_sort=asc ekleyin.

Yeni bir müşteri oluşturduğumda customerNumber neden bazen boş?

Müşteri numarası atama, mükerrer numarayı önlemek için dağıtık kilit altında serileştirilir. Yanıtta gelmezse kaydı id ile tekrar okuyun.

Görselleri nasıl yüklerim?

Toplu uçlar Base64 kabul eder: /Customers/images/batch, /passport-images/batch, /residence-permit-images/batch, /vaccination-images/batch. Web formu uçları ise multipart/form-data kullanır.

Zaman aşımına uğrayan bir tahsilat isteğini tekrar gönderebilir miyim?

Önce GET /AccountingDebitCredits?documentNumber_eq=... ile kaydın oluşup oluşmadığını doğrulayın. API idempotency anahtarı taşımaz.

Destek ve sürüm

Sorun bildirirken

Aşağıdaki bilgileri iletmek çözüm süresini belirgin şekilde kısaltır:

• İstek zamanı (UTC+3) ve endpoint yolu
• HTTP durum kodu ve yanıt gövdesi
• İstek yapan sunucunun çıkış (egress) IP'si
• Gönderilen gövdenin kişisel veri maskelenmiş hâli

Sürüm politikası

Canlı ve her zaman güncel şema: Swagger arayüzü · docs.turasistan.com