UBL-TR Zorunlu Alanlar ve Sık Yapılan Hatalar
UBL-TR e-fatura XML'inde zorunlu alanlar beş mantıksal blokta toplanır: belge kimliği, taraf bilgileri, satır kalemleri, vergi alanları ve toplamlar. Bu blokların hangi alanları içermesi gerektiği GİB'in yayımladığı XSD şema dosyalarında tanımlıdır ve şemaya uymayan belge sistem tarafından reddedilir.
Bu yazı, e-fatura entegrasyonu geliştiren yazılımcılar ve XML üreten sistemleri denetleyen muhasebeciler için hazırlandı. Alanları blok blok ele alıp, sahada en çok karşılaşılan hataları ve sebeplerini anlatıyoruz.
Blok 1: Belge kimliği alanları
Faturanın kim olduğunu tanımlayan çekirdek alanlardır. Bunlar eksikse belge hiçbir aşamada işlem görmez.
- UBLVersionID ve CustomizationID — kullanılan UBL sürümü ve Türkiye özelleştirmesi
- ProfileID — fatura senaryosu (temel, ticari, ihracat, yolcu beraberi…)
- ID — fatura numarası; 3 harfli birim kodu, 4 haneli yıl ve 9 haneli sıra numarasından oluşan 16 karakterlik yapı
- UUID — belgeye özgü, tekrar etmeyen benzersiz kimlik
- IssueDate — düzenleme tarihi
- InvoiceTypeCode — fatura tipi (satış, iade, tevkifat, istisna…)
- DocumentCurrencyCode — para birimi
Fatura numarası formatı en sık hata üretilen yerdir. 16 karakterlik yapının dışına çıkan, yıl bilgisi düzenleme tarihiyle uyuşmayan veya seride boşluk bırakan numaralar reddedilir.
Blok 2: Taraf bilgileri (satıcı ve alıcı)
AccountingSupplierParty satıcıyı, AccountingCustomerParty alıcıyı tanımlar. Her iki taraf için de vergi kimlik bilgisi, unvan ve adres zorunludur.
- VKN veya TCKN — tüzel kişilerde 10 haneli VKN, gerçek kişilerde 11 haneli TCKN
- PartyName — ticari unvan
- PostalAddress — adres, ilçe, il ve ülke bilgisi
- TaxScheme — bağlı olunan vergi dairesi
Sahada en çok görülen hata, alıcının VKN'sinin hatalı veya eksik hane ile yazılmasıdır. Bir diğeri, gerçek kişi alıcıya TCKN yerine VKN alanının kullanılmasıdır; şema bunu yakalar ve belge geri döner.
Blok 3: Satır kalemleri
InvoiceLine bloğu, faturadaki her mal veya hizmet satırını taşır. Her satırda kalem sırası, miktar, birim, birim fiyat ve satır toplamı bulunmalıdır.
- ID — satır numarası
- InvoicedQuantity — miktar ve birim kodu (adet, kg, saat…)
- LineExtensionAmount — satırın vergi hariç tutarı
- Item/Name — mal veya hizmetin adı
- Price/PriceAmount — birim fiyat
- TaxTotal — satıra ait vergi bilgisi
Birim kodları uluslararası UN/ECE listesinden gelir. 'adet' yerine serbest metin yazmak şema hatasına yol açar. Miktar × birim fiyat sonucunun satır toplamıyla tutmaması ise en yaygın tutarlılık hatasıdır.
Blok 4: Vergi alanları
TaxTotal ve içindeki TaxSubtotal blokları, KDV ve diğer vergileri taşır. Her vergi için matrah, oran ve hesaplanan tutar ayrı ayrı belirtilir.
- TaxableAmount — verginin matrahı
- TaxAmount — hesaplanan vergi tutarı
- Percent — vergi oranı
- TaxCategory/TaxScheme — vergi türü kodu
İstisna veya tevkifat söz konusuysa ilgili kod alanları da doldurulmalıdır. KDV istisnası uygulanan bir faturada istisna sebep kodunun boş bırakılması, belgenin reddedilme sebeplerinden biridir.
Blok 5: Toplamlar
LegalMonetaryTotal bloğu faturanın mali özetidir. Buradaki rakamların satırlardan matematiksel olarak türetilebilir olması gerekir.
- LineExtensionAmount — satır toplamlarının toplamı
- TaxExclusiveAmount — vergi hariç tutar
- TaxInclusiveAmount — vergi dahil tutar
- AllowanceTotalAmount — toplam iskonto
- PayableAmount — ödenecek tutar
XSLT şablonu da zorunludur
Teknik alanların dışında bir zorunluluk daha vardır: her e-Fatura XML'i, kendi görüntüsünü üreten XSLT şablonunu içinde barındırmak zorundadır. Şablon, belgeye base64 kodlu olarak gömülür.
Hukuki açıdan kritik nokta şudur: XSLT ile üretilen görüntü ile XML'deki veri çeliştiğinde esas alınan XML'deki veridir. Görüntü yalnızca sunum katmanıdır; mali denetimde bakılan şey veridir.
En sık karşılaşılan beş hata
- Fatura numarası formatının 16 karakterlik yapıya uymaması
- Satır toplamları ile genel toplam arasında kuruş düzeyinde yuvarlama farkı
- Birim kodunun standart listede bulunmayan bir değer olması
- İstisna veya tevkifat kodunun eksik bırakılması
- UUID'nin tekrar etmesi — aynı kimliğin iki belgede kullanılması
Bu hataların ortak özelliği, gözle bakıldığında fark edilmemeleridir. Fatura ekranda doğru görünür ama şema doğrulamasından geçmez. Bu yüzden üretilen her XML'in gönderilmeden önce XSD'ye karşı doğrulanması gerekir.
Şema doğrulamasını otomatikleştirmek
PDFXMLPro, PDF'ten ürettiği her XML dosyasını GİB şemasına karşı doğrular; doğrulamadan geçmeyen çıktı kullanıcıya verilmez. Böylece entegrasyon tarafında zaman kaybettiren red döngüleri baştan engellenir.
Elinizde hazır bir XML varsa ve yapısını incelemek istiyorsanız, ücretsiz XML görüntüleyicimizle dosyayı ağaç görünümünde açıp hangi blokların dolu, hangilerinin boş olduğunu görebilirsiniz.
Şema doğrulaması nasıl yapılır?
Doğrulama, XML dosyasının GİB tarafından yayımlanan XSD dosyalarına karşı sınanmasıdır. Bu işlem çoğu programlama dilinde standart kütüphanelerle yapılabilir; ayrıca hazır doğrulama araçları da mevcuttur.
Doğrulama iki katmanda düşünülmelidir. Birinci katman şema uyumudur: alanlar doğru yerde ve doğru formatta mı? İkinci katman iş kuralı uyumudur: tutarlar birbirini tutuyor mu, senaryo ile fatura tipi uyumlu mu? Şema ikinci katmanı yakalamaz; bunun için ek kontroller gerekir.
Özetle UBL-TR'de zorunluluk iki katmanlıdır: şemanın dayattığı yapısal zorunluluklar ve mevzuatın dayattığı iş kuralları. Bir belge şemadan geçebilir ama iş kuralı açısından hatalı olabilir. Sağlam bir entegrasyon her iki katmanı da kontrol eder.