Tesis Aylık Rapor API

Genel Bilgi

Bu doküman yalnızca POST /tesis-aylik-rapor/ endpoint'ini kapsar. İsteklerde tesisin aylık oda, yatak, açık gün ve ülke kırılımı bazlı metrikleri gönderilir.

v6.0.0 Yayın Notları

v5.0.1 Yayın Notları

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

TGA Tesis Entegrasyon Servisi sürekli geliştirilen dinamik bir yapıdır. Bu nedenle API yanıtlarına statik bir api_version alanı eklenmiştir.

Tüm Otel Yönetim Sistemleri (PMS / CMS) firmalarının ve entegratörlerin kendi sistemlerinde otomatik bir versiyon kontrol mekanizması (Alert / Uyarı Sistemi) kurmasını tavsiye ederiz. Yanıttaki api_version (ör. v6.0.0), sizde kayıtlı sürümden farklıysa IT/geliştirici ekibinize otomatik uyarı üretilmeli ve API dokümantasyonu kontrol edilerek gerekli güncellemeler yapılmalıdır.

Ortamlar

Kimlik Doğrulama

Her istekte size verilen API anahtarı X-API-Key başlığı ile gönderilmelidir. API anahtarı payload içinde gönderilmez.

X-API-Key: YOUR_API_KEY

Endpoint

Başlıklar

İstek Gövdesi

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "rapor_tarihi": "2025-10",
  "il_kodu": "34",
  "ilce_kodu": "1103",
  "oda_sayisi": 100,
  "yatak_sayisi": 100,
  "tesisin_aylik_acik_oldugu_gun_sayisi": 30,
  "aylik_ortalama_fiyat": 100,
  "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
    }
  ]
}

Alanlar

data Öğesi Alanları

Doğrulama Kuralları

Başarılı Yanıt

200 İstek kabul edildiğinde aşağıdaki formatta yanıt döner.

{
  "api_version": "v6.0.0",
  "status": "success",
  "message": "Veriler başarıyla alındı",
  "data": {
    "request_id": "2cb35dfc-859d-46cd-8655-22320b0cb340",
    "errors": []
  }
}

request_id, gönderimin takibi için kullanılabilir.

Hata Yanıtları

401 API Anahtarı Eksik

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

403 API Anahtarı Geçersiz veya Pasif

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

422 Doğrulama Hatası

{
  "api_version": "v6.0.0",
  "status": "error",
  "message": "Geçersiz il veya ilçe kodu",
  "data": {
    "request_id": null,
    "errors": [
      {
        "alan": "ilce_kodu",
        "tip": "il_ilce_uyumsuz",
        "mesaj": "ilce_kodu '8888', il_kodu '34' için geçerli bir ilçe kodu değildir (il–ilçe eşleşmesi uyuşmuyor). Tespit edilemeyen ilçeler için '9999' kodunu kullanabilirsiniz."
      }
    ]
  }
}

Olası doğrulama hata tiplerinden bazıları:

• uuid_parsing: id geçerli bir UUID değildir.
• string_pattern_mismatch: rapor_tarihi formatı hatalıdır.
• il_kodu_gecersiz veya il_ilce_uyumsuz: il / ilçe bilgisi hatalıdır.
• iso_kodu_gecersiz: ülke kodu geçersizdir.

Örnek İstekler

Açık Tesis

curl -X POST "https://tesis-entegrasyon.tga.gov.tr/tesis-aylik-rapor/" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "rapor_tarihi": "2025-10",
    "il_kodu": "34",
    "ilce_kodu": "1103",
    "oda_sayisi": 100,
    "yatak_sayisi": 100,
    "tesisin_aylik_acik_oldugu_gun_sayisi": 30,
    "aylik_ortalama_fiyat": 100,
    "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
      }
    ]
  }'

Kapalı Tesis

curl -X POST "https://tesis-entegrasyon.tga.gov.tr/tesis-aylik-rapor/" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "rapor_tarihi": "2025-11",
    "il_kodu": "07",
    "ilce_kodu": "1126",
    "oda_sayisi": 80,
    "yatak_sayisi": 160,
    "tesisin_aylik_acik_oldugu_gun_sayisi": 0,
    "data": []
  }'

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

Kesin açık gün sayısı bilinmiyorsa, rapor ayının toplam gün sayısı gönderilir. Aşağıdaki örnekte 2025-02 ayı 28 gündür.

curl -X POST "https://tesis-entegrasyon.tga.gov.tr/tesis-aylik-rapor/" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "rapor_tarihi": "2025-02",
    "il_kodu": "34",
    "ilce_kodu": "1103",
    "oda_sayisi": 50,
    "yatak_sayisi": 120,
    "tesisin_aylik_acik_oldugu_gun_sayisi": 28,
    "aylik_ortalama_fiyat": 100,
    "data": [
      {
        "iso_kodu": "TUR",
        "haftaici_toplam_giris_yapan_misafir": 100,
        "haftasonu_toplam_giris_yapan_misafir": 80,
        "haftaici_toplam_geceleme": 90,
        "haftasonu_toplam_geceleme": 70,
        "haftaici_toplam_satilan_oda_gece": 50,
        "haftasonu_toplam_satilan_oda_gece": 40
      }
    ]
  }'

Kabul edilen ülke kodları (iso_kodu)

iso_kodu alanında ISO 3166-1 alpha-3 formatında (büyük harf) resmi üç harfli kodlar kullanılır. Kod listesi aşağıda verilmiştir. Buna ek olarak şu değerler de kabul edilir: XKX (Kosova), CTR (Kuzey Kıbrıs Türk Cumhuriyeti) ve tüm diğer ülkeleri tek satırda toplamak için OTHER.

Lokasyon Kodu Notu

il_kodu ve ilce_kodu değerleri İçişleri Bakanlığı (NVİ - MERNİS) / TÜİK standartlarına uygun resmi kodlar olarak gönderilmelidir. Kodlar string formatındadır; bu nedenle başında sıfır olan değerler varsa sıfırları korunmalıdır.

Güncel il ve ilçe kodları listesine buradan ulaşabilirsiniz: