GİB UBL-TR Güncellemesi: ERP Ekipleri İçin e-Fatura Entegrasyonu Rehberi

e-Fatura entegrasyonu ve 14 Eylül 2026 UBL-TR güncellemesi

Gelir İdaresi Başkanlığı (GİB), 27 Temmuz 2026'da e-Fatura paketini, e-Arşiv Fatura paketini ve UBL-TR Kod Listeleri Kılavuzu'nu güncelledi; değişiklikler 14 Eylül 2026 itibarıyla devreye alındı. ERP'sinden fatura kesen her şirket için bu, e-Fatura entegrasyonu katmanında yeni istisna kodları, yeni plaka ve dorse kuralları, şarj hizmeti faturaları için zorunlu alanlar ve e-Gider Pusulası için yeni bir etiket demek. Bu alanlarda eksik veya eski formatlı veri gönderen sistemler, faturalarını artık şematron kontrolünden geçiremiyor.

Bu yazıda neyin değiştiğini, ERP tarafında hangi alanların ve eşlemelerin etkilendiğini, özel entegratörün test ortamında nasıl bir test planı yürütülmesi gerektiğini ve kuyruk, yeniden deneme ve idempotency ile dayanıklı bir ara katmanın nasıl kurulacağını anlatıyoruz. Sonda ERP ve finans ekiplerinin doğrudan kullanabileceği bir kontrol listesi var.

Kısaca

• GİB'in 27.07.2026 tarihli paketleri 14.09.2026'da yürürlüğe girdi; 24.08.2026'da e-Fatura paketindeki eksiklikler ayrıca giderildi.
• Etkilenen başlıca alanlar: istisna kodu listeleri (233 eklendi, 308 ve 339 yatırım teşvik listesine taşındı), plaka/dorse tipleri, SARJ ve SARJANLIK faturaları, erreceipt etiketi.
• Doğrulamayı entegratöre bırakmayın: güncel XSD ve şematron dosyalarını kendi CI hattınızda koşturun.
• Ara katmanda kuyruk, sınıflandırılmış yeniden deneme ve ETTN tabanlı idempotency, mükerrer fatura ve kayıp belge riskini azaltır.
• Reddedilen faturalar hata koduna göre izlenmeli; geri dönüş planı "eski formata dönmek" değil, etkilenen belgeleri bekletmek olmalı.

GİB ne yayımladı ve güncelleme ne zaman yürürlüğe girdi?

GİB'in e-Belge portalındaki duyurulara göre takvim şöyle ilerledi: 27 Temmuz 2026'da e-Fatura Paketi, e-Arşiv Fatura Paketi ve UBL-TR (Kod Listeleri) Kılavuzu güncellendi ve güncellemelerin 14.09.2026 itibarıyla devreye alınacağı duyuruldu. 11 Ağustos'ta e-Arşiv paketindeki earsiv.xsd eksiklikleri giderildi. 24 Ağustos'ta ise 27 Temmuz'da yayımlanan e-Fatura paketindeki eksikliklerin giderildiği açıklandı.

Bu son düzeltme önemli bir ders içeriyor: Paket, yayımlandıktan sonra da değişebiliyor. Temmuz sonunda paketi indirip test ortamına kuran bir ekip, ağustos sonundaki düzeltmeyi kaçırırsa canlıya farklı kurallarla çıkabilir. Bu yüzden paket dosyalarını tarih ve sürümle saklamak, her yeni duyuruda farkları incelemek gerekiyor.

Hangi dosyalar değişti?

Değişikliklerin teknik karşılığı, GİB'in UBL-TR 1.2.1 paketindeki kod listesi ve şematron dosyalarıdır. NES'in 24 Ağustos analizine göre düzeltme UBL-TR_Codelist.xml, UBL-TR_Common_Schematron.xml ve UBL-TR_Main_Schematron.xml dosyalarını kapsıyor. Kod listeleri kılavuzu ise V 1.43 sürümüne yükseldi. e-Arşiv tarafında earsiv.xsd güncellendi.

Özel entegrasyon kılavuzunda ne değişti?

Ayrı bir başlık olarak GİB, 29 Haziran 2026'da e-Fatura Uygulaması Özel Entegrasyon Kılavuzu'nu v1.14 sürümüne güncelledi. Değişiklik kaydına göre özel entegrasyon başvurusu yapacak mükellefler için TÜRKAK onaylı ISO belgeleri zorunlu hale geldi. Kılavuz; bilgi güvenliği için TS ISO IEC 27001 veya ISO 27001, iş sürekliliği için ISO 22301 ve BT hizmet yönetimi için TS ISO IEC 20000 veya ISO 20000 belgelerini sayıyor. Faturalarını bir özel entegratör üzerinden gönderen şirketlerin bu belgeleri entegratörlerinden teyit etmesi yeterli.

ERP tarafında hangi alanlar ve eşlemeler etkileniyor?

Güncellemenin büyük kısmı XML'i üreten koda değil, ERP'deki ana veriye ve eşleme tablolarına dokunuyor. ERP'de "istisna kodu", "plaka", "fatura tipi" gibi alanların nasıl tutulduğu ve UBL-TR alanlarına nasıl eşlendiği, faturanın kabul edilip edilmeyeceğini belirliyor.

İstisna kodları ve fatura tipleri

Kod listesine 233 numaralı istisna kodu eklendi: "2942 Sayılı Kamulaştırma Kanunu Kapsamında Taşınmazların Kamulaştırmayı Yapan Devlet ve Kamu Tüzel Kişilerine Devri". 308 ve 339 kodları genel listeden çıkarılıp yeni yatırım teşvik istisna listesine (YatirimTesvikTaxExemptionReasonCodeType) taşındı. Şematron kuralına göre istisna listesindeki kodlar yalnızca ISTISNA, IADE, IHRACKAYITLI, SGK, YTBISTISNA ve YTBIADE fatura tipleriyle kullanılabiliyor. Ayrıca IADE tipindeki faturaların düzenlenebileceği senaryolara KAMU eklendi.

Plaka ve dorse alanları

Plaka tipleri listesine DORSEPLAKA'nın yanında YABANCIDORSE, YABANCIPLAKA ve YABANCIDORSEPLAKA eklendi. 24 Ağustos düzeltmesiyle LicensePlateID alanındaki schemeID değerleri PLAKA ve YABANCIPLAKA ile sınırlandı; dorse tipleri TransportEquipment/ID kontrolüne taşındı. Yabancı plakalarda yalnızca büyük harf, rakam, alt çizgi ve tire kabul ediliyor. e-İrsaliye'de şoför (DriverPerson) bilgisi varsa plaka bilgisi de zorunlu. ERP'nizde "plaka" tek bir serbest metin alanıysa, araç ve dorse ayrımını ve yerli/yabancı bilgisini ayrı alanlara taşımanız gerekebilir.

Şarj hizmeti faturaları (SARJ ve SARJANLIK)

SARJ ve SARJANLIK tipindeki enerji faturalarında alıcı tarafında schemeID="PLAKA" olan bir tanımlayıcı zorunlu hale geldi. Fatura dönemi (InvoicePeriod) başlangıç ve bitiş tarihi ile saatiyle eksiksiz gönderilmeli. SARJ tipinde ayrıca GUID formatında bir ESURaporID ve rapor tarihi, SARJANLIK tipinde ise bir seri numarası bekleniyor. Şarj istasyonu işleten veya bu hizmeti faturalayan şirketlerde bu alanlar çoğu zaman ERP'de hiç yoktur; operasyon sisteminden taşınmaları gerekir.

e-Gider Pusulası ve erreceipt etiketi

GİB, e-belge XML'inde kullanımı yasak olan ayrılmış etiketlere (ReservedAliases) ve kullanıcı zarf etiketlerine e-Gider Pusulası'nı temsil eden erreceipt etiketini ekledi. erreceipt kullanıcı hesaplarında UserOptionCode alanı zorunlu ve 171, 172, 173 veya 174 değerlerinden biri olmalı. GİB, 15 Eylül 2026'da e-Gider Pusulası paketini de güncelledi.

e-Arşiv tarafı

Vergi Teknolojileri'nin özetine göre e-Arşiv XSD'sinde birden fazla ESU rapor kimliği gönderilebiliyor. Alıcı bilgisi ise ya tüzel kişi (VKN ve unvan) ya da gerçek kişi (TCKN, ad ve soyad) olarak verilmeli; ikisi birlikte gönderilemiyor. Teknoloji destek faturalarında (TEKNOLOJIDESTEK) senaryo alanı EARSIVFATURA olmalı.

Değişiklik	Etkilenen alan / süreç	Yapılacak iş
233 istisna kodu eklendi	İstisna kodu ana verisi, satış faturası şablonları	Kodu eşleme tablosuna ekleyin; yalnız izinli fatura tipleriyle seçilebilir yapın
308 ve 339 yatırım teşvik listesine taşındı	Teşvikli satış faturaları, YTBISTISNA/YTBIADE akışı	Kodları doğru listeden okuyun; eski eşlemeyi kapatın
İstisna kodu ↔ fatura tipi kuralı	Fatura tipi seçimi, ERP doğrulama kuralları	ERP'de kayıt anında aynı kuralı uygulayın, hatayı kullanıcıya gösterin
Yabancı plaka/dorse tipleri, dorse için TransportEquipment	Araç ana verisi, sevkiyat, e-İrsaliye	Araç ve dorse alanlarını ayırın; yabancı plaka formatını doğrulayın
e-İrsaliye'de şoför varsa plaka zorunlu	Sevk irsaliyesi ekranı, lojistik entegrasyonu	Şoför girilen kayıtta plakayı zorunlu alan yapın
SARJ / SARJANLIK zorunlu alanları	Enerji faturası, şarj platformu verisi	Plaka, dönem saatleri, ESURaporID ve seri numarasını kaynaktan taşıyın
erreceipt etiketi ve UserOptionCode	Zarf üretimi, kullanıcı listesi işleme	Etiket kontrolünü ve 171–174 değer kontrolünü ekleyin
e-Arşiv alıcı kuralı	Cari kart, perakende satış	VKN/TCKN alanlarının aynı anda dolu gitmesini engelleyin

Özel entegratörün test ortamında nasıl bir test planı yürütülmeli?

Test planının amacı, canlıda red alacak her senaryoyu test ortamında önceden görmek. Bunun için gerçek ERP verisinden türetilmiş bir senaryo matrisi ve bilerek hatalı hazırlanmış negatif test belgeleri gerekir. Test belgeleri, kullandığınız özel entegratörün test ortamında uçtan uca, yani imza, zarf ve yanıt dahil koşturulmalı.

Senaryo matrisi

Matrisin satırları fatura tipleri ve senaryolar (TEMELFATURA, TICARIFATURA, KAMU, EARSIVFATURA vb.), sütunları ise güncellemeden etkilenen alanlardır. Her hücre için en az bir geçerli örnek belge üretin. Son altı ayın faturalarından her tip ve istisna kombinasyonu için bir örnek seçmek, unutulan kenar durumları yakalamanın en hızlı yoludur.

Negatif testler

Negatif testlerde belgenin reddedilmesi beklenir. Örneğin 233 kodunu izin verilmeyen bir fatura tipiyle göndermek, yabancı plakaya küçük harf veya boşluk koymak, şoförü olan bir irsaliyede plakayı boş bırakmak. Bu belgeler hem şematronun güncel olduğunu kanıtlar hem de red kodlarının ERP'ye doğru yansıdığını test eder.

Şematron ve XSD doğrulaması neden kendi CI hattınızda koşmalı?

XSD, belgenin yapısını (hangi eleman nerede, hangi tipte) denetler. Şematron ise iş kurallarını, örneğin "bu istisna kodu yalnız şu fatura tipleriyle kullanılabilir" gibi koşulları denetler. GİB'in paketindeki şematron dosyaları, entegratörün ve GİB'in uyguladığı kuralların kaynağıdır.

Bu kontrolleri yalnızca entegratöre bırakmak, hatayı en geç ve en pahalı noktada görmek demektir. Bunun yerine GİB paketindeki XSD ve şematron dosyalarını sürüm kontrolüne alın ve her eşleme değişikliğinde örnek belgelerinizi bu dosyalara karşı otomatik doğrulayın. 24 Ağustos'taki gibi bir paket düzeltmesi geldiğinde dosyayı güncelleyip testleri yeniden koşturmak dakikalar sürer.

Ön doğrulama ara katmanda da çalışmalı

Aynı doğrulama canlıda, belge entegratöre gitmeden önce ara katmanda da çalıştırılabilir. Böylece hatalı belge kuyrukta "iş hatası" olarak işaretlenir, entegratöre hiç gitmez ve kullanıcı hatayı ERP ekranında görür. Bu, red sayısını ve entegratörle yaşanan gidiş gelişi azaltır.

Ara katman: kuyruk, yeniden deneme ve idempotency

Pek çok şirkette e-Fatura entegrasyonu, ERP'nin doğrudan entegratör API'sini çağırmasından ibarettir. Bu model, entegratör yavaşladığında veya bir ağ hatası olduğunda fatura kaybına ya da mükerrer gönderime açıktır. Bir kurumsal entegrasyon ara katmanı bu riskleri merkezi olarak yönetir.

Kuyruk ve outbox

ERP, faturayı kaydettiği aynı veritabanı işleminde bir outbox tablosuna da "gönderilecek" kaydı yazar. Ara katman bu tabloyu okuyup kuyruğa alır. Böylece fatura kaydedildiyse gönderim görevi de kesinlikle oluşmuştur. Ayrıntılar için outbox pattern, idempotency ve retry yazımıza bakabilirsiniz.

Sınıflandırılmış yeniden deneme

Her hata yeniden denenmemeli. Zaman aşımı veya geçici servis hatası gibi teknik hatalar artan bekleme süreleriyle yeniden denenir. Şematron reddi gibi iş hataları ise yeniden denenmez; belge düzeltilmek üzere ERP'ye geri döner. Bu ayrım yapılmazsa hatalı belge kuyrukta defalarca dolaşır.

ETTN ile idempotency

Her faturanın evrensel tekil numarası (ETTN, UUID) ERP'de belge oluşturulurken bir kez üretilmeli ve yeniden denemelerde aynı kalmalıdır. Ara katman bu numarayı idempotency anahtarı olarak kullanır: aynı ETTN ile ikinci kez gönderim isteği gelirse önceki sonucu döndürür. Entegratör API'si değiştiğinde ise sözleşme testleri işe yarar; API sözleşmesi ve geriye dönük uyumluluk yazımızda bu yaklaşımı anlattık.

• • •

Geri dönüş (rollback) planı nasıl kurulur?

14 Eylül'den sonra GİB eski kurallarla belge kabul etmediği için geri dönüş, "eski formata dönmek" anlamına gelmez. Doğru geri dönüş planı, yeni eşleme kodunda bir hata çıktığında etkilenen belge türünü durdurup bekletmek, diğer belgelerin akmaya devam etmesini sağlamaktır.

• Yeni eşlemeleri özellik bayrağı arkasında açın; önce pilot bir seri veya şubede devreye alın.
• Eşleme tablolarını sürümleyin; hatalı sürümden bir önceki doğru sürüme tek adımda dönebilin.
• Belge türü bazında "beklet" anahtarı tanımlayın; bekleyen belgeler kuyrukta kaybolmadan kalsın.
• Düzeltme sonrası bekleyen belgeleri aynı ETTN ile, kontrollü hızda yeniden gönderin.
• Her geri dönüş kararını kimin, ne zaman ve neden verdiğiyle kayda geçirin.

Reddedilen faturalar nasıl izlenir?

Özel entegratör modelinde her belge için sistem yanıtı ve ticari faturalarda alıcının uygulama yanıtı gelir. Bu yanıtlar ERP kaydına geri yazılmazsa finans ekibi reddedilen faturayı ancak müşteri aradığında öğrenir. İzleme panelinde en az şu göstergeler olmalı: belge türüne göre red oranı, hata koduna göre dağılım, kuyrukta bekleyen belge sayısı ve en eski bekleyen belgenin yaşı.

Eşik değerler aşıldığında hem entegrasyon ekibine hem muhasebeye alarm gitmeli. 14 Eylül gibi bir geçiş gününden sonraki ilk iki hafta, red oranını günlük takip etmek ve en sık görülen hata kodlarını hızla eşleme düzeltmesine çevirmek için en kritik dönemdir.

e-Fatura ve e-Arşiv Fatura uygulamalarının temellerini tazelemek isteyen ekipler için GİB'in kısa tanıtım videosu iyi bir başlangıç:

ERP ekipleri için kontrol listesi

Aşağıdaki liste, e-Fatura entegrasyonu sahibi ekiplerin bir sonraki GİB paketi geldiğinde de tekrar kullanabileceği şekilde hazırlandı:

• GİB e-Belge duyurularını haftalık takip eden bir sorumlu atandı.
• Güncel UBL-TR paketi, kod listeleri ve şematron dosyaları tarih ve sürümle depoda saklanıyor.
• İstisna kodu, fatura tipi, plaka ve dorse eşleme tabloları V1.43'e göre gözden geçirildi.
• ERP ekranlarında istisna kodu ↔ fatura tipi kuralı kayıt anında uygulanıyor.
• Araç, dorse ve yabancı plaka bilgileri ayrı alanlarda tutuluyor ve formatı doğrulanıyor.
• SARJ/SARJANLIK ve e-Gider Pusulası kullanılıyorsa zorunlu alanların kaynağı belirlendi.
• Senaryo matrisi ve negatif testler entegratörün test ortamında uçtan uca koşturuldu.
• XSD ve şematron doğrulaması CI hattında ve ara katmanda çalışıyor.
• Outbox, sınıflandırılmış yeniden deneme ve ETTN tabanlı idempotency devrede.
• Özellik bayrağı, eşleme sürümleri ve belge türü bazında "beklet" anahtarı hazır.
• Red oranı ve hata kodu dağılımı panelde; eşik alarmları muhasebeye de gidiyor.
• Özel entegratörün güncel ISO belgeleri ve paket güncelleme takvimi teyit edildi.

Plaka ve dorse: artık ayrı alanlarda ve ayrı kontrollerle.

Sevkiyat: e-İrsaliye'de şoför varsa plaka zorunlu.

e-Gider Pusulası: erreceipt etiketi zarf kontrollerine girdi.

Aksiyon Soft nasıl yardımcı olur?

Aksiyon Soft olarak e-Fatura ve e-Arşiv akışlarını ERP'den bağımsız bir ara katmanda ele alıyoruz. Süreç bir keşif çalışmasıyla başlar: mevcut eşlemeleri, son aylardaki red kodlarını ve entegratör bağlantısını inceleyip etkilenen alanların listesini çıkarırız. Ardından kuyruk, doğrulama ve izleme içeren bir MVP kurar, iki haftalık sprint demolarıyla ilerler, canlı geçiş sonrasında hypercare ve SLA'lı destek veririz.

Bu işleri API ve entegrasyon ile kurumsal yazılım çözümleri hizmetlerimiz kapsamında yürütüyoruz; altyapı tarafında API ve veri entegrasyon platformu çözümümüzü kullanıyoruz. Mevcut akışınızın hızlı bir kontrolünü istiyorsanız e-Fatura UBL-TR entegrasyon kontrol hizmetimizi inceleyebilirsiniz. Merkezimiz Samsun'da; Türkiye genelinde uzaktan çalışıyor, gerektiğinde planlı yerinde ziyaretler yapıyoruz.

Sık sorulan sorular

14 Eylül 2026 güncellemesi tüm e-Fatura kullanıcılarını etkiliyor mu?

Kurallar GİB'in şematron ve kod listelerinde olduğu için tüm belgeler bu kurallara göre denetleniyor. Ancak pratik etki, kullandığınız fatura tiplerine bağlı: istisnalı satış, araç ve sevkiyat, şarj hizmeti veya e-Gider Pusulası kullanmıyorsanız değişiklik sınırlı kalabilir.

Özel entegratörümüz güncellemeyi yaptıysa bizim bir şey yapmamız gerekir mi?

Entegratör, kendi doğrulama ve iletim katmanını günceller. ERP'nizin doğru istisna kodunu, plaka tipini veya zorunlu alanı göndermesi ise sizin sorumluluğunuzdadır. Eşlemeler güncellenmezse belgeler entegratörde veya GİB'de reddedilir.

Şematron hatası alan bir faturayı yeniden göndermek yeterli mi?

Hayır. Şematron reddi bir iş hatasıdır; aynı belgeyi yeniden göndermek aynı sonucu verir. Önce ERP'deki veri veya eşleme düzeltilmeli, sonra belge yeniden oluşturulup gönderilmelidir.

Test ortamında hangi belgeleri denemeliyiz?

Son aylarda kestiğiniz her fatura tipi ve istisna kombinasyonundan en az bir örnek, yabancı plaka ve dorse içeren sevkiyatlar, varsa SARJ/SARJANLIK faturaları ve bilinçli olarak hatalı hazırlanmış negatif test belgeleri.

ETTN'yi kim üretmeli?

ETTN belge oluşturulurken bir kez üretilmeli ve yeniden denemelerde değişmemelidir. ERP'de veya ara katmanda üretilebilir; önemli olan aynı faturanın her denemede aynı ETTN ile gitmesidir.

Bir sonraki GİB paketine nasıl hazırlıklı oluruz?

Duyuruları takip eden bir sorumlu, sürümlenmiş paket dosyaları, CI'da otomatik doğrulama ve güncel bir senaryo matrisi. Bu dördü varsa yeni bir paket birkaç günlük bir eşleme işine dönüşür.

Kaynaklar

• Gelir İdaresi Başkanlığı e-Belge — Duyurular (27.07.2026, 11.08.2026, 24.08.2026, 15.09.2026)
• Gelir İdaresi Başkanlığı e-Belge — e-Fatura mevzuat, UBL-TR1.2.1 paketi ve kılavuzlar
• Gelir İdaresi Başkanlığı — e-Fatura Uygulaması Özel Entegrasyon Kılavuzu v1.14 (29.06.2026)
• NES — GİB e-Fatura, e-Arşiv ve UBL-TR paketlerini güncelledi (27.07.2026)
• NES — GİB e-Fatura paketinde plaka ve dorse kontrolleri düzeltildi (24.08.2026)
• Vergi Teknolojileri — GİB e-Fatura ve e-Arşiv Fatura kılavuzları güncellendi: 14 Eylül'de devreye girecek değişiklikler (2026)
• Müşavirler Kulübü — GİB e-Fatura ve e-Arşiv kılavuz güncellemeleri 14 Eylül 2026'da yürürlükte (14.09.2026)

Projenizi konuşalım

ERP'nizin UBL-TR güncellemesine uyumunu kontrol etmek, red oranını düşürmek veya e-Fatura entegrasyonunuzu dayanıklı bir ara katmana taşımak istiyorsanız bizimle iletişime geçin. İlk görüşmede mevcut akışınızı ve son red kodlarınızı birlikte inceleyip somut bir yol haritası çıkaralım.