Tesis Entegrasyon

API Dokümantasyonu

Mayıs 2026

v4 Yayın Notları

Uyumsuz değişiklik (Breaking Change). Günlük veri gönderim endpoint'i POST /otel-veri/ kaldırılmıştır. Bu adrese gönderilen istekler artık 410 Gone kodu ve status: "error" ile yanıtlanır; istek gövdesi doğrulanmaz. Tüm entegrasyonlar POST /tesis-aylik-veri/ üzerinden aylık veri göndermeli ve yanıtlarda api_version alanını v4 olarak okumalıdır.

Yeni istek gövdesi alanları: tesis_belge_no ve vergi_no zorunludur; rapor_tarihi ay bazında (YYYY-MM) gönderilir; tesis_acik_mi zorunludur. Açık tesislerde data en az bir satır içermeli, kapalı tesislerde boş dizi olmalıdır.
data satırı (ülke kırılımı): Her öğede iso_kodu; hafta içi / hafta sonu haftaici_toplam_giris_yapan_misafir, haftasonu_toplam_giris_yapan_misafir; haftaici_toplam_geceleme, haftasonu_toplam_geceleme; haftaici_toplam_satilan_oda_gece, haftasonu_toplam_satilan_oda_gece; ortalama_fiyat; ve ay içindeki açık gün sayısı için tesisin_aylik_acik_oldugu_gun_sayisi (1–31 arası tam sayı) bulunur.
Tek para birimi: İstemci, aylık ortalama fiyatı tek bir para birimine çevirerek (EUR) ortalama_fiyat alanında gönderir. para_birimi alanı bu endpointte yer almaz.
Güncelleme Mekanizması: Aynı tesis_belge_no ve rapor_tarihi çifti için gönderilen yeni veriler, daha önce kaydedilmiş kayıtları günceller. Düzeltme gönderimleri bu mekanizma ile yapılır.

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 (ör. v4) sisteminizde statik olarak tutunuz.
Yanıt (Response) Kontrolü: TGA'ya gönderdiğiniz her başarılı veri iletiminde, dönen yanıttaki api_version değerini kendi sisteminizdeki değer ile karşılaştırınız.
Uyarı (Alert) Mekanizması: TGA'dan dönen api_version (ör. v4), sizde kayıtlı sürümden (ör. v3) farklıysa IT/geliştirici ekibinize otomatik uyarı üretmeniz beklenir.
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/tesis-aylik-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 Tesis Aylık Veri endpoint'i (/tesis-aylik-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.

Tesis Aylık Veri Gönderimi

POST /tesis-aylik-veri/

İ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": "1234-07-1234",
  "vergi_no": "string",
  "rapor_tarihi": "YYYY-MM",
  "tesis_acik_mi": true | false,
  "data": [
    {
      "iso_kodu": "ISO 3166-1 alpha-3 veya OTHER",
      "haftaici_toplam_giris_yapan_misafir": integer,
      "haftasonu_toplam_giris_yapan_misafir": integer,
      "haftaici_toplam_geceleme": integer,
      "haftasonu_toplam_geceleme": integer,
      "haftaici_toplam_satilan_oda_gece": integer,
      "haftasonu_toplam_satilan_oda_gece": integer,
      "ortalama_fiyat": number (float),
      "tesisin_aylik_acik_oldugu_gun_sayisi": integer
    }
  ]
}

İstek Alanları (kök)

Alan	Tip	Zorunlu	Açıklama
`tesis_belge_no`	string	Evet	Tesis belge numarası. İki biçimden biri: `NNNN-NN-NNNN` (yalnız rakam ve tire) veya 1–5 haneli rakam, 0 ile başlamaz (ör. `12345`). Soft delete anahtarıdır.
`vergi_no`	string	Evet	Vergi numarası (10-11 haneli, sadece rakam). Kayıtta saklanır.
`rapor_tarihi`	string	Evet	Rapor ayı, `YYYY-MM` formatında (ör. `2025-10`). Ay 01–12 arası olmalıdır.
`tesis_acik_mi`	boolean	Evet	Tesis ilgili ayda açık mıydı? `true` ise `data` en az bir öğe içermelidir; `false` ise `data` boş dizi (`[]`) olmalıdır.
`data`	array	Evet	Ülke (`iso_kodu`) bazlı aylık metrik kırılımları. Kapalı ay için boş dizi.

data öğesi alanları

Alan	Tip	Zorunlu	Açıklama
`iso_kodu`	string	Evet	Ülke kodu (strict `ISO 3166-1 alpha-3`), `XKX` (Kosova), `CTR` (KKTC) veya `OTHER`.
`haftaici_toplam_giris_yapan_misafir`	integer	Evet	Hafta içi (Pzt–Cum) toplam giriş yapan misafir sayısı. ≥ 0.
`haftasonu_toplam_giris_yapan_misafir`	integer	Evet	Hafta sonu (Cmt–Paz) toplam giriş yapan misafir sayısı. ≥ 0.
`haftaici_toplam_geceleme`	integer	Evet	Hafta içi toplam geceleme (kişi × gece). ≥ 0.
`haftasonu_toplam_geceleme`	integer	Evet	Hafta sonu toplam geceleme (kişi × gece). ≥ 0.
`haftaici_toplam_satilan_oda_gece`	integer	Evet	Hafta içi toplam satılan oda-gece. ≥ 0.
`haftasonu_toplam_satilan_oda_gece`	integer	Evet	Hafta sonu toplam satılan oda-gece. ≥ 0.
`ortalama_fiyat`	number (float)	Evet	İlgili ülke kırılımı için aylık ortalama oda fiyatı. ≥ 0. İstemci, tek bir para birimine çevirerek (EUR) gönderir.
`tesisin_aylik_acik_oldugu_gun_sayisi`	integer	Evet	Tesisin ilgili ayda fiilen açık olduğu gün sayısı. `1 ≤ değer ≤ 31`.

Veri Doğrulama Kuralları

Aşağıdaki kurallara uymayan istekler 422 hata kodu ile reddedilir ve hatalar sunucu tarafında kayıt altına alınır.

1 Tesis Belge Numarası (tesis_belge_no)

İzin verilen iki biçimden biri olmalıdır: (A) NNNN-NN-NNNN — dört rakam, tire, iki rakam, tire, dört rakam; yalnız 0-9 ve tire (ör. 1234-07-1234). (B) 1–5 haneli yalnız rakamlar; ilk hane 1-9 olmalıdır, 0 ile başlayamaz (ör. 7, 12345). Başta ve sondaki boşluklar kırpılır.

2 Vergi Numarası (vergi_no)

vergi_no, 10 veya 11 haneli olmalı ve sadece rakamlardan oluşmalıdır. Aksi halde yanıt mesajı "Geçersiz vergi numarası" ve tip: "vergi_no_gecersiz" döner.

3 Rapor Tarihi (rapor_tarihi)

YYYY-MM formatında olmalı, ay 01–12 aralığında bulunmalıdır. (ör. 2025-10). Geçersiz formatlar Pydantic seviyesinde 422 ile reddedilir.

4 Ülke Kodu (iso_kodu)

Yalnızca strict ISO 3166-1 alpha-3 ülke kodu, XKX, CTR veya OTHER kabul edilir. Geçersiz değerlerde yanıt mesajı "Geçersiz ülke kodu" ve tip: "iso_kodu_gecersiz" döner.

5 Açık Gün Sayısı

tesisin_aylik_acik_oldugu_gun_sayisi alanı kesin olarak 1 ≤ değer ≤ 31 aralığında olmalıdır.

6 Tesis Açık / Data İlişkisi

tesis_acik_mi=true ise data dizisi boş olmamalıdır; tesis_acik_mi=false ise data dizisi boş olmalıdır.

7 Sayısal Alanlar

Tüm hafta içi / hafta sonu metrikleri ve ortalama_fiyat alanları ≥ 0 olmalıdır.

Yanıtlar

200 OK Başarılı Yanıt

{
  "api_version": "v4",
  "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": "v4",
  "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": "v4",
  "status": "error",
  "message": "API erişimi iptal edilmiş. Lütfen destekle iletişime geçin.",
  "data": {
    "request_id": null,
    "errors": []
  }
}

422 Doğrulama Hatası

Eksik / yanlış formatlı alanlarda Pydantic doğrulama hatası örneği:

{
  "api_version": "v4",
  "status": "error",
  "message": "Doğrulama hatası oluştu",
  "data": {
    "request_id": null,
    "errors": [
      {
        "alan": "rapor_tarihi",
        "mesaj": "String should match pattern '^\\d{4}-(0[1-9]|1[0-2])$'",
        "tip": "string_pattern_mismatch"
      }
    ]
  }
}

Geçersiz vergi numarası gönderildiğinde:

{
  "api_version": "v4",
  "status": "error",
  "message": "Geçersiz vergi numarası",
  "data": {
    "request_id": null,
    "errors": [
      {
        "alan": "vergi_no",
        "tip": "vergi_no_gecersiz",
        "mesaj": "Vergi numarası 10-11 haneli olmalı ve sadece rakamlardan oluşmalıdır."
      }
    ]
  }
}

Geçersiz ülke kodu gönderildiğinde:

{
  "api_version": "v4",
  "status": "error",
  "message": "Geçersiz ülke kodu",
  "data": {
    "request_id": null,
    "errors": [
      {
        "alan": "data[0].iso_kodu",
        "tip": "iso_kodu_gecersiz",
        "mesaj": "Geçersiz iso_kodu: 'ZZZ'. ISO 3166-1 alpha-3 ülke kodu, XKX (Kosova), CTR (KKTC) veya OTHER olmalıdır."
      }
    ]
  }
}

Örnek: Açık Tesis

Tek bir rapor ayı (2025-10) için iki ülke kırılımı içeren tipik gönderim.

cURL İsteği

curl -X POST "https://tesis-entegrasyon.tga.gov.tr/tesis-aylik-veri/" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "tesis_belge_no": "1234-07-1234",
    "vergi_no": "1234567890",
    "rapor_tarihi": "2025-10",
    "tesis_acik_mi": true,
    "data": [
      {
        "iso_kodu": "TUR",
        "haftaici_toplam_giris_yapan_misafir": 200,
        "haftasonu_toplam_giris_yapan_misafir": 200,
        "haftaici_toplam_geceleme": 200,
        "haftasonu_toplam_geceleme": 200,
        "haftaici_toplam_satilan_oda_gece": 200,
        "haftasonu_toplam_satilan_oda_gece": 200,
        "ortalama_fiyat": 100,
        "tesisin_aylik_acik_oldugu_gun_sayisi": 30
      },
      {
        "iso_kodu": "DEU",
        "haftaici_toplam_giris_yapan_misafir": 150,
        "haftasonu_toplam_giris_yapan_misafir": 120,
        "haftaici_toplam_geceleme": 180,
        "haftasonu_toplam_geceleme": 140,
        "haftaici_toplam_satilan_oda_gece": 90,
        "haftasonu_toplam_satilan_oda_gece": 70,
        "ortalama_fiyat": 120.5,
        "tesisin_aylik_acik_oldugu_gun_sayisi": 30
      }
    ]
  }'

Beklenen Yanıt

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

Örnek: Kapalı Tesis

Tesis ilgili ayda kapalıysa data boş dizi olarak gönderilir. Bu örnekte belge numarası kısa sayısal biçimdedir (7123 — 1–5 hane, 0 ile başlamaz).

curl -X POST "https://tesis-entegrasyon.tga.gov.tr/tesis-aylik-veri/" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "tesis_belge_no": "7123",
    "vergi_no": "1234567890",
    "rapor_tarihi": "2025-11",
    "tesis_acik_mi": false,
    "data": []
  }'

Kabul Edilen Ülke Kodları (`iso_kodu`)

Aşağıdaki tabloda kabul edilen ISO 3166-1 alpha-3 ülke kodları yer alır. Liste countries.json dosyasından doğrudan üretilir. Ayrıca XKX (Kosova), CTR (KKTC) ve OTHER değerleri de geçerlidir. Tablo alpha-3 koduna göre alfabetik sıralıdır.

alpha-3	Ülke	Not