e-Fatura XML okuma: UBL-TR faturayı OCR'sız ERP'ye aktarmak

e-Fatura XML okuma, Gelir İdaresi Başkanlığının (GİB) UBL-TR standardındaki fatura dosyasından satıcı, tarih, tutar, vergi ve kalem bilgilerini doğrudan okuyup muhasebe ya da ERP sistemine aktarmaktır. e-Fatura zaten makinenin okuyabileceği yapılandırılmış bir dosya olduğu için optik karakter tanımaya (OCR) gerek yoktur. Asıl iş okumak değil; mükerrer faturayı yakalamak, cariyi ve kalemleri doğru eşlemek, tutarları doğrulamaktır.

Öne çıkanlar

• GİB'e göre e-Faturanın geçerli hâli, GİB üzerinden başarıyla geçmiş XML dosyasıdır. Kâğıt çıktısı ya da e-postayla gönderilen kopyası bunun yerine geçmez.
• UBL-TR, UBL 2.1 standardının Türkiye özelleştirmesidir. Faturada özelleştirme numarası "TR1.2" olarak yazılır.
• Fatura numarası 16 karakterdir: üç haneli birim kodu, dört haneli yıl ve dokuz haneli sıra numarası. Evrensel Tekil Tanımlama Numarası (ETTN) ise her faturaya özgü, GUID biçiminde bir kimliktir.
• Faturanın görüntüsü ile XML alanları arasında fark olursa XML'deki bilgi esas alınır. Veriyi görüntüden değil, XML'den okuyun.
• GİB kod listeleri değişir: UBL-TR Kod Listeleri'nin 1.43 sürümü 27 Temmuz 2026'da yayımlandı.

e-Fatura XML dosyasında ne var?

Bir e-Fatura XML dosyası, faturanın bütün bilgilerini etiketlenmiş alanlarda taşır: kim kesti, kime kesildi, ne zaman, hangi kalemler, hangi vergiler ve toplam ne. Bu alanların adı ve yeri GİB'in UBL-TR kılavuzlarında tanımlıdır.

Gelen faturanın otomatik okunması, departman departman süreç otomasyonu örneklerini derlediğimiz rehberde finans ekipleri için saydığımız ilk senaryodur. Aşağıdaki bölümler o senaryonun ayrıntısıdır.

Evrensel İş Dili (Universal Business Language, UBL), fatura ve irsaliye gibi ticari belgeler için uluslararası bir XML standardıdır. GİB'in UBL-TR Fatura Kılavuzu, UBL-TR'yi "UBL 2.1 Türkiye Özelleştirmesi" olarak tanımlar. Faturada UBL sürümü "2.1", özelleştirme numarası "TR1.2" yazılır (UBL-TR 1.2.1 Kılavuzları (yeni sekmede açılır), UBL-TR Fatura v1.0, Aralık 2017).

Dosyada fatura verisinin yanında iki şey daha bulunur:

• Mali mühür ya da e-imza. Faturanın imzalandıktan sonra değişmediğini kanıtlar. Dosyada tek bir karakter değişirse imza bozulur.
• Görüntüleme şablonu (XSLT). Faturanın insan için okunur görüntüsünü üreten dosyadır. Faturada yoksa GİB'in varsayılan şablonu kullanılabilir.

Faturanın türü iki alanla belirlenir. Senaryo alanı (ProfileID) süreci gösterir: TEMELFATURA, TICARIFATURA, EARSIVFATURA, IHRACAT, KAMU gibi. Fatura tipi alanı (InvoiceTypeCode) belgenin amacını gösterir: SATIS, IADE, TEVKIFAT, ISTISNA, OZELMATRAH, IHRACKAYITLI gibi. Güncel değer kümesi Kod Listeleri'ndedir ve yeni senaryolar eklendikçe büyür.

Bir uyarı: entegratörden ya da portaldan gelen dosya bazen faturanın kendisi değil, onu taşıyan zarftır. GİB'in Görüntüleyici Kılavuzu'na göre zarf XML'i "StandardBusinessDocument" etiketiyle, fatura XML'i ise "Invoice" etiketiyle başlar. Fatura zarftan bir yazılımla çıkarılmalıdır; elle yapılan düzenlemede tek karakter değişse imza bozulur (e-Fatura Görüntüleyici Kullanım Kılavuzu (yeni sekmede açılır), Eylül 2015).

ERP'ye aktarılacak alanlar

ERP'ye aktarımda okunacak alanlar sınırlıdır ve her birinin ERP'de belli bir karşılığı vardır. Aşağıdaki tablo, aktarımda kullanılan başlıca alanları UBL-TR'deki yerleriyle gösteriyor.

Alan tanımları GİB'in UBL-TR Fatura Kılavuzu'ndan, birim ve vergi kodları UBL-TR Kod Listeleri v1.43'ten alınmıştır (UBL-TR 1.2.1 Kılavuzları (yeni sekmede açılır), 27 Temmuz 2026).

Fatura numarasının yapısı da kılavuzda tanımlıdır: üç haneli alfanumerik birim kodu ile 13 haneli sıra numarasının birleşimidir. Sıra numarasının ilk dört hanesi yılı, kalan dokuz hanesi sırayı gösterir. Aynı fatura numarası, faturayı düzenleyen bünyesinde birden fazla kullanılamaz.

Adım adım: XML'den ERP kaydına

Aşağıdaki on adım, gelen bir e-Faturanın dosyadan ERP kaydına giden yolunu gösteriyor. İlk dördü teknik hazırlık, sonraki altısı iş kurallarıdır.

1. Faturayı alın. Gelen faturalar çalıştığınız özel entegratörün servisinden ya da GİB'in e-Fatura Portalı'ndan alınır; portal kılavuzuna göre gelen faturalar bilgisayara indirilebilir (e-Fatura Portalı Kullanım Kılavuzu (yeni sekmede açılır), Kasım 2013). Elle indirme yerine entegratörün servisinden düzenli çekmek, kaçan fatura riskini azaltır.
2. Zarftan çıkarın. Dosya zarfsa içindeki faturayı yazılımla ayırın. Sıkıştırılmış dosyayı açın; işlenecek dosya ".xml" olmalıdır.
3. Bütünlüğü kontrol edin. Mali mührün doğrulandığından emin olun. GİB'in E-Fatura Görüntüleyici programındaki "Doğrula" düğmesi bunu tek fatura için yapar; "Sorgula" düğmesi de faturanın GİB'den başarıyla geçip geçmediğini ve ticari faturaysa alıcının reddedip reddetmediğini sorgular.
4. Ad alanlarını tanıyan bir ayrıştırıcıyla okuyun. XML'i düz metin gibi aramayın. cac: ve cbc: önekleri dosyadan dosyaya farklı yazılabilir; ayrıştırıcı önekleri değil, ad alanı adreslerini (namespace) esas almalıdır.
5. Mükerrer kontrolü yapın. Aynı fatura entegratörden ikinci kez ya da ayrıca e-postayla gelebilir. ETTN, satıcı VKN/TCKN ve fatura numarasıyla daha önce kayıt açılıp açılmadığına bakın.
6. Cariyi eşleyin. Satıcının VKN ya da TCKN'si ile cari kartı bulun. İlk kez gelen bir satıcı için otomatik cari açmak yerine kaydı bir kişiye gösterin.
7. Kalemleri eşleyin. Satıcının ürün kodunu ve adını kendi stok kodunuza ya da gider hesabınıza bir eşleme tablosuyla bağlayın. Birim kodlarını kendi birimlerinize çevirin.
8. Tutarları ve vergileri doğrulayın. Satır tutarlarının toplamı, vergi toplamları ve ödenecek tutar birbiriyle tutmalıdır. Yuvarlama farkı cbc:PayableRoundingAmount alanında ayrıca yazılabilir.
9. Sipariş ve irsaliyeyle karşılaştırın. Faturadaki miktar ve fiyatı siparişle, teslim alınan miktarı irsaliyeyle eşleştirin (üçlü eşleştirme).
10. Kaydedin, istisnaları ayırın, aslını saklayın. Kuralları geçen fatura ERP'ye taslak ya da kesin kayıt olarak yazılır. Takılanlar bir istisna ekranına düşer. Orijinal XML değiştirilmeden saklanır.

Siparişten faturaya uzanan zincirin tamamını teklif, sipariş ve fatura akışını anlattığımız yazıda ele alıyoruz.

Kalem eşleme neden en zor adım?

Çünkü satıcı ürünü kendi koduyla ve kendi adıyla yazar; sizin stok kodunuzu bilmez. Aynı ürün iki satıcıda iki farklı adla, aynı satıcıda bile zamanla farklı açıklamalarla gelebilir.

Pratik çözüm bir eşleme tablosudur. Tablonun anahtarı "satıcı VKN + satıcının ürün kodu", değeri sizin stok kodunuz ve birim çevrim katsayınızdır. İlk faturalarda eşleme bir kişi tarafından yapılır ve tabloya yazılır. Sonraki faturalarda aynı kalem otomatik eşleşir.

Birimler ayrı bir dikkat ister. UBL-TR, birim kodlarını öncelikle GİB'in listesinden, listede yoksa UN/ECE birim kodlarından alır. Satıcı koli ile fatura ederken siz adet ile stok tutuyorsanız, çevrim katsayısı eşleme tablosunda durmalıdır.

Gider faturalarında stok kartı yerine gider hesabı eşlenir. Burada satıcı ve kalem açıklamasına göre bir öneri üretilebilir; ama ilk aşamada kesin kayıt yerine onaya düşmesi daha güvenlidir.

Mükerrer, iade ve reddedilen faturalar

Mükerrer, iade ve reddedilmiş faturalar, otomatik okumada özel kural gerektiren üç durumdur. Üçü de XML'deki alanlarla ayırt edilebilir.

Mükerrer fatura. GİB'in portal kılavuzu, aynı UUID ve fatura numarasına sahip faturaların portala tekrar yüklenemeyeceğini belirtir. GİB'in saklama kılavuzu da arşivde aramanın anahtarlarından birinin VKN ya da TCKN ile birlikte kullanılan fatura numarası olmasını ister (Saklama Kılavuzu (yeni sekmede açılır), Eylül 2013). Kendi kontrolünüzü aynı anahtarlarla kurun.

İade faturası. Fatura tipi IADE olan belge, malın iadesi için alıcı tarafından düzenlenir. Satıcı tarafında bu belge genellikle alış değil, satış iadesi olarak işlenir; kayıt şeklini mali müşavirinizle netleştirin. Ticari fatura senaryosunda iade faturası, asıl satış faturasına cac:BillingReference alanıyla bağlanabilir.

Reddedilen ticari fatura. TICARIFATURA senaryosunda alıcı faturayı uygulama yanıtıyla kabul ya da reddedebilir. GİB'in Görüntüleyici Kılavuzu'na göre alıcının sistem üzerinden reddettiği fatura geçersizdir. ERP kaydı, faturanın kabul ya da red durumunu da izlemelidir.

Görüntüleme ve Excel'e aktarma

e-Fatura XML'ini görüntülemek için GİB'in E-Fatura Görüntüleyici programı kullanılabilir. Program faturanın içindeki XSLT şablonunu kullanır; şablon yoksa ya da hatalıysa GİB'in varsayılan şablonuyla gösterim önerir.

Excel'e aktarma, analiz için kullanışlıdır: her kalemi bir satıra yazan bir dönüşüm, alış raporlarını hızlandırır. Ama Excel tablosu fatura değildir. GİB'e göre e-Faturanın geçerli hâli, GİB üzerinden başarıyla geçmiş XML'dir. Saklama kılavuzu da e-Faturanın mali mühür ya da e-imzasıyla birlikte, orijinal hâlinde ve bütünlüğü korunarak saklanmasını ister.

Veriyi görüntüden okumayın. GİB'in portal kılavuzuna göre faturanın XSLT görüntüsü ile XML alanları arasında fark olursa XML'deki bilgiler esas alınır. PDF'ten ya da ekran görüntüsünden okunan bir tutar, XML'deki tutarla aynı olmak zorunda değildir.

OCR ne zaman hâlâ gerekir?

Gelen e-Fatura için OCR gerekmez; veri zaten XML'dedir. OCR, yapılandırılmış verisi elinize ulaşmayan belgelerde devreye girer: yurt dışı tedarikçilerin faturaları, kâğıt ya da yalnız PDF olarak gelen belgeler, taranmış irsaliye ya da sertifikalar.

Bu belgelerde doğruluğun nasıl ölçüleceğini ve OCR'ın ne zaman gereksiz olduğunu fatura okuma (OCR) yazımızda anlatıyoruz. Fatura gönderme tarafında özel entegratör, GİB portalı ve doğrudan entegrasyon arasındaki farkı ise e-Fatura entegrasyonu yazımızda karşılaştırıyoruz.

Paket ve kod listesi güncellemelerini izleyin

UBL-TR paketi ve kod listeleri durağan değildir. Yeni fatura tipleri, istisna kodları ve senaryolar eklendikçe ayrıştırıcınızın tanımadığı değerler gelebilir.

Güncel örnekler: UBL-TR Kod Listeleri'nin 1.43 sürümü 27 Temmuz 2026'da yayımlandı. GİB, 27 Temmuz 2026'da yayımladığı e-Fatura paketindeki eksiklikleri giderdiğini 24 Ağustos 2026'da duyurdu (e-Belge duyuruları (yeni sekmede açılır)).

İki önlem bu değişikliklerin etkisini sınırlar:

• Tanımadığınız bir fatura tipi ya da senaryo geldiğinde faturayı sessizce atlamayın; istisna ekranına düşürün.
• GİB'in e-Belge duyurularını düzenli takip edin ve kod listesi değiştiğinde eşleme tablolarınızı gözden geçirin.

Bizim deneyimimiz

e-Faturayı biz düzenlemiyoruz; bu iş GİB'in portalı, özel entegratörler ya da GİB'le doğrudan entegrasyon yoluyla yürür. Entegrasyon projelerinde bizim işimiz, sizin sisteminizi kullandığınız entegratörün servisiyle konuşturmaktır.

Bu tür bağlantılarda dört ilkeye bağlı kalıyoruz:

• Tekil işlem. Her işlem benzersiz bir anahtar taşır; aynı fatura ikinci kez gelse bile ikinci bir kayıt açılmaz.
• Sıralı işleme. İşler bir kuyruğa alınır ve sırayla işlenir; karşı servis geçici olarak yanıt vermediğinde veri kaybolmaz.
• Eşleme tabloları. Ürün kodları, vergi oranları ve durum adlarının iki sistemdeki karşılıkları kodun içine gömülmez, düzenlenebilir tablolarda durur.
• Hata ekranı. Takılan kayıt kaybolmaz; bir ekranda görünür, düzeltilir ve yeniden gönderilir.

Bu yaklaşımı sistem entegrasyonları sayfamızda, belgeden veri okumayı da içeren otomasyon işlerini süreç otomasyonu sayfamızda anlatıyoruz.

Sık sorulan sorular

e-Fatura XML dosyası nasıl açılır?

GİB'in E-Fatura Görüntüleyici programıyla açılabilir. Dosya uzantısı ".zip" değil ".xml" olmalıdır. Program yalnız XML görünümü gösteriyorsa ve dosya "StandardBusinessDocument" etiketiyle başlıyorsa, açtığınız şey faturanın kendisi değil zarfıdır.

UBL-TR nedir?

UBL-TR, uluslararası UBL 2.1 belge standardının GİB tarafından yapılan Türkiye özelleştirmesidir. e-Fatura, e-Arşiv Fatura ve e-İrsaliye gibi belgelerin XML yapısını tanımlar. Kılavuzları ve kod listeleri GİB'in e-Belge sitesinde yayımlanır.

e-Fatura XML'ini Excel'e aktarmak saklama yükümlülüğünü karşılar mı?

Hayır. Excel tablosu analiz için bir kopyadır. GİB'in saklama kılavuzu, e-Faturanın mali mühür ya da e-imzasıyla birlikte orijinal hâlinde ve bütünlüğü korunarak saklanmasını ister.

ETTN ile fatura numarası arasındaki fark ne?

Fatura numarası, faturayı düzenleyenin kendi numaralandırmasıdır ve onun bünyesinde tekildir. ETTN ise faturanın evrensel eşsizliğini sağlayan, GUID biçiminde bir numaradır. Mükerrer kontrolünde ikisini, satıcının VKN ya da TCKN'siyle birlikte kullanın.

Muhasebe yazılımım zaten e-Fatura içe aktarıyorsa ayrı bir akış gerekir mi?

Çoğu zaman gerekmez; önce kullandığınız yazılımın içe aktarma özelliğini deneyin. Ayrı bir akış; kalem eşleme kuralları, sipariş ve irsaliyeyle üçlü eşleştirme, istisna ekranı ya da birden fazla sistemi besleme ihtiyacı olduğunda anlam kazanır.

Kaynaklar

• Gelir İdaresi Başkanlığı. UBL-TR 1.2.1 Kılavuzları (yeni sekmede açılır): UBL-TR Fatura v1.0 (Aralık 2017), UBL-TR Kod Listeleri v1.43 (27 Temmuz 2026), UBL-TR Temel Fatura Senaryosu v0.2, UBL-TR Ticari Fatura Senaryosu v0.3. 13 Ekim 2026'da erişildi.
• Gelir İdaresi Başkanlığı. E-Fatura Görüntüleyici Kullanım Kılavuzu v1.0 (yeni sekmede açılır). 11 Eylül 2015.
• Gelir İdaresi Başkanlığı. e-Fatura Portalı Kullanım Kılavuzu v1.5 (yeni sekmede açılır). Kasım 2013.
• Gelir İdaresi Başkanlığı. e-Fatura Uygulaması Saklama Kılavuzu v1.1 (yeni sekmede açılır). 6 Eylül 2013.
• Gelir İdaresi Başkanlığı. e-Belge duyuruları (yeni sekmede açılır): e-Fatura paketi düzeltmesi, 24 Ağustos 2026. 13 Ekim 2026'da erişildi.