UBL Nedir? e-Fatura UBL-TR Formatı ve 'UBL İçeriği Hatalı' Hatası Nasıl Çözülür (2026)

e-Faturayı gönderdiniz, birkaç dakika sonra programınızda "UBL içeriği hatalı", "UBL yapısı hatalı" ya da "çevrim hatası" yazan bir uyarı belirdi. Fatura alıcıya gitti mi, ne yapmanız gerekiyor? Bu rehberde önce UBL nedir, UBL-TR ne işe yarar ve XML ile farkı ne, sade bir dille anlatıyoruz. Ardından bu hata mesajlarının en sık nedenlerini ve sizin tarafınızda yapılacak kontrolleri adım adım sıralıyoruz.

Yazı, faturasını kendi kesen işletme sahipleri ve müşterilerinin e-faturalarıyla uğraşan muhasebeciler için hazırlandı. Teknik ayrıntıyı en aza indirdik; bilgileri GİB'in yayımladığı kılavuzlardan ve kural dosyalarından aldık. Faturanın baştan sona nasıl düzenlendiğini merak ediyorsanız e-fatura kesme adımlarını anlattığımız rehbere de göz atabilirsiniz.

Kısa cevap: UBL (Universal Business Language), faturayı ve diğer ticari belgeleri bilgisayarların okuyabileceği ortak bir XML diliyle yazma standardıdır. Türkiye'de Gelir İdaresi Başkanlığı'nın (GİB) bu standarttan uyarladığı sürüme UBL-TR denir; e-Fatura ve e-Arşiv faturalar bu biçimde düzenlenir. "UBL içeriği hatalı" türündeki mesajlar genellikle faturanın XML dosyasının yapı (şema) ya da iş kuralı kontrolünden geçemediğini anlatır; mesajın metni ve tam anlamı kullandığınız programa ve entegratöre göre değişir.

UBL nedir, ne işe yarar?

UBL, İngilizce Universal Business Language ifadesinin kısaltmasıdır; Türkçede "Evrensel İş Dili" olarak geçer. Uluslararası standart kuruluşu OASIS tarafından geliştirilen açık bir standarttır. Sipariş, irsaliye ve fatura gibi ticari belgelerde hangi bilginin hangi adla ve nereye yazılacağını tarif eder.

Kâğıt faturada "Alıcı", "Miktar", "KDV" gibi alanları gözle okursunuz. Bilgisayarların aynı faturayı hatasız okuyabilmesi için bu alanların herkesin aynı şekilde kullandığı etiketlerle yazılması gerekir. UBL bu ortak etiket setidir: Sizin programınızın ürettiği fatura, alıcının programında yeniden yazılmadan okunabilir ve muhasebeye işlenebilir.

UBL'nin işletmenize pratikte kazandırdıkları:

• Tek biçim: Hangi programı kullanırsanız kullanın, e-faturanız aynı kurallara göre oluşur.
• Otomatik okuma: Alıcı, gelen faturayı elle girmeden kendi sistemine aktarabilir.
• Makineyle denetim: Faturanın zorunlu alanlarının dolu ve tutarlı olup olmadığı, fatura alıcıya gitmeden önce otomatik kontrol edilebilir.

UBL'nin kısa tarihi

GİB'in UBL-TR kılavuz paketindeki genel açıklamalar belgesine göre UBL 1.0 2004'te yayımlandı ve 2006'da UBL 2.0'a geliştirildi. Bugün Türkiye'de esas alınan UBL 2.1 ise 4 Kasım 2013'te standartlaştı. UBL 2.1, 66 ticari belge türünün XML tanımını içerir; fatura bunlardan yalnızca biridir.

UBL-TR nedir?

UBL-TR, GİB'in UBL 2.1 standardını Türkiye'deki vergi kurallarına göre uyarladığı biçimdir; kılavuzlardaki adıyla "UBL 2.1 Türkiye Özelleştirmesi". GİB, 2009'da başlattığı e-Fatura uygulamasında belge biçimi olarak UBL'yi esas aldı. Türkiye'ye özgü bilgiler, örneğin VKN/TCKN, fatura senaryosu (temel, ticari, e-Arşiv vb.), fatura tipi (satış, iade, tevkifat, istisna vb.) ve vergi kodları UBL-TR'de tanımlanır.

UBL-TR'yi oluşturan üç parça vardır ve hepsi GİB'in e-belge sitesinde yayımlanır:

• Şema (XSD): Faturada hangi alanların, hangi sırayla ve hangi biçimde bulunacağını belirleyen iskelet.
• Kod listeleri: Birim, vergi, istisna, para birimi gibi alanlara yazılabilecek geçerli kodlar.
• Schematron (iş kuralları): "KDV'si sıfır olan satırda istisna sebebi bulunmalı" gibi mantık kontrolleri.

Şema ile iş kuralı arasındaki fark, hata mesajlarını anlamanın da anahtarıdır; aşağıda bu ayrıma tekrar döneceğiz.

Güncel sürüm: UBL-TR 1.2.1

GİB'in e-belge duyurularında güncel paketin adı UBL-TR 1.2.1'dir. Sürüm numarası 2026'da değişmedi, ancak paket ve kod listeleri yıl içinde birkaç kez güncellendi. En son 27.07.2026 tarihli duyuruyla e-Fatura paketi, e-Arşiv fatura paketi ve UBL-TR kod listeleri kılavuzu güncellendi; güncellemelerin 14.09.2026 itibarıyla devreye alınacağı bildirildi. Kod listeleri kılavuzunun bu güncellemeyle yayımlanan sürümü V1.43'tür.

İnternette sık geçen 16.03.2026 tarihli güncellemeye dikkat edin. GİB bu tarihte faaliyet koduna göre KDV oranı kontrolü için paketleri güncellediğini duyurmuştu. Ancak 27.03.2026 tarihli duyuruyla bu kontrol ikinci bir duyuruya kadar ertelendi ve 16.03.2026 güncellemesi için işlem yapılmayacağı açıklandı. Güncel durumu her zaman GİB e-Belge duyurular sayfasından kontrol edebilirsiniz.

Kod listelerini takip etmek programınızın ve entegratörünüzün işidir. Siz çoğu zaman yalnızca yeni bir seçeneği, örneğin listeye eklenmiş bir istisna kodunu seçme imkânı olarak görürsünüz.

UBL ile XML aynı şey mi?

Hayır. XML bir veri yazım biçimidir, UBL ise bu biçimle hazırlanmış bir ticari belge standardıdır. Bir benzetmeyle: XML alfabe ve dilbilgisiyse UBL o dilde yazılmış resmî bir form, UBL-TR de bu formun Türkiye'ye özel doldurma kılavuzudur. Her UBL faturası bir XML dosyasıdır, ama her XML dosyası UBL faturası değildir.

Son satırın dayanağı GİB'in E-Fatura Görüntüleyici kullanım kılavuzudur: Kılavuza göre e-Faturanın kâğıt çıktısının veya e-postayla gönderilen kopyasının asıl belge yerine kullanılması uygun değildir. e-Arşiv faturanın alıcıya iletilme kuralları farklıdır; bunun için e-Fatura ile e-Arşiv fatura arasındaki farkları anlattığımız yazıya bakabilirsiniz.

Kısa bir UBL-TR örneği

Aşağıdaki satırlar GİB'in UBL-TR 1.2.1 paketindeki örnek faturadan sadeleştirildi; fatura numarası ve tarih örnektir. Gerçek bir fatura XML'i yüzlerce satırdır, ancak hata mesajlarında adı geçen alanların çoğu bu birkaç satırda görünür.

UBL (XML) fatura dosyası nasıl açılır?

E-postayla ya da bir portaldan .xml veya .zip uzantılı bir fatura geldiyse, dosyayı çift tıkladığınızda tarayıcıda anlamsız görünen etiketlerle karşılaşabilirsiniz. Bu normaldir: XML faturanın verisidir. Okunabilir görünüm ise XML'in içine eklenen XSLT adlı bir görüntüleme şablonuyla oluşur. Faturayı okumak için şu yollardan birini kullanın:

1. E-fatura programınız veya entegratörünüzün portalı: Gelen ve giden e-faturalar bu ekranlarda görüntü olarak açılır; en pratik yol budur.
2. GİB'in E-Fatura Görüntüleyici programı: GİB'in kullanım kılavuzuna göre program XML'i açar ve faturayı görüntü olarak gösterir. Ayrıca mali mühür imzasını doğrular ve faturanın GİB'den başarıyla geçip geçmediğini sorgulayabilir. Kılavuza göre programın çalışması için bilgisayarda Java yüklü olmalıdır.
3. Metin düzenleyici veya tarayıcı: İçindeki bilgilere hızlıca bakmak için yeterlidir, ama görüntüyü değil ham XML'i görürsünüz.

Açarken sık karşılaşılan üç durum:

• Dosya ZIP ise önce arşivden çıkarın; görüntüleyiciler .xml dosyasını açar.
• Yalnızca XML görünüyor, fatura görüntüsü gelmiyorsa faturada XSLT şablonu olmayabilir ya da şablon hatalı olabilir. GİB görüntüleyicisi bu durumda faturayı GİB'in varsayılan şablonuyla göstermeyi önerir.
• Dosyanın ikinci satırında "StandardBusinessDocument" yazıyorsa açtığınız şey faturanın kendisi değil, onu taşıyan zarftır. Fatura, <Invoice ile başlayan bölümdür. GİB kılavuzu bu ayıklamanın bir yazılımla yapılmasını önerir, çünkü tek karakterlik bir değişiklik bile imzayı bozar.

Aynı nedenle fatura XML'inde elle değişiklik yapmayın: İmza doğrulaması bozulur ve görüntüleyici faturanın değiştirildiğini gösterir. Bilgi yanlışsa düzeltme, faturayı düzenleyen tarafın programında yapılır.

'UBL İçeriği Hatalı', 'UBL Yapısı Hatalı' ve 'Çevrim Hatası' ne demek?

Önce önemli bir not: Bu ifadeler GİB'in resmî durum kodu adları değildir. Programlar ve özel entegratörler, GİB'den ya da kendi kontrollerinden dönen sonucu kendi cümleleriyle gösterir. Aynı hata bir programda "UBL içeriği hatalı", başka birinde "XML doğrulama hatası" diye görünebilir. Bu yüzden aşağıdaki açıklamalar genel çerçevedir; kesin anlam için mesajın ayrıntısına ve sağlayıcınızın açıklamasına bakın.

Mesajın genel anlamı

Fatura gönderildiğinde XML dosyası iki temel kontrolden geçer:

• Şema (yapı) kontrolü: Alanlar doğru adla, doğru sırada ve doğru biçimde mi? "Yapısı hatalı" türündeki mesajlar çoğunlukla bu kontrole işaret eder.
• Schematron (iş kuralı) kontrolü: Kodlar geçerli mi, alanlar birbiriyle tutarlı mı? "İçeriği hatalı" türündeki mesajlar çoğunlukla bu kontrole işaret eder.

GİB'in e-Fatura sistem yanıtı kılavuzunda bu iki kontrolün resmî durum kodları vardır: 1150 "Schematron kontrol sonucu hatalı" ve 1160 "XML şema kontrolünden geçemedi". Kılavuza göre işleme sırasındaki hata kodları 1100 ile 1200 arasındadır ve böyle bir hatada zarf bir sonraki aşamaya geçmez; yani fatura alıcıya ulaşmamıştır. Bazı sağlayıcılar benzer kontrolleri faturayı GİB'e iletmeden önce kendi sisteminde de yapabilir; bu durumda hata GİB koduyla değil, sağlayıcının kendi mesajıyla döner.

En sık 7 neden ve çözümü

Aşağıdaki tablo, GİB'in güncel e-Fatura paketindeki Schematron kural dosyasından derlendi. Ortadaki sütun, kural dosyasındaki hata metninin özüdür; programınız aynı hatayı farklı bir cümleyle gösterebilir.

Kural dosyasında bunların dışında fatura numarasının biçimi (3 karakter, yıl ve 9 haneli sıra numarası; örneğin ABC2026000000001) ve 01.01.2005'ten önceki tarihler de kontrol edilir. Bu alanları genellikle program kendisi doldurur.

Örnek senaryo: 12 kişilik bir hırdavat toptancısı, yeni gelen ürünler için stok kartlarında "Kutu" birimini açıyor ama birimin UBL kodunu boş bırakıyor. O gün kesilen faturalardan yalnızca kutu birimli satırı olan geri dönüyor; yalnızca "Adet" kullanılan faturalar sorunsuz gidiyor. Birim tanımına BX kodu girildikten sonra fatura yeniden gönderiliyor. Tek bir faturada hata alıp diğerlerinde almıyorsanız, önce o faturaya özgü bilgiye (yeni birim, yeni cari, istisnalı satır) bakın.

'Çevrim hatası' ne olabilir?

"Çevrim" burada dönüştürme anlamına gelir. Bu ifade genellikle programın fatura bilgilerini UBL-TR XML'ine dönüştürürken ya da gelen bir XML'i okurken takıldığını anlatabilir; yani hata GİB'e gitmeden, programın veya entegratörün kendi tarafında oluşmuş olabilir. Mesajın başında görünen numaralar da GİB durum kodu olmayabilir, sağlayıcının kendi iç numarası olabilir. Çevrim hatasında en hızlı çözüm, hata metnini ve fatura numarasını kopyalayıp program desteğinize iletmektir.

Hata alınca adım adım ne yapmalı?

Paniğe gerek yok; hatalı dönen bir fatura çoğu zaman tek bir alanın düzeltilmesiyle çözülür. Şu sırayı izleyin:

1. Faturanın GİB'den geçip geçmediğini öğrenin. Durumda 1100-1200 aralığında bir hata kodu ya da "gönderilemedi" ifadesi varsa fatura alıcıya ulaşmamıştır. GİB'in görüntüleyici kılavuzuna göre GİB sisteminden geçmemiş bir fatura geçersizdir; bu durum, alıcıya ulaşmış bir faturanın iptalinden farklıdır.
2. Hata metnini olduğu gibi kopyalayın. Ekran görüntüsü yerine metni almak, hangi alanın hatalı olduğunu görmenizi kolaylaştırır.
3. Metindeki alan adını nedenle eşleştirin. unitCode birimi, TaxExemptionReason istisna sebebini, VKN/TCKN kimlik numarasını, IssueDate tarihi, CurrencyCode ve CalculationRate para birimi ile kuru gösterir.
4. Kaynağı düzeltin, XML'i değil. Birim tanımını, cari kartı veya fatura satırını programda düzeltin; XML dosyasını elle düzenlemeyin.
5. Aynı nedenden etkilenen başka fatura var mı, bakın. Yeni açılan bir birim veya cari kart birden fazla faturayı etkileyebilir.
6. Yeniden gönderin ve durumu izleyin. Alıcıya ulaşan faturada GİB'in son durumu 1300 "Başarıyla tamamlandı" olarak görünür.
7. Çözemediyseniz desteğe eksiksiz bilgiyle gidin. Hata metni, fatura numarası ve mümkünse faturanın XML dosyasıyla başvurmak çözümü hızlandırır.

Fatura alıcıya ulaştıktan sonra fark ettiğiniz bir yanlışlık ise artık UBL hatası değildir; iptal, itiraz veya iade faturası gibi yollar gündeme gelir. Bu ayrımı ve GİB durum kodlarının anlamını e-fatura durum kodları ne anlama geliyor yazımızda ayrıntılı anlattık.

Evobulut'ta UBL ile ilgili işlemler

UBL'nin teknik ayrıntısı programın işidir; sizin kontrol etmeniz gereken, programdaki tanımların doğru olmasıdır. Evobulut e-Fatura Programı'nda UBL ile ilgili üç işlem öne çıkar.

Birimlere UBL kodu tanımlama

Stok birimlerinizin UBL karşılığını Ayarlar > Referans Kayıtları > Satış Tanımları > Birim ekranında, her birimin "UBL Kodu" alanına girersiniz. Sık kullanılan kodlar şunlardır:

Tam liste e-Fatura UBL kodlarının kullanımı kılavuzunda yer alır. Yeni bir birim açtığınızda UBL kodunu da aynı anda girmek, birim kaynaklı hataların önüne geçer.

Başka programdan UBL/XML fatura aktarma

Program değiştirirken eski faturalarınızı tek tek girmeniz gerekmez. UBL/XML faturaları bir ZIP arşivinde toplayıp Evobulut'a toplu olarak yükleyebilirsiniz.

Aktarım sırasında faturadaki cari VKN/TCKN'ye göre aranır; kayıtlıysa mevcut kart kullanılır, değilse yeni cari kart açılır. Stoklar da stok koduna göre eşleştirilir ya da yeni stok kartı oluşturulur. Adımları UBL/XML fatura aktarımı kılavuzunda bulabilirsiniz.

Hatalı e-faturaları görme ve çözme

Geri dönen faturalar Hatalı E-Faturalar ekranında listelenir. Burada her faturanın hata kodunu ve hata açıklamasını görürsünüz. Faturadaki sorunu düzelttikten sonra "Çöz" düğmesiyle kaydı çözüme bağlayıp faturayı yeniden gönderirsiniz; "Çözülen Faturalar" görünümünde hatayı kimin ve ne zaman düzelttiğini izleyebilirsiniz. Ayrıntılar hatalı e-faturaların kontrolü kılavuzunda.

Özet ve sonraki adım

UBL, faturanın makinelerin okuyabildiği ortak dilidir; UBL-TR bu dilin GİB kurallarıyla Türkiye'ye uyarlanmış hâlidir. e-Fatura ve e-Arşiv faturanın arka planında her zaman bir UBL-TR XML dosyası bulunur. "UBL içeriği hatalı", "yapısı hatalı" veya "çevrim hatası" gibi mesajlar bu dosyanın bir kontrolden geçemediğini söyler. En sık nedenler birim kodu, istisna sebebi, VKN/TCKN, kuruş hanesi, senaryo ile fatura tipi uyumu, tevkifat ve tarih ya da kur alanlarıdır.

Bugün yapabileceğiniz en faydalı kontrol, programınızdaki tüm stok birimlerinin UBL kodunun dolu olduğuna bakmaktır. Sık kestiğiniz istisnalı ya da tevkifatlı faturalarda doğru tipin seçildiğini de mali müşavirinizle bir kez teyit edin.

e-Faturalarınızı, birim tanımlarınızı ve hatalı faturalarınızı tek ekrandan yönetmek için Evobulut'u 14 gün ücretsiz deneyin.

Sıkça sorulan sorular

UBL nedir, açılımı ne?

UBL, Universal Business Language ifadesinin kısaltmasıdır; Türkçede "Evrensel İş Dili" olarak geçer. OASIS tarafından geliştirilen, fatura ve sipariş gibi ticari belgeleri XML ile ortak bir yapıda yazmayı sağlayan uluslararası bir standarttır.

UBL-TR ile UBL arasındaki fark nedir?

UBL uluslararası genel standarttır; UBL-TR ise GİB'in UBL 2.1'i Türkiye'deki vergi kurallarına göre uyarladığı sürümdür. UBL-TR; VKN/TCKN, fatura senaryosu, fatura tipi ve Türkiye'ye özgü vergi ve istisna kodları gibi alanları ve bunların kurallarını ekler. Güncel paketin adı UBL-TR 1.2.1'dir.

UBL ile XML aynı şey mi?

Hayır. XML bir veri yazım biçimidir; UBL ise XML ile yazılan bir ticari belge standardıdır. Her UBL faturası bir XML dosyasıdır, ancak her XML dosyası UBL faturası değildir.

UBL formatındaki fatura nasıl açılır?

En kolay yol, faturayı e-fatura programınızda veya entegratörünüzün portalında açmaktır. Elinizde yalnızca dosya varsa GİB'in E-Fatura Görüntüleyici programıyla .xml dosyasını görüntüleyebilirsiniz; dosya ZIP olarak geldiyse önce arşivden çıkarın.

'UBL içeriği hatalı' ne demek?

Genellikle faturanın XML dosyasının GİB iş kurallarından (Schematron) ya da programın veya entegratörün kendi kontrollerinden geçemediğini anlatır. Mesajın metni ve tam anlamı sağlayıcıya göre değişir; sık nedenler hatalı birim kodu, eksik istisna sebebi ve hatalı VKN/TCKN'dir. Hata ayrıntısındaki alan adı, neyin düzeltileceğini gösterir.

'UBL çevrim hatası' neden olur?

Çevrim hatası genellikle programın fatura bilgisini UBL-TR XML'ine dönüştürürken ya da bir XML'i okurken takıldığını anlatır. Hata GİB'e gitmeden oluşmuş olabilir ve anlamı sağlayıcıya göre değişir; hata metnini ve fatura numarasını program desteğinize iletin.

UBL birim kodu nedir, 'Adet' için hangi kod kullanılır?

UBL birim kodu, faturadaki miktarın hangi ölçü birimiyle yazıldığını gösteren uluslararası koddur. Adet için C62 kullanılır; kilogram için KGM, litre için LTR, metre için MTR ve kutu için BX de GİB'in kabul ettiği listededir.

e-Arşiv fatura da UBL formatında mı?

Evet. e-Arşiv fatura da UBL-TR formatında düzenlenir; GİB'in kod listesinde e-Arşiv için ayrı bir senaryo (EARSIVFATURA) tanımlıdır. Alıcıya iletilme şekli e-Faturadan farklı olsa da faturanın verisi yine bir UBL-TR XML dosyasıdır.