UBL-TR Nedir? e-Fatura UBL Dosyası Ne İşe Yarar?

UBL-TR, uluslararası UBL 2.1 standardının GİB tarafından Türkiye için uyarlanmış hâlidir; e-Fatura ve e-İrsaliye XML dosyaları bu biçimde hazırlanır.

Son güncelleme · 5 Kasım 2026

UBL-TR, Universal Business Language (Evrensel İş Dili) standardının Türkiye özelleştirmesidir. GİB, e-Fatura uygulamasında belge biçimi olarak önce UBL 2.0’ı, ardından 4 Kasım 2013’te standartlaşan UBL 2.1’i esas almıştır. e-Fatura, e-Arşiv, e-İrsaliye ve uygulama yanıtı gibi belgeler UBL-TR şemasına uygun XML dosyaları olarak hazırlanır.

Gördüğünüz PDF fatura, bu XML dosyasının okunabilir bir görüntüsüdür. Asıl belge XML’dir; imza ya da mali mühürle onay da XML belgesi üzerinde yapılır.

UBL-TR dosyasında neler bulunur?

  • Senaryo (ProfileID): TEMELFATURA, TICARIFATURA, EARSIVFATURA, IHRACAT gibi.
  • Fatura tipi (InvoiceTypeCode): SATIS, IADE, TEVKIFAT, ISTISNA, OZELMATRAH, IHRACKAYITLI gibi.
  • ETTN (UUID): belgenin evrensel tekil kimliği.
  • Belge para birimi (DocumentCurrencyCode) ve fiyatlar başka para biriminde gösteriliyorsa döviz kuru (PricingExchangeRate).
  • Satıcı ve alıcı bilgileri, satırlar, vergi toplamları ve varsa tevkifat bilgisi (WithholdingTaxTotal).

UBL-TR kod listeleri neden önemli?

Fatura tipleri, istisna sebepleri, tevkifat kodları ve birim kodları GİB’in yayımladığı UBL-TR Kod Listeleri’nden seçilir. Listeler düzenli güncellenir: GİB’in e-Belge duyurularına göre 2026’da UBL-TR 1.2.1 paketi ve kod listesi kılavuzu birkaç kez güncellendi.

GİB’in Merkez birimi kendisine gelen her zarfı XSD ve Schematron kontrolünden geçirir. Bu yüzden güncel olmayan bir kod ya da eksik zorunlu alan, faturanın alıcıya ulaşmadan geri dönmesine yol açabilir.

UBL dosyası nasıl açılır?

XML dosyası bir metin düzenleyicide açılabilir ama okunması zordur. Entegratörünüzün portalı ya da GİB’in e-Fatura görüntüleyici programı XML’i fatura görüntüsüne çevirir. Muhasebe programına aktarımda PDF yerine XML (UBL) dosyasını kullanmak, verinin elle yeniden girilmesini önler.

TicariHub siparişlerinizden faturayı hazırlayıp kendi entegratör hesabınıza gönderir. Faturanın ETTN’si ilk denemede üretilir ve tekrar denemelerde aynı kalır; böylece aynı sipariş için ikinci belge oluşmaz.

Sık Sorulan Sorular

UBL ile UBL-TR arasındaki fark nedir?

UBL, uluslararası bir iş belgesi standardıdır. UBL-TR ise GİB’in bu standardı (bugün UBL 2.1’i) Türkiye’deki e-Fatura, e-Arşiv ve e-İrsaliye uygulamaları için uyarladığı, Türkiye’ye özgü alan ve kod listeleri eklenmiş hâlidir.

UBL dosyası nedir, nasıl açılır?

UBL dosyası e-Faturanın XML biçimindeki asıl hâlidir. Entegratör portalınızda ya da GİB’in görüntüleyici programında açtığınızda fatura görüntüsüne dönüşür. Muhasebe aktarımında bu dosyayı kullanmak veri girişini azaltır.

e-Arşiv faturada da UBL kullanılır mı?

Evet. UBL-TR kod listesinde e-Arşiv için EARSIVFATURA senaryosu tanımlıdır. 509 sayılı Tebliğ de e-Arşiv faturanın elektronik iletiminde GİB’in e-Fatura format ve standardının kullanılmasını ve faturanın basılabilir görüntüsünün eklenmesini ister.

UBL hatası ne demek?

Faturanın XML’i UBL-TR şemasına ya da Schematron kurallarına uymadığında oluşan hatadır; örneğin eksik zorunlu alan ya da listede olmayan bir kod. GİB Merkez bu kontrolleri yapar, hatalı zarf alıcıya iletilmez. Hata ayrıntısını entegratörünüzün panelinde görürsünüz.

Kaynaklar

Mevzuat değişebilir; uygulamadan önce güncel hâlini kaynaktan ya da mali müşavirinizden doğrulayın.

  1. GİB UBL-TR 1.2.1 Kılavuzları: Kod Listeleri V1.43, Genel Açıklamalar, Fatura (ebelge.gib.gov.tr) · erişim 5 Kasım 2026
  2. GİB e-Fatura Uygulaması Entegrasyon Kılavuzu v1.10 (ebelge.gib.gov.tr) · erişim 5 Kasım 2026
  3. GİB e-Belge Duyuruları (ebelge.gib.gov.tr) · erişim 5 Kasım 2026
  4. VUK Genel Tebliği Sıra No 509, güncel metin (GİB, 2026) · erişim 5 Kasım 2026

İlgili Araç ve Sayfalar

İlgili Terimler

Bu işleri elle yapmayın

TicariHub; sipariş, e-fatura, stok, kargo ve ön muhasebeyi 30+ kanalda tek panelden otomatik yönetir.