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.
İçindekiler
- UBL-TR nedir, neden kullanılır?
- e-Fatura XML dosyasında hangi alanlar bulunur?
- Fatura satırı XML'de nasıl yazılır?
- Toplamlar ve vergiler nasıl tutar?
- İmza ve görsel şablon XML'in neresinde durur?
- Ret mesajları UBL-TR alanlarıyla nasıl eşleşir?
- PakERP One UBL-TR belgesini nasıl üretir?
- Sık sorulan sorular
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:
| Alan | Anlamı | Örnek ya da not |
|---|---|---|
| cbc:ProfileID | Senaryo | Temel, ticari, ihracat, e-Arşiv |
| cbc:ID | Fatura numarası | 16 hane: seri, yıl, sıra no |
| cbc:UUID | ETTN | Dünyada tek olan belge kimliği |
| cbc:IssueDate | Düzenleme tarihi | Yıl ay gün biçiminde |
| cbc:InvoiceTypeCode | Fatura tipi | SATIS, IADE, TEVKIFAT, ISTISNA, OZELMATRAH, IHRACKAYITLI |
| cbc:Note | Belge notları | Görselde faturanın altında |
| cbc:DocumentCurrencyCode | Belge para birimi | TRY, EUR, USD |
| cac:AccountingSupplierParty | Satıcı | Vergi no, unvan, adres |
| cac:AccountingCustomerParty | Alıcı | Vergi no, unvan, adres |
| cac:PricingExchangeRate | Döviz kuru | Dövizli faturada bulunur |
| cac:TaxTotal | Vergi toplamı | Oran, matrah, tutar, istisna kodu |
| cac:WithholdingTaxTotal | Tevkifat | Tevkifatlı faturada |
| cac:LegalMonetaryTotal | Toplamlar | Mal hizmet toplamı, vergiler dahil, ödenecek |
| cac:InvoiceLine | Fatura 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.
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ış:
| Alan | Anlamı | Örnek |
|---|---|---|
| LineExtensionAmount | Satırların toplamı | 10.000,00 |
| TaxExclusiveAmount | Vergiler hariç toplam | 10.000,00 |
| TaxInclusiveAmount | Vergiler dahil toplam | 12.000,00 |
| AllowanceTotalAmount | Toplam iskonto | 0,00 |
| PayableAmount | Ödenecek tutar | 12.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çen | Muhtemel sebep | Nereye bakılır |
|---|---|---|
| ID ya da numara | Biçim hatası ya da mükerrer numara | Seri ve sayaç |
| Alıcı ya da posta kutusu | Alıcı kayıtlı değil ya da kayıtlı ama e-Arşiv kesildi | Mükellef sorgusu |
| Vergi istisna kodu | Sıfır KDV'li satırda kod yok | Satırın istisna kodu |
| Kur | Dövizli faturada kur yok | Belge kuru |
| Toplam ya da tutar | Satır toplamı ile genel toplam tutmuyor | Yuvarlama, iskonto |
| Birim kodu | Birim listede yok | Birim 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.
- 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.
- Dövizli belge: para birimi döviz olan her faturaya kur bilgisi eklenir; kur yoksa belge kurulmaz ve kullanıcı uyarılır.
- 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.
- 102 Satış İrsaliyesi: sevk adresi, araç ve şoför bilgileri e-İrsaliye XML'ine yazılır.
- 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.