Tesis Entegrasyon

API Dokümantasyonu

v2.0

Şubat 2026

v2.0 Yayın Notları

iso_kodu doğrulama: iso_kodu alanı artık yalnızca ISO 3166-1 alpha-3 ülke kodu veya other kabul eder.
Tutar alanları float dönüşümü: gelir/tutar alanları dokümantasyonda integer yerine number (float) olarak belirtilmiştir.
Yanıtlarda versiyon bilgisi: /otel-veri yanıtlarına statik api_version alanı eklenmiştir.
satis_kanali doğrulaması: satis_kanali yalnızca acenta, online, bireysel veya other değerlerini kabul eder.

Sürüm (Versiyon) Yönetimi ve Entegrasyonu

TGA Tesis Entegrasyon Servisi, sürekli geliştirilen ve yeni kuralların/özelliklerin eklenebildiği dinamik bir yapıdır. Bu nedenle, API yanıtlarına (response) statik bir api_version alanı eklenmiştir.

PMS Firmalarından Beklenen Sürüm Kontrol Kurgusu

Tüm PMS firmalarının/entegratörlerin kendi sistemlerinde otomatik bir versiyon kontrol mekanizması (Alert/Uyarı Sistemi) kurmalarını tavsiye ederiz.

Versiyonun Kaydedilmesi: Entegrasyon yaptığınız güncel API versiyonunu (Örn: v2) sisteminizde statik olarak tutunuz.
Yanıt (Response) Kontrolü: TGA'ya gönderdiğiniz her başarılı günlük veri iletiminde, dönen yanıttaki api_version değerini kendi sisteminizdeki değer ile karşılaştırınız.
Uyarı (Alert) Mekanizması: Eğer TGA'dan dönen versiyon (Örn: v3), sizin sisteminizde kayıtlı olan versiyondan (Örn: v2) farklıysa, yazılımınızın IT/Geliştirici ekibinize otomatik bir uyarı (alert) üretmesi gerekmektedir.
Güncelleme Aksiyonu: Bu uyarıyı alan teknik ekiplerin ivedilikle Tesis Entegrasyon - API Dokümantasyonu adresini ziyaret ederek en güncel Yayın Notlarını (Release Notes) okuması, değişen kurallara veya yeni alanlara göre entegrasyon yapılarını güncellemeleri beklenmektedir.

Bu kurgu, entegrasyonunuzun ilerleyen dönemlerde sürekli hata almasını engelleyecek kritik bir güvenlik önlemidir.

Ortamlar

Ortam	Base URL
Test	`https://test-tesis-entegrasyon.tga.gov.tr`
Canlı	`https://tesis-entegrasyon.tga.gov.tr`

Tüm endpoint'ler yukarıdaki base URL'lere göre çağrılır (örn: https://tesis-entegrasyon.tga.gov.tr/otel-veri/).

Swagger / API Test Aracı

API'yi interaktif olarak test etmek için Swagger UI kullanabilirsiniz:

Ortam	Swagger URL
Test	`https://test-tesis-entegrasyon.tga.gov.tr/swagger`

Swagger Kullanımı:

/swagger adresinde sadece Otel Veri endpoint'i (/otel-veri/) dokümante edilmektedir.
Swagger üzerinden deneme yapmak için Authorize butonuna tıklayıp X-API-Key değerinizi girmeniz gerekmektedir.

Kimlik Doğrulama

Tüm API istekleri için API anahtarı gereklidir. API anahtarınız size özel olarak oluşturulmuş ve tarafınıza iletilmiştir.

Her istekte X-API-Key başlığı ile API anahtarınızı göndermeniz gerekmektedir:

X-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Önemli: API anahtarınızı güvenli bir şekilde saklayınız ve üçüncü şahıslarla paylaşmayınız. Sağlayıcı bilgisi API anahtarınız üzerinden otomatik olarak belirlenmektedir.

Otel Veri Gönderimi

POST /otel-veri/

Otel verilerini sisteme aktarır. Veriler asenkron olarak işlenmek üzere kuyruğa alınır.

İstek Başlıkları

Başlık	Değer	Açıklama
`Content-Type`	`application/json`	İstek formatı
`X-API-Key`	API anahtarınız	Kimlik doğrulama (zorunlu)

İstek Gövdesi

{
  "tesis_belge_no": "string",
  "vergi_no": "string",
  "data": [
    {
      "rapor_tarihi": "YYYY-MM-DD",
      "para_birimi": "TRY | USD | AUD | DKK | EUR | ... (izin verilen listeden biri)",
      "toplam_oda": integer,
      "toplam_kisi": integer,
      "net_oda_geliri": number (float),
      "vergi_tutari": number (float),
      "demografik_veriler": [
        {
          "iso_kodu": "ISO 3166-1 alpha-3 veya OTHER",
          "yetiskin": integer,
          "cocuk": integer,
          "oda": integer,
          "net_gelir": number (float)
        }
      ],
      "kanal_veriler": [
        {
          "satis_kanali": "Acenta | Online | Bireysel | Other",
          "oda": integer,
          "kisi": integer,
          "net_gelir": number (float)
        }
      ]
    }
  ]
}

İstek Alanları

Alan	Tip	Zorunlu	Açıklama
`tesis_belge_no`	string	Hayır	Tesis belge numarası
`vergi_no`	string	Evet	Vergi numarası (10-11 haneli, sadece rakam)
`data`	array	Evet	Veri dizisi

Veri Alanları

Alan	Tip	Zorunlu	Açıklama
`rapor_tarihi`	string	Evet	YYYY-MM-DD formatında rapor tarihi
`para_birimi`	string	Evet	Para birimi kodu; sadece izin verilen listedeki değerler kabul edilir (aşağıya bakınız)
`toplam_oda`	integer	Evet	Toplam oda sayısı
`toplam_kisi`	integer	Evet	Toplam kişi sayısı
`net_oda_geliri`	number (float)	Evet	Net oda geliri
`vergi_tutari`	number (float)	Evet	Vergi tutarı
`demografik_veriler`	array	Evet	Ülkeye göre demografik veriler
`kanal_veriler`	array	Evet	Satış kanalı verileri

Çoklu Para Birimi Desteği: Aynı rapor_tarihi için farklı para birimlerinde veri gönderilebilir. Her veri öğesi kendi para_birimi alanını taşır. Örneğin, aynı tarih için hem TRY hem USD cinsinden veriler ayrı veri öğeleri olarak gönderilebilir.

Demografik Veriler

Alan	Tip	Zorunlu	Açıklama
`iso_kodu`	string	Evet	Ülke kodu (strict ISO 3166-1 alpha-3) veya `OTHER`
`yetiskin`	integer	Evet	Yetişkin sayısı
`cocuk`	integer	Evet	Çocuk sayısı
`oda`	integer	Evet	Oda sayısı
`net_gelir`	number (float)	Evet	Net gelir

Kanal Veriler

Alan	Tip	Zorunlu	Açıklama
`satis_kanali`	string	Evet	Sadece şu değerler kabul edilir: Acenta, Online, Bireysel, Other
`oda`	integer	Evet	Oda sayısı
`kisi`	integer	Evet	Kişi sayısı
`net_gelir`	number (float)	Evet	Net gelir

Veri Tutarlılık ve Doğrulama Kuralları

Gönderilen her veri öğesi aşağıdaki kurallara uymalıdır. Bu kurallara uymayan istekler 422 hata koduyla reddedilir ve hatalar kayıt altına alınır.

1 Para Birimi (para_birimi)

para_birimi alanı yalnızca izin verilen para birimi kodlarından biri olmalıdır. İzin verilen kodlar: TRY, USD, AUD, DKK, EUR, GBP, CHF, SEK, CAD, KWD, NOK, SAR, JPY, RON, RUB, CNY, PKR, QAR, KRW, AZN, AED, KZT. Geçersiz değerlerde yanıt mesajı "Geçersiz para birimi" ve tip: "para_birimi_gecersiz" döner.

2 Ülke Kodu (iso_kodu)

iso_kodu alanı yalnızca strict ISO 3166-1 alpha-3 ülke kodu veya OTHER olabilir. Geçersiz değerler alan doğrulama hatası ile 422 döner.

3 Satış Kanalı (satis_kanali)

satis_kanali alanı yalnızca Acenta, Online, Bireysel veya Other değerlerinden biri olmalıdır. Geçersiz değerlerde yanıt mesajı "Geçersiz satış kanalı" ve tip: "satis_kanali_gecersiz" döner.

4 Oda Sayısı Dengesi

Toplam oda sayısı, demografik ve kanal bazlı oda sayıları toplamına eşit olmalıdır.

toplam_oda = Σ demografik_veriler.oda = Σ kanal_veriler.oda

5 Kişi Sayısı Dengesi

Toplam kişi sayısı, demografik yetişkin ve çocuk toplamına ve kanal kişi toplamına eşit olmalıdır.

toplam_kisi = Σ (demografik.yetiskin + demografik.cocuk) = Σ kanal_veriler.kisi

6 Gelir Dengesi

Net oda geliri, tüm kırılımların toplamına eşit olmalıdır.

net_oda_geliri = Σ demografik_veriler.net_gelir = Σ kanal_veriler.net_gelir

Yanıtlar

200 OK Başarılı Yanıt

{
  "api_version": "v2",
  "status": "success",
  "message": "Veriler başarıyla alındı",
  "data": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "errors": []
  }
}

request_id alanı, isteğinizi takip etmek için kullanılabilir. Başarılı yanıtta errors boş dizi döner.

401 Kimlik Doğrulama Hatası

{
  "api_version": "v2",
  "status": "error",
  "message": "API anahtarı eksik. Lütfen X-API-Key başlığını sağlayın.",
  "data": {
    "request_id": null,
    "errors": []
  }
}

403 Erişim Engeli

{
  "api_version": "v2",
  "status": "error",
  "message": "API erişimi iptal edilmiş. Lütfen destekle iletişime geçin.",
  "data": {
    "request_id": null,
    "errors": []
  }
}

422 Doğrulama Hatası

Alan doğrulama hatalarında:

{
  "api_version": "v2",
  "status": "error",
  "message": "Doğrulama hatası oluştu",
  "data": {
    "request_id": null,
    "errors": [
      {
        "alan": "vergi_no",
        "mesaj": "Bu alan zorunludur",
        "tip": "missing"
      }
    ]
  }
}

Geçersiz para birimi gönderildiğinde:

{
  "api_version": "v2",
  "status": "error",
  "message": "Geçersiz para birimi",
  "data": {
    "request_id": null,
    "errors": [
      {
        "alan": "data[0]",
        "tip": "para_birimi_gecersiz",
        "mesaj": "Geçersiz para birimi: 'XYZ'. İzin verilen değerler: AED, AUD, ..."
      }
    ]
  }
}

Geçersiz satış kanalı gönderildiğinde:

{
  "api_version": "v2",
  "status": "error",
  "message": "Geçersiz satış kanalı",
  "data": {
    "request_id": null,
    "errors": [
      {
        "alan": "data[0].kanal_veriler[0].satis_kanali",
        "tip": "satis_kanali_gecersiz",
        "mesaj": "Geçersiz satış kanalı: 'Foo'. İzin verilen değerler: acenta, online, bireysel, other"
      }
    ]
  }
}

Veri tutarlılık kuralı ihlallerinde:

{
  "api_version": "v2",
  "status": "error",
  "message": "Veri tutarlılık kontrolü başarısız",
  "data": {
    "request_id": null,
    "errors": [
      {
        "alan": "data[0]",
        "tip": "oda_dengesi",
        "mesaj": "Oda sayısı dengesi hatalı: toplam_oda=100, demografik oda toplamı=90, kanal oda toplamı=90"
      }
    ]
  }
}

Örnek: Çoklu Para Birimi

Aynı tarih için TRY ve USD cinsinden veri gönderimi:

cURL İsteği

curl -X POST https://tesis-entegrasyon.tga.gov.tr/otel-veri/ \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "tesis_belge_no": "TR-07-12345",
    "vergi_no": "1234567890",
    "data": [
      {
        "rapor_tarihi": "2025-10-20",
        "para_birimi": "TRY",
        "toplam_oda": 120,
        "toplam_kisi": 200,
        "net_oda_geliri": 50000,
        "vergi_tutari": 10000,
        "demografik_veriler": [
          { "iso_kodu": "TUR", "yetiskin": 80, "cocuk": 20, "oda": 60, "net_gelir": 25000 },
          { "iso_kodu": "DEU", "yetiskin": 50, "cocuk": 10, "oda": 35, "net_gelir": 15000 },
          { "iso_kodu": "GBR", "yetiskin": 30, "cocuk": 10, "oda": 25, "net_gelir": 10000 }
        ],
        "kanal_veriler": [
          { "satis_kanali": "Acenta", "oda": 50, "kisi": 90, "net_gelir": 22000 },
          { "satis_kanali": "Online", "oda": 45, "kisi": 70, "net_gelir": 18000 },
          { "satis_kanali": "Bireysel", "oda": 25, "kisi": 40, "net_gelir": 10000 }
        ]
      },
      {
        "rapor_tarihi": "2025-10-20",
        "para_birimi": "USD",
        "toplam_oda": 120,
        "toplam_kisi": 200,
        "net_oda_geliri": 1500,
        "vergi_tutari": 300,
        "demografik_veriler": [
          { "iso_kodu": "TUR", "yetiskin": 80, "cocuk": 20, "oda": 60, "net_gelir": 750 },
          { "iso_kodu": "DEU", "yetiskin": 50, "cocuk": 10, "oda": 35, "net_gelir": 450 },
          { "iso_kodu": "GBR", "yetiskin": 30, "cocuk": 10, "oda": 25, "net_gelir": 300 }
        ],
        "kanal_veriler": [
          { "satis_kanali": "Acenta", "oda": 50, "kisi": 90, "net_gelir": 660 },
          { "satis_kanali": "Online", "oda": 45, "kisi": 70, "net_gelir": 540 },
          { "satis_kanali": "Bireysel", "oda": 25, "kisi": 40, "net_gelir": 300 }
        ]
      },
      {
        "rapor_tarihi": "2025-10-21",
        "para_birimi": "TRY",
        "toplam_oda": 130,
        "toplam_kisi": 220,
        "net_oda_geliri": 55000,
        "vergi_tutari": 11000,
        "demografik_veriler": [
          { "iso_kodu": "TUR", "yetiskin": 90, "cocuk": 20, "oda": 65, "net_gelir": 28000 },
          { "iso_kodu": "DEU", "yetiskin": 55, "cocuk": 15, "oda": 40, "net_gelir": 17000 },
          { "iso_kodu": "GBR", "yetiskin": 30, "cocuk": 10, "oda": 25, "net_gelir": 10000 }
        ],
        "kanal_veriler": [
          { "satis_kanali": "Acenta", "oda": 55, "kisi": 100, "net_gelir": 24000 },
          { "satis_kanali": "Online", "oda": 50, "kisi": 80, "net_gelir": 21000 },
          { "satis_kanali": "Bireysel", "oda": 25, "kisi": 40, "net_gelir": 10000 }
        ]
      },
      {
        "rapor_tarihi": "2025-10-21",
        "para_birimi": "EUR",
        "toplam_oda": 130,
        "toplam_kisi": 220,
        "net_oda_geliri": 1400,
        "vergi_tutari": 280,
        "demografik_veriler": [
          { "iso_kodu": "TUR", "yetiskin": 90, "cocuk": 20, "oda": 65, "net_gelir": 700 },
          { "iso_kodu": "DEU", "yetiskin": 55, "cocuk": 15, "oda": 40, "net_gelir": 420 },
          { "iso_kodu": "GBR", "yetiskin": 30, "cocuk": 10, "oda": 25, "net_gelir": 280 }
        ],
        "kanal_veriler": [
          { "satis_kanali": "Acenta", "oda": 55, "kisi": 100, "net_gelir": 600 },
          { "satis_kanali": "Online", "oda": 50, "kisi": 80, "net_gelir": 520 },
          { "satis_kanali": "Bireysel", "oda": 25, "kisi": 40, "net_gelir": 280 }
        ]
      },
      {
        "rapor_tarihi": "2025-10-22",
        "para_birimi": "TRY",
        "toplam_oda": 110,
        "toplam_kisi": 180,
        "net_oda_geliri": 45000,
        "vergi_tutari": 9000,
        "demografik_veriler": [
          { "iso_kodu": "TUR", "yetiskin": 70, "cocuk": 20, "oda": 55, "net_gelir": 23000 },
          { "iso_kodu": "DEU", "yetiskin": 40, "cocuk": 10, "oda": 30, "net_gelir": 12000 },
          { "iso_kodu": "GBR", "yetiskin": 30, "cocuk": 10, "oda": 25, "net_gelir": 10000 }
        ],
        "kanal_veriler": [
          { "satis_kanali": "Acenta", "oda": 45, "kisi": 80, "net_gelir": 20000 },
          { "satis_kanali": "Online", "oda": 40, "kisi": 60, "net_gelir": 15000 },
          { "satis_kanali": "Bireysel", "oda": 25, "kisi": 40, "net_gelir": 10000 }
        ]
      },
      {
        "rapor_tarihi": "2025-10-22",
        "para_birimi": "USD",
        "toplam_oda": 110,
        "toplam_kisi": 180,
        "net_oda_geliri": 1350,
        "vergi_tutari": 270,
        "demografik_veriler": [
          { "iso_kodu": "TUR", "yetiskin": 70, "cocuk": 20, "oda": 55, "net_gelir": 690 },
          { "iso_kodu": "DEU", "yetiskin": 40, "cocuk": 10, "oda": 30, "net_gelir": 360 },
          { "iso_kodu": "GBR", "yetiskin": 30, "cocuk": 10, "oda": 25, "net_gelir": 300 }
        ],
        "kanal_veriler": [
          { "satis_kanali": "Acenta", "oda": 45, "kisi": 80, "net_gelir": 600 },
          { "satis_kanali": "Online", "oda": 40, "kisi": 60, "net_gelir": 450 },
          { "satis_kanali": "Bireysel", "oda": 25, "kisi": 40, "net_gelir": 300 }
        ]
      },
      {
        "rapor_tarihi": "2025-10-23",
        "para_birimi": "TRY",
        "toplam_oda": 140,
        "toplam_kisi": 240,
        "net_oda_geliri": 60000,
        "vergi_tutari": 12000,
        "demografik_veriler": [
          { "iso_kodu": "TUR", "yetiskin": 100, "cocuk": 20, "oda": 70, "net_gelir": 30000 },
          { "iso_kodu": "DEU", "yetiskin": 60, "cocuk": 15, "oda": 40, "net_gelir": 18000 },
          { "iso_kodu": "GBR", "yetiskin": 35, "cocuk": 10, "oda": 30, "net_gelir": 12000 }
        ],
        "kanal_veriler": [
          { "satis_kanali": "Acenta", "oda": 60, "kisi": 110, "net_gelir": 26000 },
          { "satis_kanali": "Online", "oda": 50, "kisi": 85, "net_gelir": 22000 },
          { "satis_kanali": "Bireysel", "oda": 30, "kisi": 45, "net_gelir": 12000 }
        ]
      },
      {
        "rapor_tarihi": "2025-10-24",
        "para_birimi": "TRY",
        "toplam_oda": 135,
        "toplam_kisi": 230,
        "net_oda_geliri": 58000,
        "vergi_tutari": 11600,
        "demografik_veriler": [
          { "iso_kodu": "TUR", "yetiskin": 95, "cocuk": 25, "oda": 70, "net_gelir": 30000 },
          { "iso_kodu": "DEU", "yetiskin": 50, "cocuk": 10, "oda": 35, "net_gelir": 16000 },
          { "iso_kodu": "GBR", "yetiskin": 40, "cocuk": 10, "oda": 30, "net_gelir": 12000 }
        ],
        "kanal_veriler": [
          { "satis_kanali": "Acenta", "oda": 55, "kisi": 100, "net_gelir": 25000 },
          { "satis_kanali": "Online", "oda": 50, "kisi": 85, "net_gelir": 21000 },
          { "satis_kanali": "Bireysel", "oda": 30, "kisi": 45, "net_gelir": 12000 }
        ]
      },
      {
        "rapor_tarihi": "2025-10-24",
        "para_birimi": "USD",
        "toplam_oda": 135,
        "toplam_kisi": 230,
        "net_oda_geliri": 1740,
        "vergi_tutari": 348,
        "demografik_veriler": [
          { "iso_kodu": "TUR", "yetiskin": 95, "cocuk": 25, "oda": 70, "net_gelir": 900 },
          { "iso_kodu": "DEU", "yetiskin": 50, "cocuk": 10, "oda": 35, "net_gelir": 480 },
          { "iso_kodu": "GBR", "yetiskin": 40, "cocuk": 10, "oda": 30, "net_gelir": 360 }
        ],
        "kanal_veriler": [
          { "satis_kanali": "Acenta", "oda": 55, "kisi": 100, "net_gelir": 750 },
          { "satis_kanali": "Online", "oda": 50, "kisi": 85, "net_gelir": 630 },
          { "satis_kanali": "Bireysel", "oda": 30, "kisi": 45, "net_gelir": 360 }
        ]
      },
      {
        "rapor_tarihi": "2025-10-25",
        "para_birimi": "TRY",
        "toplam_oda": 125,
        "toplam_kisi": 210,
        "net_oda_geliri": 52000,
        "vergi_tutari": 10400,
        "demografik_veriler": [
          { "iso_kodu": "TUR", "yetiskin": 85, "cocuk": 25, "oda": 65, "net_gelir": 27000 },
          { "iso_kodu": "DEU", "yetiskin": 45, "cocuk": 10, "oda": 35, "net_gelir": 15000 },
          { "iso_kodu": "GBR", "yetiskin": 35, "cocuk": 10, "oda": 25, "net_gelir": 10000 }
        ],
        "kanal_veriler": [
          { "satis_kanali": "Acenta", "oda": 50, "kisi": 95, "net_gelir": 23000 },
          { "satis_kanali": "Online", "oda": 50, "kisi": 75, "net_gelir": 19000 },
          { "satis_kanali": "Bireysel", "oda": 25, "kisi": 40, "net_gelir": 10000 }
        ]
      },
      {
        "rapor_tarihi": "2025-10-26",
        "para_birimi": "TRY",
        "toplam_oda": 100,
        "toplam_kisi": 160,
        "net_oda_geliri": 40000,
        "vergi_tutari": 8000,
        "demografik_veriler": [
          { "iso_kodu": "TUR", "yetiskin": 60, "cocuk": 20, "oda": 50, "net_gelir": 20000 },
          { "iso_kodu": "DEU", "yetiskin": 35, "cocuk": 10, "oda": 30, "net_gelir": 12000 },
          { "iso_kodu": "GBR", "yetiskin": 25, "cocuk": 10, "oda": 20, "net_gelir": 8000 }
        ],
        "kanal_veriler": [
          { "satis_kanali": "Acenta", "oda": 40, "kisi": 70, "net_gelir": 17000 },
          { "satis_kanali": "Online", "oda": 35, "kisi": 55, "net_gelir": 13000 },
          { "satis_kanali": "Bireysel", "oda": 25, "kisi": 35, "net_gelir": 10000 }
        ]
      },
      {
        "rapor_tarihi": "2025-10-26",
        "para_birimi": "EUR",
        "toplam_oda": 100,
        "toplam_kisi": 160,
        "net_oda_geliri": 1100,
        "vergi_tutari": 220,
        "demografik_veriler": [
          { "iso_kodu": "TUR", "yetiskin": 60, "cocuk": 20, "oda": 50, "net_gelir": 550 },
          { "iso_kodu": "DEU", "yetiskin": 35, "cocuk": 10, "oda": 30, "net_gelir": 330 },
          { "iso_kodu": "GBR", "yetiskin": 25, "cocuk": 10, "oda": 20, "net_gelir": 220 }
        ],
        "kanal_veriler": [
          { "satis_kanali": "Acenta", "oda": 40, "kisi": 70, "net_gelir": 470 },
          { "satis_kanali": "Online", "oda": 35, "kisi": 55, "net_gelir": 410 },
          { "satis_kanali": "Bireysel", "oda": 25, "kisi": 35, "net_gelir": 220 }
        ]
      }
    ]
  }'

Beklenen Yanıt

{
  "api_version": "v2",
  "status": "success",
  "message": "Veriler başarıyla alındı",
  "data": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "errors": []
  }
}