Yapı malzemesi satış uygulamamın fatura kesebilmesi yetmiyordu; kesilen faturanın GİB'in beklediği UBL-TR XML'ine dönüşebilmesi gerekiyordu. Bu yazı o dönüşümü, doğrulamayı ve yol boyunca karşıma çıkan, çoğu Türkiye'ye özgü tuzakları anlatıyor.
Kapsamı baştan dürüstçe söyleyeyim. Uygulama şu an kapalı modda: e-Fatura XML'i üretiliyor, doğrulanıyor, veritabanında saklanıyor ve kullanıcı indirebiliyor. Gönderim yok, çünkü henüz bir özel entegratör seçmedim. Doğrudan GİB entegrasyonunu bilinçli olarak kapsam dışı bıraktım: mali mühür, BİS raporu, GİB test süreci ve 7/24 bağlantı taahhüdü, kullanıcının makinesinde çalışan bir masaüstü uygulamasına uymuyor. Üretilen XML imzasız; imzanın yerleşeceği UBLExtensions bloğu boş bırakılıyor ve imzalama entegratörün işi olacak.
XML için kütüphane kullanmadım
UBL üretmek için ihtiyacım olan tek şey iç içe elemanlar, öznitelikler ve doğru kaçış. Bunun için bir XML kütüphanesi eklemek yerine yaklaşık 60 satırlık küçük bir kurucu yazdım. Mali belge üreten bir yolda her yeni bağımlılık, gereksiz bir tedarik zinciri yüzeyi.
Kaçışta sıranın önemi var: & ilk sırada değiştirilmezse, daha önce üretilen < tekrar kaçırılıp &lt; olur. Firma ünvanlarında & ve tırnak gerçekten geçiyor ("Yılmaz & Oğulları", 12" boru), testler de tam bunları sınıyor:
export function escape(value: string): string {
return value
.replace(/&/g, '&') // ilk sırada olmalı
.replace(/</g, '<')
.replace(/>/g, '>')
.replace(/"/g, '"')
.replace(/'/g, ''')
}
Encoding tarafında sürpriz yok: belge UTF-8 bildirimiyle yazılıyor ve "Şişli Çğıöü" gibi Türkçe karakterlerin olduğu gibi kaldığını doğrulayan ayrı bir test var. İçeriği olmayan elemanlar kendi kendini kapatan etiket olarak yazılıyor; anlamsız boş etiketler entegratör tarafında sorun çıkarıyor.
Künye: profil, numara ve ETTN
Faturanın başı her zaman aynı iskeleti taşıyor. Projeden sadeleştirilmiş hâli:
<cbc:UBLVersionID>2.1</cbc:UBLVersionID>
<cbc:CustomizationID>TR1.2</cbc:CustomizationID>
<cbc:ProfileID>EARSIVFATURA</cbc:ProfileID>
<cbc:ID>FTR2026000000001</cbc:ID>
<cbc:CopyIndicator>false</cbc:CopyIndicator>
<cbc:UUID>3f2504e0-4f89-41d3-9a0c-0305e82c3301</cbc:UUID>
<cbc:IssueDate>2026-09-08</cbc:IssueDate>
<cbc:IssueTime>14:30:00</cbc:IssueTime>
<cbc:InvoiceTypeCode>SATIS</cbc:InvoiceTypeCode>
<cbc:DocumentCurrencyCode>TRY</cbc:DocumentCurrencyCode>
Belge numarası GİB biçiminde olmak zorunda: 3 karakter seri kodu, 4 hane yıl, 9 hane sıra; toplam 16 karakter, ayraç yok. Doğrulamada bunu tek bir düzenli ifade karşılıyor: /^[A-Z0-9]{3}\d{13}$/.
ETTN (cbc:UUID) yerelde randomUUID() ile üretiliyor ve bir kez verildikten sonra korunuyor. XML yeniden üretildiğinde aynı ETTN kullanılıyor; her üretimde yeni numara vermek, aynı faturanın GİB tarafında iki ayrı belge gibi görünmesine yol açardı. Gönderilmiş bir faturanın XML'i ise hiç yeniden üretilemiyor.
Vergi kimliği için schemeID VKN mi TCKN mi olduğunu söylüyor. 10 hane tüzel kişi (VKN), 11 hane gerçek kişi (TCKN). Gerçek kişide ayrıca cac:Person altında ad ve soyad ayrı yazılıyor. Cari kartında ünvan tek alan olduğu için son kelimeyi soyad kabul ediyorum; kusurlu ama yaygın bir varsayım, ad/soyad boşsa doğrulama zaten uyarı veriyor. Uzunluğu yanlış bir vergi numarası hata, sağlama (checksum) testinden geçmeyen numara ise uyarı.
e-Fatura mı, e-Arşiv mi
Senaryo seçimi kullanıcıya bırakılmıyor. Alıcı e-Fatura mükellefiyse fatura GİB üzerinden onun sistemine gidiyor (TEMELFATURA veya TICARIFATURA); değilse e-Arşiv (EARSIVFATURA) olarak doğrudan alıcıya ulaşıyor. Yanlış senaryo reddedilmek demek, bu yüzden bilgi cari kartındaki mükellefiyet alanından okunuyor:
export function determineScenario(eInvoiceTaxpayer: boolean, isCommercial = false) {
if (!eInvoiceTaxpayer) return 'EARSIV'
return isCommercial ? 'COMMERCIAL' : 'BASIC'
}
e-Arşiv tarafında iki fark var. XML'e gönderim şeklini (ELEKTRONIK / KAGIT) taşıyan bir cac:AdditionalDocumentReference ekleniyor; elektronik gönderimde alıcının e-postası yoksa doğrulama uyarıyor. e-Fatura alıcısının GİB posta kutusu etiketi varsa ikinci bir PartyIdentification olarak schemeID="GIB_ETIKET" ile yazılıyor.
İade faturası InvoiceTypeCode=IADE ile ve düzelttiği faturaya cac:BillingReference atfıyla üretiliyor. İadeyi TICARIFATURA ile göndermiyorum; ticari senaryo seçili alıcıda iade TEMELFATURA olarak çıkıyor. Bu kuralı GİB kılavuzundan değil yaygın uygulamadan aldım, kodda da mali müşavir ve entegratör teyidi beklediği not olarak duruyor.
Doğrulama: bilinçli olarak XSD değil
Burada kendime karşı da dürüst olmam gerekti. İlk planda "XML şemaya karşı doğrulanır" yazıyordu. Uyguladığım şey ise bir XSD doğrulaması değil. UBL 2.1 şema dosyaları megabaytlarca yer tutuyor, GİB'in TR1.2 kısıtlarının önemli kısmı da şemada değil kılavuzda. Schematron da çalıştırmıyorum.
Bunun yerine validateUbl, belgenin entegratöre gitmeden kesin olarak reddedileceği durumları yakalıyor: GİB biçiminde olmayan numara, geçersiz ETTN, hatalı VKN/TCKN, eksik zorunlu alan, yabancı parada eksik kur, aynı KDV oranının kırılımda iki kez geçmesi ve tutmayan aritmetik. Aritmetik kontrolleri satırda (brüt − iskonto = net, matrah × oran = KDV) ve belgede (kırılım matrahı = vergi hariç toplam, vergi hariç + KDV = ödenecek) yapılıyor. Yuvarlama farkı hata sayılmasın diye tolerans 0.011: bir kuruşluk fark geçiyor, iki kuruş hata. Bulgular hata/uyarı olarak ayrılıyor ve hata içeren belge saklanıyor ama ERROR durumunda kalıyor, gönderilemiyor. Mesajlar da düzeltmenin nereden yapılacağını söylüyor: satıcı vergi numarası boşsa firma ayarları, alıcınınki boşsa cari kartı.
Tutarların kendisi buraya kadar zaten doğru gelmiş olmalı. Para ve KDV hesapları tek bir paylaşılan çekirdekte yapılıyor; o konuyu Kuruşu kuruşuna yazısında anlattım. UBL tarafının işi o tutarları doğru alanlara koymak: tutarlar iki ondalık ve currencyID ile, miktar ve birim fiyat dört ondalıkla yazılıyor ki kuruş altı fiyatlar kaybolmasın.
Gerçekten yaşadığım hatalar
En öğretici kısım burası. Hiçbiri GİB'e ulaşmadı, çünkü uygulama kapalı moddaydı; ama entegratör bağlandığı gün hepsi ret olarak dönecekti.
Fatura numarası GİB biçiminde değildi. Seri deseni FT-{YYYY}-{SEQ:5} ile FT-2026-00001 üretiyordu. Numara yalnız uygulamanın içinde kullanıldığı sürece kimse fark etmedi; kuralı UBL üretimi dışarıdan getirdi. Varsayılan desen FTR{YYYY}{SEQ:9} (iade için IAD) oldu. Kesilmiş faturaların numarasına dokunmadım: mali bir belgenin numarası geriye dönük düzeltilmez. Eski biçimli faturalar e-Belge üretiminde ERROR kalıyor ve nedeni ekranda yazıyor.
Satır iskontosu iki kez düşülüyordu. Uçtan uca denetimde beş iskonto senaryosu denedim; ikisi, yalnız satır iskontosu olan ve satır + belge iskontosu olan faturalar, doğrulamadan kaldı:
HATA [kdvKirilimi] KDV kırılımı matrahı 9500.00, vergi hariç toplam 9000.00.
HATA [odenecekTutar] Ödenecek tutar 10900.00 olmalı, belgede 11400.00.
Satır toplamı zaten satır iskontolarını düşmüştü; üstüne belgenin toplam iskontosu (satır + belge) düşülünce satır iskontosu ikinci kez iniyordu. UBL'de AllowanceTotalAmount yalnız belge iskontosunu taşımalı. İnşaat malzemesinde satır iskontosu istisna değil kural; düzeltilmeseydi faturaların çoğu gönderilemezdi. Düzeltmeden sonra iskonto kombinasyonlarını nakliyeli ve nakliyesiz kapsayan bir matris testi ekledim. Testin gerçekten yakaladığını görmek için düzeltmeyi geçici olarak geri aldım: tam beklenen üç senaryo düştü.
LineExtensionAmount ile TaxableAmount aynı şey değil. Belge iskontosu satırlara oransal dağıtılıyor ve KDV o dağıtımdan sonraki tutar üzerinden hesaplanıyor. Bu yüzden satırda LineExtensionAmount satır iskontosu düşülmüş net, TaxSubtotal/TaxableAmount ise belge iskontosu payı da düşülmüş matrah. İkisini aynı sanmak, belge iskontolu faturada KDV'yi olduğundan yüksek gösterirdi.
Öğe sırası şemayı bozuyordu. UBL 2.1'de Invoice kök öğeleri bir xs:sequence. cac:PricingExchangeRate'i LineCountNumeric'in hemen arkasına yazıyordum; şemadaki yeri AllowanceCharge'tan sonra, TaxTotal'dan önce. Döviz cinsinden her fatura XSD doğrulamasından kalırdı. XSD çalıştırmadığım için bunu ancak kod okurken fark ettim. Şimdi bir test, kök öğelerin şemadaki sıranın bu kurucunun ürettiği kesitine uyduğunu dövizli, iskontolu, nakliyeli bir iade faturası üzerinde sınıyor. Ucuz ama işe yarayan bir XSD vekili.
Fatura yanlış adrese düzenlenebilirdi. Alıcının fatura adresini orderBy(asc(isDefault)) ile seçiyordum. Boolean sıralamasında asc false'u öne alır; yani varsayılan olmayan adres seçiliyordu. Tek adresli carilerde görünmüyor, ikinci adres eklendiği anda ortaya çıkıyor. Düzeltme tek kelime: desc.
Birim kodları
GİB, unitCode için UN/ECE Recommendation 20 listesini bekliyor; kullanıcı ise "ADET", "KG", "PALET", "KOLI" yazıyor. Bir eşleme tablosu bunları çeviriyor: ADET → C62, KG → KGM, M → MTR, M3 → MTQ, PALET → PF, KOLI → BX. Sektörel birimler sorunlu: "BOY" (12 metrelik demir çubuk) ve "SEFER" (nakliye seferi) listede yok. Bunları bilinçli olarak C62 ile eşledim; tutarı etkilemiyor, miktarın anlamı satır açıklamasında kalıyor. Eşlenemeyen her birim yine C62'ye düşüyor ama kullanıcıya uyarı olarak bildiriliyor.
Tuzaklar
| Tuzak | Belirti | Çözüm |
|---|---|---|
| Tireli belge numarası | FT-2026-00001 biçimi reddedilir |
3 + 4 + 9 = 16 karakter, ayraçsız seri deseni |
| Her üretimde yeni ETTN | Aynı fatura iki ayrı belge gibi görünür | ETTN'yi ilk üretimde verip saklamak |
| Satır iskontosunu belge iskontosuna katmak | Kırılım matrahı ve ödenecek tutar tutmaz | AllowanceTotalAmount = yalnız belge iskontosu |
| Net tutarı matrah sanmak | Belge iskontolu faturada KDV fazla görünür | Satırda netAmount ve matrah ayrı alanlar |
| Kök öğe sırası | Dövizli fatura XSD'den kalır | Şema sırasını sınayan test |
asc ile varsayılan seçmek |
İkinci adreste fatura yanlış adrese gider | desc(isDefault) |
| Kaçış sırası | &lt; gibi bozuk metin |
& ilk sırada |
| Sektörel birimler | UN/ECE'de karşılığı yok | C62 + kullanıcıya uyarı |
Henüz yapmadıklarım
Bu taslağı hazırlarken kodu yeniden okudum ve açık kalanları da yazmak istiyorum:
- İmza ve gönderim yok. XAdES imzası, mali mühür ve gönderim entegratör adaptörüyle gelecek. Arayüz hazır; gönderim kuyruğu geçici hatalarda 1, 5, 15, 60, 240 ve 720 dakika arayla yeniden deniyor.
- Gerçek XSD doğrulaması yok. Şema paketi depoda değil. Entegratör bağlanınca ilk dövizli faturayı ayrıca denemem gerekiyor.
- Tevkifat ve istisna yok.
TEVKIFAT,ISTISNAveOZELMATRAHtip listesinde tanımlı ama bunlara özgü XML üretilmiyor. %0 KDV'li satırda istisna gerekçesi de yazılmıyor. Şimdilik yalnızSATISveIADEgerçekten destekleniyor. IssueTimeUTC yazılıyor. Saat, kaydın oluşturulma zamanındantoISOString()ile alınıyor; Türkiye saatine çevrilmiyor.- Türkçe büyük harf. Birim eşlemesi
toLocaleUpperCase('tr-TR')kullanıyor; küçük harfle girilmiş "koli" bu yüzden "KOLİ" oluyor, tabloda bulunmuyor ve uyarıylaC62'ye düşüyor. Varsayılan birim kodları büyük harfle tanımlı olduğu için şu an pratikte görünmüyor, ama düzeltilmesi gereken bir tuzak.
e-Faturada asıl iş XML yazmak değil; GİB'den önce reddedilecek her şeyi kullanıcı hâlâ ekrandayken yakalamak.