e-Fatura ve e-Arşiv Entegrasyonu: Teknik Rehber

01e-Fatura ve e-Arşiv Entegrasyonu: Teknik Rehber

Türkiye'de e-Fatura ve e-Arşiv uygulamaları, belirli ciro eşiklerini aşan ya da belirli sektörlerde faaliyet gösteren mükellefler için zorunludur; kapsam Gelir İdaresi Başkanlığı (GİB) düzenlemeleriyle her yıl genişlemektedir. Yazılımınızın fatura üretmesi yetmez; faturanın doğru formatta hazırlanması, GİB ya da özel entegratör üzerinden iletilmesi, alıcıya ulaşması ve yasal süre boyunca saklanması gerekir. Bu rehber, e-Fatura ve e-Arşiv entegrasyonunu yazılım projesi olarak ele alırken bilinmesi gereken kavramları ve tasarım kararlarını özetler.

Not: Bu rehber teknik bir özet niteliğindedir; mükellefiyet, kapsam ve süre bilgileri için GİB mevzuatı ve mali müşavirinizin görüşü esastır.

02Temel Kavramlar

e-Fatura ile e-Arşiv Farkı

e-Fatura, her iki tarafın da e-Fatura mükellefi olduğu durumlarda GİB sistemi üzerinden karşılıklı iletilen faturadır; alıcı faturayı kendi e-Fatura sistemine düşmüş olarak alır ve yanıt (kabul/red) verebilir. e-Arşiv fatura, alıcının e-Fatura mükellefi olmadığı durumlarda (nihai tüketici ya da e-Fatura'ya kayıtlı olmayan firma) düzenlenir; fatura alıcıya e-posta, SMS ya da kâğıt çıktı ile iletilir, GİB'e ise raporlanır. Yazılım, alıcının mükellefiyetini fatura anında sorgulayarak hangi belge türünün düzenleneceğine karar vermelidir.

UBL-TR Formatı

Her iki belge de UBL-TR (Universal Business Language, Türkiye uyarlaması) XML standardında hazırlanır. Fatura başlığı, taraf bilgileri, satırlar, vergi ve indirim kalemleri, toplamlar ve ek alanlar bu şemaya göre yazılır. Şema doğrulaması (XSD) ve GİB'in yayımladığı şematron kurallarına uyum, faturanın reddedilmemesi için ön koşuldur.

Entegrasyon Yöntemleri

GİB portal: Küçük hacimli mükellefler için web arayüzü; yazılım entegrasyonuna uygun değildir.
Doğrudan entegrasyon: Mükellefin kendi sistemini GİB web servislerine bağlaması; teknik yeterlilik ve sürekli uyum yükü gerektirir.
Özel entegratör: GİB'den izinli entegratör firmaların API'leri üzerinden gönderim; en yaygın ve pratik yöntemdir. Yazılım projelerinin büyük çoğunluğu bu yolu izler.

03Entegrasyon Mimarisi

Fatura Yaşam Döngüsü

Taslak: Sipariş ya da hizmet kaydından fatura verisi üretilir; alıcı mükellefiyeti sorgulanır (e-Fatura mı, e-Arşiv mi).
Doğrulama: UBL-TR şema ve iş kuralı kontrolleri yapılır; eksik vergi numarası, hatalı KDV oranı gibi sorunlar gönderimden önce yakalanır.
Gönderim: Belge özel entegratör API'sine iletilir; entegratör imzalayıp GİB'e gönderir ve bir belge kimliği döner.
Durum takibi: Belge durumu (kuyrukta, iletildi, kabul, red, hata) periyodik sorgu ya da webhook ile izlenir; e-Fatura'da alıcı yanıtı da takip edilir.
Arşivleme: İmzalı XML ve görüntü (PDF/HTML) yasal süre boyunca (genel kural on yıl) değiştirilemez biçimde saklanır.

Numara ve Seri Yönetimi

Fatura numaraları GİB kurallarına göre seri (üç karakter) + yıl + sıra numarası biçimindedir ve boşluk bırakılamaz. Numara üretimi, eş zamanlı işlemlerde çakışma olmaması için veritabanı düzeyinde kilitle ya da tek noktadan yapılmalıdır. Gönderim başarısız olan bir numara iptal ya da yeniden gönderim kurallarına göre ele alınır; numara asla "geri alınıp" başka faturaya verilmez.

Hata ve Yeniden Deneme

Entegratör servisleri geçici olarak yanıt vermeyebilir. Gönderim işlemleri kuyruğa alınmalı, yeniden denemeler üstel bekleme ile yapılmalı ve aynı belgenin iki kez gönderilmesini önlemek için belge kimliği (ETTN/UUID) kullanılmalıdır. Kalıcı hatalar (şema hatası, geçersiz vergi numarası) operasyon ekibine görünür bir hata kuyruğuna düşmelidir.

04Uygulamada Dikkat Edilecekler

Test ortamı: Entegratörlerin test ortamlarında uçtan uca senaryo (gönderim, kabul, red, iptal) çalıştırılmadan canlıya geçilmemelidir.
Senaryo türleri: Temel ve ticari fatura senaryoları, ihracat, yolcu beraberi eşya gibi özel senaryoların hangilerinin kapsamda olduğu baştan belirlenmelidir.
İptal ve itiraz: e-Arşiv faturada iptal, e-Fatura'da ticari senaryoda red ve harici itiraz yolları farklıdır; yazılım bu akışları ve süre sınırlarını desteklemelidir.
Muhasebe entegrasyonu: Fatura verisinin ERP ya da muhasebe yazılımına aktarımı, mükerrer kayıt oluşturmayacak biçimde tasarlanmalıdır.
KVKK: Fatura nihai tüketici verisi içerir; erişim yetkileri ve saklama süreleri KVKK ile uyumlu olmalı, e-Arşiv faturaların e-posta ile iletiminde alıcı adresi doğrulanmalıdır.
Görsel şablon: Faturanın HTML/PDF görüntüsü XSLT şablonuyla üretilir; kurumsal kimliğe uygun şablon hazırlanırken zorunlu alanların görünürlüğü korunmalıdır.

05Entegratör Seçerken Sorulacak Sorular

API dokümantasyonu güncel mi, test ortamı ve örnek kod sunuluyor mu?
Durum bildirimi için webhook desteği var mı, yoksa yalnızca sorgu mu?
Belge başına ve aylık ücretlendirme, arşiv saklama ücreti ve süresi nedir?
Hizmet seviyesi (erişilebilirlik) taahhüdü ve kesinti bildirimi nasıl yapılıyor?
Mevzuat değişikliklerinde şema güncellemeleri ne kadar sürede yansıtılıyor?

06Sonuç

e-Fatura ve e-Arşiv entegrasyonu, doğru tasarlandığında fatura sürecini elle müdahaleden arındıran ve muhasebe ile senkron çalışan bir altyapıya dönüşür. Kritik noktalar mükellefiyet sorgusu, şema doğrulaması, güvenilir kuyruk ve yeniden deneme mantığı, numara yönetimi ve yasal arşivlemedir. Mevcut yazılımınıza e-Fatura entegrasyonu eklemek ya da e-ticaret ve ERP akışlarınızla birleştirmek için ücretsiz ön değerlendirme talep edebilirsiniz.