UBL-TR Nedir? Tanımı, Nerede Kullanılır, Nelere Dikkat Edilir

UBL-TR Nedir? Tanımı, Nerede Kullanılır, Nelere Dikkat Edilir

UBL-TR, Türkiye’de e-belgelerin makine tarafından işlenmesini sağlayan ve GİB kurallarıyla uyarlanmış UBL tabanlı XML belge standardı demektir. Bu yapı, fatura bilgilerinin ortak etiketlerle taşınmasını ve yazılımlar arasında okunmasını sağlar.

Bu konu, e-Fatura düzenleyen, e-Arşiv kullanan veya entegrasyon yöneten işletmelere yarar. UBL-TR; dosya alanlarını, kodları, toplamları ve belge ilişkilerini anlamayı kolaylaştırır.

UBL, Universal Business Language ifadesinin kısaltmasıdır. Ticari belgelerdeki bilgileri ortak bir XML veri modeli içinde tanımlamayı amaçlar.

UBL-TR ise bu genel yapının Türkiye’deki e-belge ihtiyaçlarına göre uyarlanmış hâlidir. GİB teknik kılavuzları, şema dosyaları ve iş kuralları bu uyarlamanın uygulanma biçimini belirler.

UBL-TR tek başına bir portal, entegratör veya görsel fatura ekranı değildir. Belgenin yazılımlar tarafından okunabilen veri katmanını ve bu verinin düzenini ifade eder.

Örneğin bir e-Fatura dosyasında satıcı, alıcı, tarih, vergi, kalem ve toplam bilgileri belirli XML etiketleriyle taşınır. Yazılım, bu etiketleri kullanarak belgeyi işler.

PDF veya HTML görünümü, UBL-TR XML dosyasının görsel sunumudur. Görsel dosya ile kaynak XML arasında bilgi, tutar veya tarih farkı bulunmaması gerekir.

UBL-TR standardı ile e-belge arasındaki fark nedir?

UBL-TR, e-belgenin teknik veri yapısını; e-belge ise mevzuata göre düzenlenen elektronik ticari belgeyi ifade eder. Biri formatı, diğeri belgenin hukuki ve ticari niteliğini açıklar.

Bir e-Fatura, e-Arşiv Fatura veya e-İrsaliye XML içinde UBL-TR yapısını kullanabilir. Ancak belgenin geçerliliği yalnızca XML etiketlerinin bulunmasına bağlı değildir.

Belgenin doğru senaryoda oluşturulması, imzalanması, ilgili kanaldan gönderilmesi ve sistem yanıtının alınması gerekir. Alıcı bilgileri ile vergi ve toplam hesapları da ilgili kurallara uymalıdır.

Bu nedenle UBL-TR dosyasını, e-belgenin tamamı yerine geçen tek unsur olarak düşünmek doğru değildir. Format, gönderim süreci ve mevzuat birlikte değerlendirilir.

Yanlış: UBL-TR dosyası oluşturmak, belgenin otomatik olarak geçerli olduğu anlamına gelir. Doğru: Şema, iş kuralları, imza, gönderim ve sistem yanıtı birlikte kontrol edilir.

e-Defter bu ayrım için iyi bir örnektir. E-Defter, UBL-TR fatura dosyasıyla aynı belge yapısını kullanmaz; kendi teknik kılavuzları ve dosya bileşenleri bulunur.

Bir işletme yazılım seçerken yalnızca XML dışa aktarımı sormamalıdır. Güncel GİB şemalarının, kod listelerinin, imza süreçlerinin ve yanıt ekranlarının desteklenip desteklenmediğini de kontrol etmelidir.

UBL-TR hangi e-belgelerde kullanılır?

UBL-TR, başta e-Fatura, e-Arşiv Fatura ve e-İrsaliye gibi teknik kılavuzlarında XML yapısı tanımlanan e-belgelerde kullanılır. Belge türüne göre kök eleman, profil ve zorunlu alanlar değişebilir.

Her e-belgenin aynı UBL-TR dosyası olduğu varsayılmamalıdır. Belge türü, işlem senaryosu ve GİB’in güncel teknik kılavuzu birlikte incelenmelidir.

e-İrsaliye dosyasında fatura tutarı yerine sevk ve mal hareketi bilgileri öne çıkar. Bu nedenle e-Fatura alanlarını doğrudan e-İrsaliye dosyasına kopyalamak hatalı sonuç verebilir.

e-SMM veya e-MM kullanan işletmeler de aynı yöntemi izlemelidir. Önce belge türü belirlenmeli, sonra o belgeye ait GİB şeması ve iş kuralları kullanılmalıdır.

GİB teknik kılavuzlarında yapılan değişiklikler, alan zorunluluklarını veya kod listelerini etkileyebilir. Uygulama güncellenmeden önce güncel kılavuz ve duyurular kontrol edilmelidir.

UBL-TR dosyasında hangi temel alanlar bulunur?

UBL-TR dosyasında belge kimliği, tarih, profil, taraflar, para birimi, kalemler, vergi ve toplam tutarlar gibi temel alanlar bulunur. Her alanın zorunluluğu, belge türüne ve senaryoya göre değişebilir.

Belge kimliği için genellikle cbc:ID kullanılır. Bu alan, fatura numarası veya ilgili belgenin numarasıdır; benzersizlik ve numara sırası kuralları ayrıca değerlendirilir.

cbc:UUID, belgenin benzersiz teknik kimliğini taşır. Uygulamalarda bu değer ETTN olarak da anılabilir; numara ve UUID aynı işlevi taşımaz.

cbc:IssueDate düzenleme tarihini, cbc:InvoiceTypeCode belge türünü, cbc:ProfileID ise işlem profilini belirtir.

cac:AccountingSupplierParty satıcıyı, cac:AccountingCustomerParty alıcıyı tanımlar. VKN veya TCKN, unvan, adres ve vergi bilgileri bu bölümlerde yer alabilir.

cac:InvoiceLine kalem bilgilerini taşır. Miktar, ölçü birimi, birim fiyat, iskonto, ürün açıklaması ve kalem vergileri burada ilişkilendirilir.

cac:TaxTotal vergi toplamlarını, cac:LegalMonetaryTotal ise ara toplam ve ödenecek tutar gibi parasal değerleri içerir. Rounding farkları, toplam kontrollerinde ayrıca incelenir.

UBL-TR fatura alanları nasıl eşleştirilir?

UBL-TR fatura alanları, işletmenin muhasebe veya satış yazılımındaki bilgilerle doğru XML etiketlerinin eşleştirilmesiyle oluşturulur. Eşleştirme, yalnızca alan adlarının benzemesine göre yapılmamalıdır.

Önce belgenin türü, profili ve senaryosu belirlenir. Daha sonra taraf bilgileri, kalemler, vergiler ve toplamlar ilgili teknik kılavuzda tanımlanan alanlara aktarılır.

1. Belge profili ve senaryosu seçilir, bu seçim fatura türüyle tutarlı hâle getirilir.
2. Satıcı ve alıcı bilgileri, VKN veya TCKN ile birlikte doğru taraf alanlarına yazılır.
3. Her kalemin miktarı, birimi, birim fiyatı, açıklaması ve vergi bilgisi ayrı satırda eşleştirilir.
4. Vergi toplamları, iskonto ve ödenecek tutar kalemlerden yeniden hesaplanarak karşılaştırılır.
5. Oluşan XML, güncel XSD ve iş kurallarıyla doğrulanır; ardından imza ve gönderim süreci yürütülür.

Örneğin satış yazılımındaki müşteri vergi numarası, alıcı tarafının kimlik alanına yazılmalıdır. Bu değer açıklama alanına bırakılırsa XML teknik olarak okunabilir görünse bile iş kuralı ihlali oluşabilir.

Para birimi, ölçü birimi ve vergi kodları serbest metin olarak girilmemelidir. Güncel kod listesinde karşılığı bulunan değerler kullanılmalı ve yazım biçimi değiştirilmemelidir.

Eşleştirme sonrasında görsel fatura ile XML karşılaştırılmalıdır. Görselde görünen kalem, miktar veya toplam XML içinde bulunmuyorsa gönderim öncesi kayıt düzeltilmelidir.

UBL-TR ile e-Fatura ve e-Arşiv XML'i nasıl ayrılır?

UBL-TR, e-Fatura ve e-Arşiv XML dosyalarında benzer temel alanlar sunsa da belge profili, alıcı ve gönderim senaryosu farklıdır. Ayrım, dosya uzantısından veya yalnızca görsel tasarımdan anlaşılamaz.

e-Fatura genel olarak e-Fatura sistemine kayıtlı alıcılar arasındaki ticari akışta kullanılır. Kullanılan senaryo, profil bilgisi ve alıcının sistemdeki durumu dosya ve gönderim sürecinde dikkate alınır.

e-Arşiv Fatura ise genel olarak e-Fatura sistemindeki alıcı dışındaki düzenleme senaryolarında kullanılır. Bununla birlikte istisnai durumlar ve raporlama koşulları için güncel mevzuat ayrıca incelenmelidir.

e-Arşiv sürecinde XML verisinin yanında alıcıya sunulan görsel çıktı bulunabilir. Görselin PDF olması, XML kaydının saklanması veya raporlanması gereğini ortadan kaldırmaz.

e-Arşiv Fatura kullanırken alıcının kimlik bilgileri, belge türü, tarih, tutar ve raporlama akışı birlikte kontrol edilmelidir. Sadece PDF üretmek, e-Arşiv sürecinin tamamlandığını göstermez.

Bir yazılım aynı satış ekranından iki belge türünü üretebilir. Ancak sistem, seçilen profile göre farklı zorunlu alanları, alıcı kontrollerini ve gönderim adımlarını uygulamalıdır.

Alıcının e-Fatura kayıt durumu, özel senaryo veya istisna koşulu belirsizse güncel GİB duyurusu ve mali müşaviriniz kontrol edilmelidir. Mevzuat değişiklikleri, pratikte kullanılan işlem akışını etkileyebilir.

UBL-TR dosyası gönderilmeden önce nasıl doğrulanır?

UBL-TR dosyası gönderilmeden önce XML şeması, iş kuralları, kod listeleri, imza ve görsel içerik açısından doğrulanır. Sadece dosyanın açılması, belgenin teknik olarak geçerli olduğunu kanıtlamaz.

XSD doğrulaması; etiketlerin doğru sırada bulunup bulunmadığını, veri tiplerini ve yapısal zorunlulukları kontrol eder. Schematron veya benzeri iş kuralı kontrolleri ise alanlar arasındaki mantıksal ilişkileri inceler.

• Belgenin kök elemanı ve XML namespace değerleri güncel teknik kılavuzla uyumludur.
• Belge numarası, UUID, tarih, profil ve belge türü alanları eksiksizdir.
• VKN veya TCKN, unvan, adres ve alıcı bilgileri doğru tarafla eşleşir.
• Para birimi, ölçü birimi, vergi ve istisna kodları güncel listeden seçilir.
• Kalem toplamları, vergi toplamları ve ödenecek tutar matematiksel olarak uyuşur.
• Elektronik imza veya mali mühür, kullanılan süreç için geçerli durumdadır.
• XML ile oluşturulan görsel çıktı aynı bilgileri ve tutarları gösterir.

Doğrulama hatası çıktığında yalnızca hata mesajını kapatmak yeterli değildir. Mesajın işaret ettiği XML düğümü, kaynak muhasebe kaydı ve hesaplama yeniden incelenmelidir.

Entegrasyon yazılımı doğrulama yapsa bile işletme kendi test senaryosunu oluşturmalıdır. Özellikle iskonto, tevkifat, istisna, döviz ve iade işlemleri ayrı ayrı denenmelidir.

UBL-TR imza ve belge doğrulaması nasıl yapılır?

UBL-TR belgesinin imza süreci, belge türüne ve gönderim yöntemine göre elektronik imza veya mali mühür kullanılarak yürütülür. İmza, XML içeriğinin sonradan değiştirilip değiştirilmediğini denetlemeye yardımcı olur.

İmza atılmadan önce belge verileri son hâline getirilmelidir. İmzadan sonra tutar, alıcı, tarih veya kalem bilgisi değiştirilirse imza doğrulaması bozulabilir ve belge yeniden oluşturulmalıdır.

İmza kontrolünde sertifikanın geçerliliği, imza bütünlüğü, sertifika zinciri ve kullanılan uygulamanın güncelliği değerlendirilir. Sürecin ayrıntıları, kullanılan entegrasyon ve GİB teknik kurallarıyla belirlenir.

Uzman notu: XML içinde küçük bir karakter değişikliği bile imza özetini etkileyebilir. İmzalı dosyayı metin editörüyle düzeltmeyin; kaynağı düzelterek XML’i yeniden üretin.

Yanlış: İmzalı XML’i açıp eksik alanı elle eklemek güvenli bir düzeltmedir. Doğru: Muhasebe kaynağı güncellenir, XML yeniden oluşturulur, tekrar doğrulanır ve yeniden imzalanır.

Elektronik imza araçları veya mali mühür cihazları çalışmıyorsa sertifika süresi, sürücü, kart okuyucu ve işletim sistemi uyumu kontrol edilir. e-İmza süreçlerinde kullanıcı yetkileri de gözden geçirilmelidir.

İmza doğrulaması başarılı olsa bile alıcıya teslim veya GİB sistem yanıtı ayrıca izlenmelidir. Teknik olarak imzalı bir dosya, gönderim tamamlanmadan ticari süreci sonuçlandırmaz.

UBL-TR gönderiminde en sık hangi hatalar görülür?

UBL-TR gönderimindeki yaygın hatalar; eksik zorunlu alan, yanlış kod, hatalı toplam, geçersiz imza ve alıcı profilinin yanlış seçilmesinden kaynaklanır. Hata türü belirlenmeden yapılan düzeltmeler yeni sorunlar oluşturabilir.

Eksik alan hatalarında önce ilgili XML düğümü belirlenir. Ardından bu alanın neden boş kaldığı araştırılır; kaynak kartta eksik bilgi varsa yalnızca XML üzerinde geçici değişiklik yapılmaz.

VKN veya TCKN biçimi, ülke kodu, para birimi ve ölçü birimi gibi değerler kod listelerine bağlıdır. Serbest yazılan benzer ifadeler, şema geçse bile iş kuralı kontrolünde reddedilebilir.

Kalem toplamı ile genel toplam uyuşmadığında miktar, birim fiyat, iskonto, vergi oranı ve yuvarlama yöntemi sırayla incelenir. Bir kuruşluk fark bile bazı doğrulamalarda önem taşıyabilir.

Aynı belge numarası veya UUID ile yeniden gönderim, mükerrerlik sorununa yol açabilir. Yeniden denemeden önce sistemdeki gönderim durumu ve önceki yanıt mutlaka kontrol edilmelidir.

Alıcının posta kutusu, senaryo veya profil bilgisi yanlış seçilirse belge doğru XML’e rağmen işlem göremeyebilir. Alıcı kartındaki kayıt bilgisi güncel GİB verileriyle karşılaştırılmalıdır.

Hata mesajı teknik, yapısal veya iş kuralı kaynaklı olabilir. Sorun çözülemezse XML, hata çıktısı, gönderim zamanı ve kaynak fatura kaydı birlikte saklanarak entegrasyon desteğine iletilmelidir.

UBL-TR gelen belge nasıl kontrol edilir?

UBL-TR gelen belge kontrolünde önce gönderen, alıcı, belge kimliği, tarih, kalemler, vergi ve toplam tutarlar karşılaştırılır. Sonra imza ve sistem yanıtının durumu incelenir.

Gelen XML dosyasındaki satıcı bilgisi, işletmenin gerçek tedarikçisiyle eşleşmelidir. Belge numarası ve UUID, aynı belgenin daha önce kaydedilip kaydedilmediğini kontrol etmek için kullanılır.

Örneğin küçük bir kafe sahibi, kahve tedarikçisinden gelen UBL-TR faturayı kaydetmeden önce ürün kalemlerini teslim fişiyle karşılaştırır. Miktar farkı varsa muhasebe kaydı hemen kesinleştirilmez.

Kafe sahibi daha sonra vergi toplamını, iskonto bilgisini ve ödenecek tutarı görsel çıktı ile XML arasında karşılaştırır. Tedarikçi bilgisi doğru olsa bile kalem veya tutar uyuşmazlığı ayrıca çözülmelidir.

İşletme kendi müşterisine belge düzenliyorsa aynı kontrolleri giden belgede de uygular. Kendi mevzuat senaryosuna göre e-Fatura veya e-Arşiv seçimi yapılmadan XML üretimine başlanmamalıdır.

Gelen belge teknik olarak geçerli olsa bile mal veya hizmetin gerçekten teslim alındığı anlamına gelmez. Satın alma onayı, teslim kaydı ve muhasebe kontrolü UBL-TR doğrulamasından ayrı yürütülür.

İade, itiraz veya düzeltme gerektiğinde orijinal belgenin üzerine yazılmaz. İlgili belge ilişkisi, yanıt süreci ve mali müşavir yönlendirmesi dikkate alınarak yeni işlem oluşturulur.

UBL-TR dosyası nasıl saklanır ve denetlenir?

UBL-TR dosyası, imzalı orijinal XML ve belgeye ait sistem yanıtlarıyla birlikte saklanmalıdır. Görsel PDF, tek başına kaynak elektronik belgeyi temsil etmeyebilir.

Saklama sırasında XML dosyasının bütünlüğü korunmalı, dosya adı değiştirilse bile belge kimliği ve UUID kaybolmamalıdır. İmzalı dosyanın üzerinde sonradan düzenleme yapılmamalıdır.

Gönderilen belgelerde gönderim zamanı, alıcı, durum yanıtı ve hata bilgisi kayıt altına alınmalıdır. Gelen belgelerde ise indirme zamanı, kaynak sistem ve muhasebe eşleştirmesi izlenebilir olmalıdır.

Görsel çıktı, kullanıcıların okumayı kolaylaştırır ve denetim sırasında karşılaştırma sağlar. Ancak denetimde gerektiğinde XML, imza bilgisi ve ilgili yanıt dosyaları birlikte sunulabilmelidir.

Yedekleme tek bir bilgisayara veya yalnızca e-posta klasörüne bırakılmamalıdır. Yetkilendirme, erişim kaydı, düzenli geri yükleme testi ve dosya bütünlüğü kontrolleri yazılı prosedüre bağlanmalıdır.

Saklama süresi, belge türüne ve güncel mevzuatın öngördüğü yükümlülüklere göre belirlenir. Emin olunmayan durumlarda güncel GİB duyurusu ve mali müşavirinizi kontrol edin.

Denetim hazırlığında sık sorulan sorular bölümü başlangıç sağlayabilir; ancak özel işlem, istisna veya sektör kuralında resmi kılavuz ve mali müşavir görüşü esas alınmalıdır.

Özet: 5 maddede UBL-TR nedir ve nelere dikkat edilir?

UBL-TR, Türkiye’deki belirli e-belgelerin makine tarafından okunmasını sağlayan UBL tabanlı XML uyarlamasıdır. Formatı anlamak, belgeyi tek başına geçerli saymak yerine tüm gönderim zincirini kontrol etmeyi gerektirir.

Doğru uygulama; belge türünü seçmek, alanları eşleştirmek, kodları doğrulamak, imzalamak, göndermek ve sistem yanıtını izlemek adımlarından oluşur.

• UBL-TR, e-belgenin teknik veri yapısıdır; e-Fatura veya e-Arşiv ise belgenin türünü ve işlem bağlamını ifade eder.
• Belge profili, senaryo, alıcı bilgisi ve kök XML yapısı her gönderimden önce kontrol edilmelidir.
• Kalem, vergi, iskonto ve ödenecek tutar alanları hem kaynak kayıtla hem XML ile karşılaştırılmalıdır.
• XSD doğrulaması yeterli değildir; iş kuralları, elektronik imza, gönderim durumu ve alıcı yanıtı da incelenmelidir.
• İmzalı orijinal XML, görsel çıktı ve sistem yanıtları mevzuata uygun süre boyunca erişilebilir biçimde saklanmalıdır.

Belge türü, profil veya özel vergi uygulaması konusunda belirsizlik varsa yalnızca eski bir XML örneğine güvenilmemelidir. Güncel GİB teknik kılavuzu ve mali müşavirinizin değerlendirmesi birlikte alınmalıdır.

UBL-TR uyumlu e-belge akışınız için efaturakontor.com’da tüm e-belgelerde geçerli havuz kontör paketlerini 100’den 500.000 kontöre kadar inceleyebilirsiniz; gelen ve giden belgelerin her biri bir kontör düşürür. Ücretsiz e-Fatura portalı sunulur; kontörler Sovos altyapısına aynı gün tanımlanır ve paketlerin kullanım süresi 12-18 aydır.