1. Ana Sayfa
  2. Üretim Dünyası
  3. UBL-TR Nedir
e-Belge Rehberi · Temel

UBL-TR Nedir? e-Faturanın XML Yapısını Alan Alan Okumak

PakERP One Ekibi 9 dk okuma
Kısa cevap

UBL-TR, uluslararası UBL 2.1 standardının Türkiye için uyarlanmış hâlidir ve e-Fatura, e-Arşiv ve e-İrsaliye belgelerinin XML biçimini belirler. Faturanın kendisi bu XML dosyasıdır; PDF yalnız görüntüsüdür. Dosyada senaryo, fatura tipi, 16 haneli numara, ETTN, satıcı ve alıcı, vergi toplamları, ödenecek tutar ve satırlar belirli etiketlerin içinde yazılır. Entegratörden gelen ret mesajlarının çoğu bu alanlardan birine işaret eder.

Muhasebeci e-Faturayı ekranda düzgün bir sayfa olarak görür: logo, tablo, toplamlar. Ama o sayfa faturanın kendisi değildir; faturanın kendisi arka plandaki XML dosyasıdır ve sayfa bu dosyadan bir şablonla çizilir. Entegratör "TaxExemptionReasonCode alanı zorunludur" ya da "PricingExchangeRate bulunmalıdır" gibi bir ret mesajı döndürdüğünde, mesaj bu dosyadaki bir alandan bahseder.

Bu yazı yazılımcılar için değil, e-Fatura kesen ve ret mesajı okuyan muhasebe ve satış ekipleri için yazıldı. UBL-TR'nin ne olduğunu, bir e-Fatura dosyasında hangi alanların bulunduğunu ve sık görülen ret mesajlarının hangi alana karşılık geldiğini anlatıyoruz. e-Faturanın genel işleyişi için e-Fatura nedir yazısına bakabilirsiniz.

UBL-TR nedir, neden kullanılır?

UBL, ticari belgelerin bilgisayarlar arasında ortak bir dille alınıp verilmesi için geliştirilmiş uluslararası bir XML standardıdır. Fatura, irsaliye, sipariş gibi belgelerin hangi alanlardan oluşacağını ve bu alanların nasıl adlandırılacağını tanımlar. UBL-TR ise bu standardın 2.1 sürümünün Gelir İdaresi tarafından Türkiye'nin vergi kurallarına göre uyarlanmış hâlidir.

Ortak bir format kullanılmasının sebebi basittir: satıcının programı ile alıcının programı birbirini tanımaz, ama ikisi de UBL-TR'yi tanır. Satıcının programı faturayı bu formatta üretir, alıcının programı aynı formatı okuyup alış faturasına çevirir. Arada kimse faturayı elle yeniden yazmaz.

UBL-TR yalnız e-Faturada değil, e-Arşiv faturada ve e-İrsaliyede de kullanılır. e-Faturanın kök belgesi fatura, e-İrsaliyenin kök belgesi sevk bildirimidir; alanların çoğu ortaktır. Yasal çerçeve VUK 509 sıra no.lu Genel Tebliğ ile çizilir, teknik ayrıntılar GİB'in e-Belge sitesinde yayımlanan kılavuzlar, şemalar ve kod listeleriyle belirlenir. Kod listeleri zaman zaman güncellendiği için programınızın güncel listeyi kullandığından emin olun.

e-Fatura XML dosyasında hangi alanlar bulunur?

Bir e-Fatura dosyası üst bilgi, taraflar, toplamlar ve satırlar olmak üzere dört kısımdan oluşur. Alan adları İngilizcedir ve iki önekle yazılır: cbc öneki tek bir değeri, cac öneki birden fazla alan içeren bir grubu gösterir. Aşağıdaki tablo sahada en çok karşılaşılan alanları açıklar:

AlanAnlamıÖrnek ya da not
cbc:ProfileIDSenaryoTemel, ticari, ihracat, e-Arşiv
cbc:IDFatura numarası16 hane: seri, yıl, sıra no
cbc:UUIDETTNDünyada tek olan belge kimliği
cbc:IssueDateDüzenleme tarihiYıl ay gün biçiminde
cbc:InvoiceTypeCodeFatura tipiSATIS, IADE, TEVKIFAT, ISTISNA, OZELMATRAH, IHRACKAYITLI
cbc:NoteBelge notlarıGörselde faturanın altında
cbc:DocumentCurrencyCodeBelge para birimiTRY, EUR, USD
cac:AccountingSupplierPartySatıcıVergi no, unvan, adres
cac:AccountingCustomerPartyAlıcıVergi no, unvan, adres
cac:PricingExchangeRateDöviz kuruDövizli faturada bulunur
cac:TaxTotalVergi toplamıOran, matrah, tutar, istisna kodu
cac:WithholdingTaxTotalTevkifatTevkifatlı faturada
cac:LegalMonetaryTotalToplamlarMal hizmet toplamı, vergiler dahil, ödenecek
cac:InvoiceLineFatura satırıHer satır için bir grup

Senaryo ile fatura tipi sık karıştırılır. Senaryo, alıcının yanıt hakkını ve belgenin hangi kanaldan gideceğini belirler; fatura tipi, vergi hesabının türünü. Senaryo farkı temel fatura ile ticari fatura farkı yazısında, tipler e-Fatura tipleri ve senaryoları yazısında.

Sahadan not

Faturada bir bilginin görünmediği şikâyetlerinin önemli kısmında bilgi XML'de zaten vardır; görünmemesinin sebebi entegratörün varsayılan şablonunun o alanı çizmemesidir. Önce XML'e bakmak, programı değiştirmeye kalkmadan sorunu şablona indirger.

Fatura satırı XML'de nasıl yazılır?

Her fatura satırı bir cac:InvoiceLine grubudur. Grubun içinde satır numarası, miktar ve birimi, satır tutarı, satırın vergisi, mal ya da hizmetin adı ve birim fiyatı bulunur. Satırın en sık hata çıkaran kısımları şunlardır:

  • Birim kodu. Miktar bir birim koduyla yazılır ve bu kod serbest metin değil, uluslararası birim kod listesinden gelir. Adet için C62, kilogram için KGM, metre için MTR yaygın kodlardır. Programdaki birim kartı bu koda eşlenmemişse ret gelir.
  • Mal adı. Görselde basılan ad bu alandan gelir. Stok kodu ile stok adının birlikte yazılması, alıcının muhasebesinin satırı eşlemesini kolaylaştırır.
  • Satır vergisi. KDV oranı ve tutarı satırda da yazılır. Oran sıfırsa satıra istisna sebebi kodu eklenir; kodlar e-Faturada KDV istisna kodları yazısında.
  • Yuvarlama. Satır tutarlarının toplamı, toplamlar grubundaki tutarla kuruşu kuruşuna tutmalıdır. Satırda birim fiyat ve miktar çarpımı ile yazılan tutar arasındaki küçük farklar bile ret sebebidir.

Bazı belge türlerinde satıra ek alanlar gelir. Örneğin teşvikli satışta makine adı ve sıra numarası gibi bilgiler satırda yer alır; tevkifatlı satışta satıra tevkifat bilgisi eklenir. Bu alanların görselde sütun olarak görünüp görünmemesi şablona bağlıdır.

Toplamlar ve vergiler nasıl tutar?

cac:LegalMonetaryTotal grubu faturanın parasal özetidir ve alıcının ödeyeceği tutar bu gruptan okunur. Grubun alanlarını bir örnekle anlatalım. Temsili rakamlarla, 10.000 TL tutarında, %20 KDV'li bir satış:

AlanAnlamıÖrnek
LineExtensionAmountSatırların toplamı10.000,00
TaxExclusiveAmountVergiler hariç toplam10.000,00
TaxInclusiveAmountVergiler dahil toplam12.000,00
AllowanceTotalAmountToplam iskonto0,00
PayableAmountÖdenecek tutar12.000,00

Ödenecek tutarın vergiler dahil toplamdan farklı olduğu durumlar vardır. Tevkifatlı faturada alıcının beyan edeceği KDV kısmı ödenecek tutardan düşülür; istisnalı faturada KDV tutarı sıfır olduğu için ödenecek tutar matraha eşittir. Bu farkların her biri belge tipiyle uyumlu olmalıdır; tip SATIS iken ödenecek tutarın vergiler dahil toplamdan düşük olması ret sebebidir.

Dövizli faturada ayrıca kur bilgisi bulunmak zorundadır. Belge para birimi döviz iken kur grubu eksikse entegratör belgeyi reddeder. Dövizli faturanın ayrıntıları dövizli e-Fatura nasıl kesilir yazısında.

İmza ve görsel şablon XML'in neresinde durur?

Dosyanın başında bir uzantı alanı bulunur ve elektronik imza bu alanın içine yerleştirilir. İmza, dosyanın tamamını kapsar; imzadan sonra herhangi bir alan değiştirilirse imza doğrulaması başarısız olur. Bu yüzden gönderilmiş bir e-Faturanın XML'ini düzenleyip yeniden göndermek mümkün değildir; düzeltme yeni belgeyle yapılır. İmzanın kim tarafından atıldığı yönteme bağlıdır; ayrıntı mali mühür nedir yazısında.

Görsel şablon ise XML'e ek belge olarak gömülebilir. Şablon bir XSLT dosyasıdır ve XML'deki alanların sayfada nasıl çizileceğini tarif eder. Şablon gömülü değilse alıcının ya da entegratörün varsayılan şablonu kullanılır ve fatura beklediğinizden farklı görünebilir. Örneğin satırlara eklenmiş özel bilgiler varsayılan şablonda hiç görünmeyebilir. Şablonun nasıl hazırlanıp gömüldüğü e-Fatura tasarımı ve XSLT yazısında.

Buradan çıkan pratik ders şudur: "faturada şu bilgi görünmüyor" şikâyetinde önce XML'e bakılır. Bilgi XML'de varsa sorun şablondadır; XML'de yoksa programın o alanı hiç yazmadığı anlaşılır.

Ret mesajları UBL-TR alanlarıyla nasıl eşleşir?

Entegratör ve GİB belgeyi şema ve iş kuralı denetimlerinden geçirir. Ret mesajı genellikle bir alan adı ya da bir kural içerir. Mesajı doğru alana bağlamak çözümü hızlandırır:

Mesajda geçenMuhtemel sebepNereye bakılır
ID ya da numaraBiçim hatası ya da mükerrer numaraSeri ve sayaç
Alıcı ya da posta kutusuAlıcı kayıtlı değil ya da kayıtlı ama e-Arşiv kesildiMükellef sorgusu
Vergi istisna koduSıfır KDV'li satırda kod yokSatırın istisna kodu
KurDövizli faturada kur yokBelge kuru
Toplam ya da tutarSatır toplamı ile genel toplam tutmuyorYuvarlama, iskonto
Birim koduBirim listede yokBirim kartı eşlemesi

Mükerrer numara ve posta kutusu hataları en sık görülenlerdir. Numara biçimi e-Fatura numarası formatı, alıcı durumu e-Fatura mükellef sorgulama yazısında. Ret mesajlarının uzun listesi mevcut e-belge ret nedenleri rehberinde.

PakERP One UBL-TR belgesini nasıl üretir?

PakERP One satış faturasını ve irsaliyesini kaydettiğiniz anda UBL-TR belgesini kendisi üretir ve göndermeden önce zorunlu alanları denetler; kullanıcı XML ile uğraşmaz. Program ve bulut sunucu ücretsizdir; gönderim Digital Planet ya da Sovos özel entegratörüyle yapılır ve entegratör bedeli entegratöre aittir.

  1. 101 Satış Faturası: senaryo ve fatura tipi belgeden belirlenir: iade, tevkifat, istisna ya da teşvikli satış seçildiğinde ilgili alanlar XML'e yazılır. Sıfır KDV'li satırda istisna kodu sorulur.
  2. Dövizli belge: para birimi döviz olan her faturaya kur bilgisi eklenir; kur yoksa belge kurulmaz ve kullanıcı uyarılır.
  3. Notlar ve kalem adı: belge notları faturanın altında görünecek şekilde yazılır; kalem adına stok kodu ve stok adı birlikte gelir.
  4. 102 Satış İrsaliyesi: sevk adresi, araç ve şoför bilgileri e-İrsaliye XML'ine yazılır.
  5. Evrak eki: gelen belgelerin UBL ve PDF dosyası 961 Gelen e-Faturalar ekranından alınan kaydın eki olarak saklanır; istendiğinde XML açılıp incelenebilir.

Ayrıntılar e-Belge modülü sayfasında; e-belge ret mesajlarının çözümü mevcut e-Fatura ve e-İrsaliye rehberinde.

Kaynaklar

Sık Sorulan Sorular

UBL-TR nedir?
Uluslararası UBL 2.1 standardının Gelir İdaresi tarafından Türkiye'nin vergi kurallarına göre uyarlanmış hâlidir. e-Fatura, e-Arşiv ve e-İrsaliye belgelerinin XML biçimini belirler.
e-Faturanın asıl belgesi PDF mi XML mi?
Asıl belge imzalı XML dosyasıdır. PDF ya da ekrandaki sayfa, XML'in bir şablonla çizilmiş görüntüsüdür ve tek başına fatura değildir.
ETTN nedir?
Her e-belgeye verilen ve dünyada başka hiçbir belgeyle çakışmayan evrensel tekil numaradır. XML'de UUID alanında yazılır. Fatura numarası insanların, ETTN sistemlerin belgeyi tanımasını sağlar.
Gönderilmiş e-Faturanın XML'i düzeltilebilir mi?
Düzeltilemez. Belge imzalanmıştır; imzadan sonra yapılan her değişiklik imzayı bozar. Hatalı belge iptal, red ya da iade yoluyla kapatılır ve gerekiyorsa yeni belge düzenlenir.
Faturada bir bilgi görünmüyorsa sebep ne olabilir?
Önce XML'e bakılır. Bilgi XML'de varsa görünmemesinin sebebi görsel şablondur; şablon o alanı çizmiyordur. XML'de yoksa program o alanı hiç yazmamıştır.
PE
PakERP One Ekibie-Fatura ve e-Belge rehberleri, programı geliştiren ekip tarafından yazılır. Son güncelleme: .

e-Faturayı PakERP One ile ücretsiz kesin

PakERP One masaüstü program ve bulut sunucu ücretsiz; kullanıcı ve modül sınırı yok, hesap programın içinden açılır.