Ticari belgelerin (fatura, irsaliye, sipariş vb.) XML olarak standart biçimde tanımlanmasını sağlayan uluslararası bir standarttır. Türkiye'deki e-fatura sistemi bu standardın yerelleştirilmiş hali olan UBL-TR'yi kullanır.

UBL-TR ile normal XML arasındaki fark nedir?

UBL-TR de bir XML'dir; farkı, hangi etiketlerin hangi kurallarla kullanılacağının GİB tarafından şema ile sabitlenmiş olmasıdır. Bu sayede tüm muhasebe yazılımları aynı dosyayı aynı şekilde yorumlar.

E-faturanın aslı PDF mi XML mi?

XML'dir. Hukuken geçerli belge UBL-TR XML dosyasıdır; PDF yalnızca insan okuması için üretilen görsel kopyadır ve çoğu zaman XML'in içine gömülü olarak taşınır.

UBL Nedir? UBL-TR Formatı Ne Anlama Gelir?

UBL (Universal Business Language — Evrensel İş Dili), fatura, irsaliye, sipariş gibi ticari belgelerin XML formatında standart biçimde tanımlanmasını sağlayan uluslararası bir standarttır. OASIS tarafından yayımlanır ve dünyada birçok ülkenin e-fatura altyapısının temelini oluşturur.

UBL-TR nedir?

UBL-TR, UBL 2.1 standardının Türkiye'nin vergi mevzuatına göre uyarlanmış halidir. Gelir İdaresi Başkanlığı (GİB), e-fatura ve e-arşiv fatura sisteminde belgelerin UBL-TR formatında üretilmesini zorunlu tutar. Yani Türkiye'de kesilen her e-faturanın aslı, UBL-TR standardına uygun bir XML dosyasıdır; PDF hali yalnızca görsel bir kopyadır.

Bir UBL-TR faturasında neler bulunur?

Kimlik bilgileri: fatura numarası (ID), evrensel tekil numara (UUID), düzenleme tarihi ve saati
Senaryo ve tip: ProfileID (TICARIFATURA, TEMELFATURA, EARSIVFATURA...) ve InvoiceTypeCode (SATIS, IADE, TEVKIFAT...)
Taraflar: satıcı (AccountingSupplierParty) ve alıcı (AccountingCustomerParty) — unvan, VKN/TCKN, adres
Fatura kalemleri: her satır için mal/hizmet adı, miktar, birim fiyat, KDV oranı ve tutarı
Toplamlar: matrah, hesaplanan KDV, vergiler dahil toplam ve ödenecek tutar (LegalMonetaryTotal)
Görsel kopya: faturanın PDF görüntüsünün base64 olarak gömüldüğü alan (EmbeddedDocumentBinaryObject)

UBL-TR doğrulaması neden önemli?

GİB ve özel entegratörler, gelen XML'i şema (XSD) ve şematron kurallarıyla denetler. Zorunlu bir alanın eksik olması, VKN'nin hatalı yazılması veya KDV toplamlarının tutmaması durumunda belge reddedilir. Bu yüzden PDF'ten XML üreten bir aracın çıktısının şema doğrulamasından geçmesi kritiktir — PDFXMLPro'nun ürettiği tüm XML dosyaları UBL-TR 1.2 şema kontrolünden geçirilir.

UBL-TR dosyasını nasıl görüntülerim?

UBL-TR XML dosyaları ham halde okunması zor, uzun belgelerdir. E-Fatura Görüntüleyici aracımız dosyayı fatura görünümünde açar: taraflar, kalemler ve toplamlar tablo halinde gösterilir, gömülü PDF varsa tek tıkla indirilebilir. Elinizde PDF fatura varsa ve UBL-TR XML'e ihtiyacınız varsa, PDF XML çevirme sayfamızdan dönüştürme yapabilirsiniz.

UBL ile UBL-TR arasındaki fark nedir?

UBL, uluslararası bir standarttır ve dünya genelinde elektronik ticaret belgelerinin ortak dilini tanımlar. UBL-TR ise bu standardın Türkiye mevzuatına uyarlanmış sürümüdür.

Uyarlama, uluslararası şemaya Türkiye'ye özgü alanların eklenmesiyle yapılmıştır. Vergi kimlik numarası, vergi dairesi bilgisi, tevkifat alanları ve GİB'in tanımladığı senaryo yapısı bunların başında gelir.

Pratik sonucu şudur: bir UBL belgesi uluslararası araçlarla okunabilir, ancak Türkiye'de geçerli bir e-Fatura olabilmesi için UBL-TR kurallarına uyması gerekir.

UBL-TR belgesinin bölümleri

Bir UBL-TR faturası mantıksal bloklardan oluşur. Bu blokları tanıdığınızda, ham XML'e baktığınızda ne aradığınızı bilirsiniz.

Belge başlığı: fatura numarası, benzersiz kimlik, tarih, senaryo ve fatura tipi
Satıcı bilgileri: unvan, VKN, adres, vergi dairesi
Alıcı bilgileri: unvan, VKN veya TCKN, adres
Satır kalemleri: her mal veya hizmet için miktar, birim fiyat, tutar
Vergi blokları: KDV matrahı, oranı, hesaplanan vergi, varsa tevkifat
Toplamlar: vergi hariç tutar, vergi dahil tutar, iskonto, ödenecek tutar
Gömülü XSLT: belgenin görüntüsünü üreten şablon

Hangi belgeler UBL-TR kullanır?

UBL-TR yalnızca e-Fatura için değil, Türkiye'deki elektronik belge ailesinin geneli için kullanılır.

e-Fatura ve e-Arşiv Fatura
e-İrsaliye ve irsaliye yanıtı
e-Serbest Meslek Makbuzu
e-Müstahsil Makbuzu
Uygulama ve fatura yanıtları

Belge türleri farklı şemalar kullanır ama ortak yapı aynıdır. Bu yüzden bir UBL-TR faturasını okuyabilen bir araç, genellikle diğer belge türlerini de açabilir.

Neden bu kadar ayrıntılı bir standart?

İlk bakışta UBL-TR gereğinden fazla ayrıntılı görünür: basit bir fatura için yüzlerce satırlık XML üretilir. Ancak bu ayrıntı, belgenin insan yorumuna ihtiyaç duymadan işlenebilmesini sağlar.

Standart sayesinde farklı yazılımlar kullanan iki firma, birbirinin belgesini eksiksiz okuyabilir. Kağıt faturada 'şu rakam neydi' diye telefon açmayı gerektiren durumlar, yapılandırılmış veride ortadan kalkar. Ayrıntı, otomasyonun bedelidir.

UBL-TR sürümleri arasındaki fark

UBL-TR zaman içinde güncellendi ve farklı sürümleri yayımlandı. Sürüm bilgisi belgenin başındaki alanlarda taşınır; belgeyi okuyan sistem hangi kurallara göre işlem yapacağını buradan anlar.

Sürüm farkları genellikle yeni alanların eklenmesi veya bazı alanların zorunlu hâle gelmesi şeklindedir. Eski sürüme göre üretilmiş bir belge, yeni kurallara tabi bir sistemde uyarı verebilir.

Arşivden çıkan eski belgelerde bu durumla karşılaşmak normaldir. Belgeyi görüntülemek sorun çıkarmaz; sorun, eski şemaya göre yeni belge üretmeye çalışıldığında ortaya çıkar.

UBL-TR belgesi nasıl doğrulanır?

Doğrulama, üretilen XML'in GİB tarafından yayımlanan XSD şema dosyalarına karşı sınanmasıdır. Şema, hangi alanın zorunlu olduğunu, hangi formatta yazılacağını ve hangi sırayla geleceğini tanımlar.

Doğrulamadan geçmeyen belge sisteme kabul edilmez. Bu yüzden entegrasyon geliştirirken üretilen her belgenin gönderilmeden önce şemaya karşı sınanması, red döngülerini baştan engeller.

Özet

UBL, elektronik ticaret belgeleri için geliştirilmiş uluslararası bir XML standardıdır. UBL-TR ise bu standardın Türkiye mevzuatına uyarlanmış hâlidir; vergi kimlik bilgileri, tevkifat alanları ve GİB senaryoları gibi yerel ihtiyaçlar eklenmiştir.

Bir belgenin Türkiye'de geçerli e-Fatura sayılabilmesi için UBL-TR şemasına uyması, gerekli alanları eksiksiz içermesi ve görüntüleme şablonunu barındırması gerekir. Standardın ayrıntılı olmasının sebebi, belgenin insan yorumu olmadan işlenebilmesidir.

UBL-TR ve uluslararası e-fatura ağları

Avrupa'da Peppol adı verilen bir ağ üzerinden sınır ötesi e-fatura alışverişi yapılır ve bu ağ da UBL tabanlıdır. Ortak kök sayesinde, Türkiye'deki bir belge ile Avrupa'daki bir belge yapısal olarak birbirine benzer.

Bu benzerlik, ihracat yapan firmalar için avantajdır: aynı veri modelini kullanan sistemler arasında dönüşüm yapmak, sıfırdan eşleştirme kurmaktan çok daha kolaydır. Alan adları ve zorunluluklar farklılaşsa da mantık ortaktır.