Roomnix TGA Entegrasyonu Nasıl Çalışır?

TGA entegrasyonu Roomnix'te tamamlandı ve yayında. Merkezi Turizm Veri Tabanı'na yapılması gereken aylık konaklama bildirimi artık ayrı bir veri girişi işi değil: rapor, zaten sisteminizde olan rezervasyon verisinden üretiliyor, kapanan ay gece otomatik gönderiliyor ve gönderilen her şey ekranda birebir görüntülenebiliyor.

TGA'nın ne olduğunu, hangi alanları istediğini ve bu bildirimin KBS ile Aylık Turizm İstatistik Raporu'ndan farkını ayrı bir yazıda anlatmıştık: TGA Entegrasyonu: Merkezi Turizm Veri Tabanı'na Aylık Konaklama Raporu Nasıl Gönderilir? Bu rehber ise doğrudan uygulamayı anlatıyor: Roomnix'te entegrasyonu nasıl kuracağınızı, rakamların hangi kurallarla hesaplandığını, düzeltmeyi nasıl yapacağınızı ve karşınıza çıkabilecek hataların ne anlama geldiğini.

Özet: entegrasyon ne yapıyor?

• Raporu üretir. Uyruk bazında giriş, geceleme ve satılan oda-gece sayıları ile aylık ortalama oda fiyatı, rezervasyon verisinden TGA metodolojisine göre hesaplanır.
• Önce gösterir, sonra gönderir. Herhangi bir dönemi seçip raporu ekranda, hatta gönderilecek JSON'un birebir kendisiyle birlikte görebilirsiniz.
• Kendiliğinden gönderir. Gece çalışan iş, kapanan ayı otomatik iletir; başarısız olursa ertesi gece yeniden dener.
• Kaydını tutar. Her gönderim; dönem, ortam, durum, deneme sayısı, TGA işlem numarası (request_id) ve sunucu yanıtıyla birlikte saklanır.
• Kişisel veri göndermez. Payloz tamamen istatistikseldir.

Kimler kullanabilir?

TGA raporlaması Türkiye'ye özgü bir yükümlülük olduğu için modül de buna göre kapsanmıştır:

• Ülke: Yalnızca ülkesi Türkiye olarak tanımlı tesislerde görünür ve açılır.
• Yetki: Rapor ekranına ve ayarlara yalnızca Admin ve Manager rolleri erişebilir. Bildirim ticari veri içerdiği için ön büro personeli kapsam dışıdır.
• Ücret: Modül ücretsizdir ve tüm planlara dâhildir.
• Etkinleştirme: Eklentiler ekranından TGA modülü açılır; ardından modül ayarları ve rapor konsolu erişilebilir hâle gelir.

Kurulum: bir kez yapılan altı ayar

Kurulumun tamamı tek bir ayar ekranında toplanmıştır ve ortalama beş dakika sürer.

1. Entegrasyon ve otomatik gönderim anahtarları

İki ayrı anahtar vardır: Entegrasyon açık ve Ay kapandığında otomatik gönder. Birincisi kapalıyken raporu görüntüleyebilir ama gönderemezsiniz — kuruluma başlarken rakamları kontrol etmek için bilinçli olarak bu durumda bırakabilirsiniz. İkincisi kapalıyken gönderim tamamen elle yapılır; önerilen kullanım her ikisinin de açık olmasıdır.

2. Ortam: önce test, sonra canlı

Entegrasyonun iki ortamı vardır ve ikisi ayrı adreslere gider. Uygulama kuralı nettir: canlıya geçmeden önce en az bir dönemin test ortamında başarıyla gönderilmiş olması beklenir. Rapor ekranının sağ üst köşesindeki rozet, o an hangi ortamda olduğunuzu her zaman gösterir; bir dönemi "gönderdim" sanıp test ortamında bırakmak en kolay yapılan hatadır.

3. Tesis kimliği: Roomnix üretir, bir daha değişmez

Paylozdaki id alanı, TGA'nın size verdiği bir numara değil, tesisin sağlayıcı sistemindeki benzersiz kimliğidir. Roomnix bu UUID'yi entegrasyon açıldığında bir kez üretir ve sabitler. Arayüzde alan salt okunurdur; yalnızca kopyalayabilirsiniz, yeniden üretemezsiniz.

Bunun sebebi teknik değil, veri bütünlüğüyle ilgilidir: kimlik değişirse TGA tarafında yeni bir tesis oluşur ve o kimlikle daha önce bildirilmiş her rakam mükerrer hâle gelir. Bu yüzden kimliği değiştirme isteği sunucu tarafında da açıkça reddedilir.

4. İl ve ilçe kodu

İl seçtiğinizde ilçe listesi otomatik dolar, böylece uyumsuz bir çift seçmeniz mümkün olmaz — TGA'nın en sık döndürdüğü doğrulama hatası tam olarak budur. Resmî listede yer almayan ilçeler için 9999 — listede yok seçeneği bulunur. Rapor üretilirken il-ilçe uyumu bir kez daha kontrol edilir; uyumsuzsa gönderim yapılmadan önce durdurulur.

5. Oda ve yatak sayısı: yalnızca doluluk oranı için

Burada en çok yanlış anlaşılan noktayı netleştirelim: bu iki alan istatistikleri etkilemez. Satılan oda-gece, geceleme ve giriş sayıları her zaman Roomnix'teki gerçek oda ve rezervasyon verisinden üretilir. Oda ve yatak sayısı, TGA'nın doluluk oranını hesaplarken kullandığı kapasite değeridir ve turizm belgenizde yazan resmî rakam olmalıdır. Girilen değerlerin doğruluğu ve belgeyle tutarlılığı tesisin sorumluluğundadır. Alanlar boş bırakılırsa Roomnix oda listesinden ve oda tipi kapasitelerinden türetir, ancak bunu bir uyarı olarak da bildirir.

6. Vergiler ve pansiyon payları

Vergi oranları kanunla belirlendiği için kullanıcı tarafından değiştirilemez ve ekranda salt okunur gösterilir:

• KDV: Konaklama hizmetlerinde %10.
• Konaklama vergisi: Rapor dönemine göre otomatik uygulanır — 1 Mayıs 2026'dan itibaren %1, öncesinde %2. Geçmiş ayları raporlarken o ayda geçerli olan oran kullanılır; siz bir şey yapmazsınız. Ayrıntı için: Konaklama vergisi %1'e düşürüldü.

Girmeniz gereken tek fiyat ayarı, pansiyon tiplerine karşılık gelen yeme-içme paylarıdır ve bunlar tutar değil yüzdedir: BB, HB, FB ve AI için oda fiyatının yüzde kaçının yeme-içmeye karşılık geldiğini girersiniz. Yüzde olması bilinçli bir tercihtir — pay, fiyatla birlikte ölçeklenir; ucuz bir gece orantılı olarak daha az yeme-içme bedeli bırakır, sabit tutarda olduğu gibi düşük fiyatlı gecelerde net fiyatı bozmaz. Ekranda referans olarak %10 / %25 / %35 / %50 değerleri önerilir; kendi maliyet yapınıza göre girmeniz beklenir. Sadece oda (RO) rezervasyonlarında kesinti yapılmaz, çünkü fiyat zaten oda fiyatıdır.

Rapor konsolu: gönderilen her şey ekranda

Kurulumdan sonra günlük kullanım tek bir ekranda geçer. Dönem seçicide son 18 ay listelenir; devam eden ay "gönderilemez" etiketiyle işaretlidir ve yalnızca önizleme amaçlıdır. Ekranda gördükleriniz:

• Özet kutuları: Toplam oda-gece, geceleme, giriş sayısı, uyruk adedi, hesaplanan ortalama fiyat, kullanılan TCMB kuru ve kur tarihi, sayılan rezervasyon adedi.
• Uyruk tablosu: Her ISO 3166 ülke kodu için giriş / geceleme / oda-gece sayıları, hafta içi ve hafta sonu olarak ayrı sütunlarda, altta toplam satırıyla.
• Uyarılar: Rakamları etkileyebilecek her durum — eksik kapasite ayarı, fiyatsız geceler, check-in işaretlenmemiş rezervasyonlar — gönderimden önce ayrı bir kutuda listelenir.
• Gönderilecek JSON: Paylozun birebir kendisi açılır bir kutuda gösterilir. Ekranda gördüğünüz rakam ile TGA'ya giden rakam aynıdır; arada yorum yapan bir katman yoktur.
• Dönem düzeltmesi: Açık gün sayısı ve ortalama oda fiyatı (EUR, net) için elle geçersiz kılma, bir de not alanı. Boş bırakılan alan otomatik hesaplanmaya devam eder.
• Gönderim geçmişi: Dönem, ortam, durum (HTTP kodu ile birlikte), deneme sayısı, son gönderim zamanı ve TGA işlem numarası.

İki düğme vardır: Yenile raporu yeniden hesaplar, TGA'ya gönder iletir. Yanındaki zorla gönder anahtarı ise yalnızca düzeltme içindir; normal akışta kapalı kalır.

Rakamlar nasıl sayılıyor?

Sayım kuralları TGA metodolojisini birebir uygular. Aynı hesaplama fonksiyonu hem ekran önizlemesini, hem elle gönderimi, hem de gece çalışan otomatik gönderimi besler; üç yolun da ürettiği payloz aynıdır.

• Gece, ait olduğu aya yazılır. 29 Temmuz – 2 Ağustos arası bir konaklamanın üç gecesi Temmuz, iki gecesi Ağustos raporuna girer. Konaklamanın başladığı ay belirleyici değildir.
• Satılan oda-gece ana misafirin uyruğuna yazılır. Bir odayı uyruklara bölmek mümkün olmadığı için oda-gece tek bir uyruğa gider.
• Geceleme her misafirin kendi uyruğuna yazılır. Odaya bağlı misafir kayıtları kullanılır; kayıt yoksa ana misafirin uyruğu kişi sayısı kadar tekrarlanır. Üç kişilik bir odanın iki gecesi 6 geceleme, 2 oda-gece üretir.
• Giriş yalnızca giriş gününe sayılır. Aya devreden bir konaklamanın girişi önceki aya aittir; devam eden ayda yalnızca geceleri sayılır.
• Hafta sonu Cuma ve Cumartesi'dir. Pazar hafta içi sayılır. Bu tanım sözleşmeyle sabittir, ayarlanabilir değildir.
• İptal ve no-show kayıtları hariçtir. Gerçekleşmemiş konaklama rapora girmez.
• Dahili "Park" oda tipleri hariçtir. Bekletme amacıyla kullanılan iç oda tipleri satılabilir envanter değildir; kanal envanterinde olduğu gibi TGA raporunda da yok sayılırlar.
• Check-in işaretlenmemiş geçmiş rezervasyonlar sayılır. Geçmiş tarihli olduğu hâlde ön büroda giriş işaretlenmemiş bir rezervasyon neredeyse her zaman gerçekleşmiş bir konaklamadır; Roomnix bunları rapora dâhil eder ve kaç tane olduğunu uyarı olarak bildirir. Gelecek tarihli kayıtlar doğal olarak sayılmaz.

Ortalama fiyat: beş adımın hepsi otomatik

Raporun en hassas alanı ortalama oda fiyatıdır. Roomnix şu sırayı izler:

1. Gerçekleşen oda geliri toplanır. Yalnızca dönem içindeki ve fiilen uyunmuş gecelerin taban fiyatı kullanılır. Taban fiyat, tesis para birimindeki güvenilir tutardır; OTA aktarımlarında bazen başka bir para biriminde gelebilen ham tutar bilinçli olarak kullanılmaz.
2. Pansiyon payı düşülür. Her gecenin fiyatından, rezervasyonun pansiyon tipine karşılık gelen yüzde çıkarılır.
3. KDV ve konaklama vergisi ayrıştırılır. Roomnix'te oda fiyatları her iki vergiye de dâhil olarak saklandığı için ikisi birden ayrıştırılır; konaklama vergisi oranı rapor dönemine göre seçilir.
4. EUR'ya çevrilir. Çevrim, TCMB'nin ilgili ayın son iş gününe ait döviz satış kuru ile yapılır. O gün için kur yayımlanmamışsa (hafta sonu, resmî tatil) geriye doğru yürünerek yayımlanan en yakın iş günü bulunur; bulunan kur saklanır ve sonraki hesaplarda yeniden indirilmez.
5. Satılan oda-gece sayısına bölünür. Sonuç, dönemin ortalama oda fiyatıdır.

Taban fiyatı boş olan geceler ortalamaya dâhil edilmez; kaç gecenin bu durumda olduğu uyarı olarak gösterilir, böylece kaynağındaki eksikliği düzeltebilirsiniz. Hesaplanan fiyat sıfır çıkarsa bu da ayrı bir uyarıyla bildirilir — genellikle pansiyon yüzdelerinin veya fiyat verisinin gözden geçirilmesi gerektiği anlamına gelir.

Otomatik gönderim tam olarak ne yapıyor?

Gece çalışan iş her sabaha karşı Türkiye saatiyle koşar ve şu mantığı izler:

• Sadece kapanan ayı hedefler. Devam eden ay hiçbir koşulda gönderilmez.
• Bir dönem TGA tarafından kabul edilmişse ve veriler o günden beri değişmemişse tekrar gönderilmez; TGA her dönem için tek gönderim bekler.
• Veriler kabul edilmiş bir dönemden sonra değiştiyse iş bunu bildirir, ancak kendiliğinden düzeltme göndermez — düzeltme bilinçli bir karardır.
• Gönderim başarısız olursa ertesi gece yeniden denenir; on günlük pencere kapansa bile denemeye devam eder, çünkü geç bildirim hiç bildirmemekten iyidir.
• Her koşuda tek örnek kilidi vardır; iş üst üste binmez.

Pratikte bunun anlamı şudur: ay kapanır, siz bir şey yapmazsınız, dönem gönderilmiş olur. Sizin işiniz ayın ilk günlerinde rapor ekranına bir kez bakmaktan ve gönderim geçmişindeki satırın yeşil olduğunu görmekten ibarettir.

Düzeltme ve geçmiş veri

Bir dönemi düzeltmek

Aynı tesis kimliği ve aynı dönem için yapılan yeni gönderim, TGA tarafında önceki rakamların yerine geçer. Roomnix kabul edilmiş bir dönemi kendiliğinden tekrar göndermediği için düzeltme şu şekilde yapılır: dönemi seçin, zorla gönder anahtarını açın ve gönderin. Düzeltme de geçmişe ayrı bir satır olarak yazılır; hangi dönemin kaç kez gönderildiği her zaman görünür kalır.

Açık gün sayısı ve fiyat için elle müdahale

Tesis ayın bir kısmında kapalıysa ya da hesaplanan ortalama fiyatın gerçeği yansıtmadığını düşünüyorsanız, dönem düzeltmesi kartından bu iki değeri elle girebilirsiniz. Girilen değer o dönem için otomatik hesaplamanın yerine geçer; alanı boşaltırsanız otomatik hesaplamaya geri dönülür. Not alanı, neden müdahale edildiğini kayda geçirmek içindir — birkaç ay sonra rakamı sorgulayan kişi genellikle siz olursunuz.

Ocak 2025'ten itibaren toplu yükleme

Sisteme yeni dâhil olan tesisler için Ocak 2025'ten son kapanan aya kadar tüm dönemler, aynı hesaplama mantığıyla ay ay üretilip tek bir toplu işlemde gönderilir. Yirmi aya yaklaşan bu seri, elle yapılması hâlinde günler süren bir iştir; entegrasyonda tek bir çalıştırmadır ve her dönem yine ayrı ayrı kayda geçer.

Hata mesajları ve anlamları

Roomnix, paylozu göndermeden önce TGA'nın reddedeceği durumları kendi tarafında kontrol eder; böylece çoğu hata sunucuya hiç gitmeden ekranda görünür.

• "Tesis kimliği tanımlı değil veya geçersiz" — Entegrasyon ayarları kaydedilmemiştir. Ayar ekranını bir kez kaydetmek kimliği üretir.
• "İl ve ilçe kodu birbiriyle uyumsuz" — Kodlar elle veya eski bir kayıttan gelmiştir. İli yeniden seçip ilçeyi listeden işaretlemek yeterlidir.
• "Oda ve yatak sayısı sıfırdan büyük olmalı" — Ayarlarda kapasite boş ve oda listesinden de türetilememiştir.
• "TCMB kuru alınamadı" — Merkez Bankası'nın ilgili günkü yayınına ulaşılamamıştır. Geçici bir durumdur; gece çalışan iş ertesi gün yeniden dener.
• Alan bazlı 422 hataları — TGA bir alanı reddettiğinde yanıtı alan adı ve gerekçesiyle birlikte olduğu gibi gösterilir; tahmin etmeniz gerekmez.
• API sürüm uyarısı — TGA yanıtındaki sürüm, entegrasyonun doğrulandığı sürümden farklıysa gönderim yine kaydedilir ama uyarı düşülür. Bu, sözleşme değişikliğini kaçırmamak için konulmuş bir erken uyarıdır.

Gizlilik: rapor tamamen istatistikseldir

Gönderilen paylozda ad, soyad, kimlik veya pasaport numarası, doğum tarihi, telefon, e-posta ya da rezervasyon kodu yoktur. Payloz; tesis kimliği, dönem, il-ilçe kodu, kapasite, açık gün sayısı, ortalama fiyat ve uyruk kodu başına altı sayıdan ibarettir. Uyruk bile isim olarak değil, üç harfli ülke kodu altında toplanmış sayılar hâlinde gider.

Misafir kimliklerinin bildirimi bambaşka bir yükümlülüktür ve KBS entegrasyonu üzerinden, giriş anında, misafir bazında yapılır. İkisi birbirinin yerine geçmez; biri günlük operasyonun parçası, diğeri ay kapanışının adımıdır.

Kurulum kontrol listesi

1. Eklentiler ekranından TGA modülünü etkinleştirin.
2. Ayarlarda entegrasyonu ve otomatik gönderimi açın, ortamı test olarak bırakın.
3. İl ve ilçeyi listeden seçin.
4. Turizm belgenizdeki oda ve yatak sayısını girin.
5. Pansiyon tipleri için yeme-içme yüzdelerini girin (RO için gerekmez).
6. Rapor ekranında son kapanan dönemi önizleyin; uyarıları ve ortalama fiyatı kontrol edin.
7. Test ortamında bir dönemi gönderin ve geçmişte başarılı satırı görün.
8. Ortamı canlıya alın; geçmiş veri yüklemesi için Roomnix ile iletişime geçin.
9. Ay başlarında geçmiş ekranına bir kez bakın. Gerisi otomatiktir.

Sonuç

TGA bildirimi, doğru yapıldığında görünmez olması gereken işlerden biridir: zorunludur, penceresi dardır, metodolojisi kendine özgüdür ve doğru hesaplandığında kimsenin dikkatini çekmez. Roomnix'in TGA entegrasyonu tam olarak bunu hedefler — raporu otel yönetim yazılımının zaten bildiği veriden üretir, ay kapanır kapanmaz gönderir, gönderdiğini eksiksiz gösterir ve gerektiğinde düzeltmenize izin verir.

Roomnix kullanıyorsanız modülü eklentiler ekranından hemen açabilirsiniz. Henüz kullanmıyorsanız entegrasyonlar sayfamızı inceleyebilir, fiyatlandırmanızı güncel vergi oranına göre kontrol etmek için konaklama vergisi hesaplama aracımızı kullanabilirsiniz.

Sık Sorulan Sorular

Roomnix TGA entegrasyonu ücretli mi?

Hayır. TGA modülü Türkiye'deki tesisler için ücretsizdir ve tüm planlara dâhildir. Eklentiler ekranından etkinleştirmeniz yeterlidir.

Tesis kimliğini (UUID) TGA mı veriyor?

Hayır, Roomnix üretir. Paylozdaki kimlik, tesisin sağlayıcı sistemindeki benzersiz kimliğidir. Bir kez üretilir ve bir daha değişmez; değişmesi TGA tarafında yeni bir tesis oluşturacağı ve bildirilen rakamları mükerrer hâle getireceği için kimliği yeniden üretme isteği sistem tarafından reddedilir.

Ayrıca API anahtarı girmem gerekiyor mu?

Hayır. Anahtar, ortam bazında Roomnix tarafında tanımlıdır. Sizin yapmanız gereken, canlıya geçmeden önce en az bir dönemi test ortamında başarıyla göndermektir.

Devam eden ay gönderiliyor mu?

Hayır. TGA yalnızca kapanmış ayları kabul eder. Devam eden ay listede "gönderilemez" olarak işaretlenir ve yalnızca önizlenebilir.

Ortalama fiyat neden PMS'imdeki fiyattan düşük?

TGA çıplak oda fiyatı istediği için. Taban fiyattan pansiyon payı yüzde olarak düşülür, KDV ve konaklama vergisi ayrıştırılır, kalan tutar TCMB'nin ay sonu döviz satış kuruyla EUR'ya çevrilir ve satılan oda-gece sayısına bölünür.

Yanlış giden bir dönemi düzeltebilir miyim?

Evet. Aynı dönem için yapılan yeni gönderim önceki rakamların yerine geçer. Kabul edilmiş bir dönem kendiliğinden tekrar gönderilmez; düzeltmeyi "zorla gönder" seçeneğiyle siz başlatırsınız.

Sezonluk tesisim; kapalı aylarda ne oluyor?

Kapalı ay da bildirilir. Açık gün sayısını dönem düzeltmesi kartından elle girebilirsiniz; sıfır girildiğinde uyruk kırılımı boş bir dönem raporu gönderilir.

Misafirlerin kişisel verileri gidiyor mu?

Hayır. Rapor tamamen istatistikseldir; kişisel veri içermez. Uyruk bile ISO üç harfli ülke kodu altında toplanmış sayılar olarak iletilir. Kimlik bildirimi KBS üzerinden yapılan ayrı bir yükümlülüktür.

Geçmiş aylar da yükleniyor mu?

Evet. Ocak 2025'ten son kapanan aya kadar tüm dönemler aynı hesaplama mantığıyla ay ay üretilip tek bir toplu işlemde gönderilir.