Türkiye'de belirli ciro sınırlarını aşan her işletme için e-Fatura zorunlu; e-Arşiv ise e-Fatura mükellefi olmayan alıcılara kesilen faturaları kapsıyor. Muhasebe programından bağımsız çalışan bir ERP'niz, kendi yazdığınız bir satış sisteminiz ya da e-ticaret altyapınız varsa, er ya da geç e-fatura entegrasyonu ihtiyacı masanıza gelir. Bu rehberde süreci teknik tarafıyla, gerçekçi süre ve maliyet aralıklarıyla anlatıyoruz.
İki Yol Var: GİB Portal mı, Özel Entegratör mü?
e-Fatura kesmenin teknik olarak iki yolu bulunur:
- GİB e-Fatura Portalı: Düşük hacimli işler için ücretsizdir ama manueldir — API otomasyonu için tasarlanmamıştır. Ayda birkaç fatura kesen bir işletme için yeterli olabilir; yazılım entegrasyonu isteyen hiçbir senaryo için uygun değildir.
- Özel Entegratör: GİB'in yetkilendirdiği firmalar (Foriba/Sovos, Logo, Mikro, Uyumsoft, İzibiz, eFinans, Turkcell e-Şirket vb.) size REST/SOAP API'ları sunar. Faturayı siz oluşturur, entegratör GİB'e iletir, yanıtları (kabul/ret) size webhook veya sorgulama ile döner.
Pratikte yazılım entegrasyonu yapan herkes özel entegratörle çalışır. Doğrudan GİB web servislerine bağlanmak da mümkündür ancak mali mühür yönetimi, zarf mantığı ve arşivleme yükümlülükleri nedeniyle küçük-orta ölçekli projelerde rasyonel değildir.
Teknik Temel: UBL-TR Formatı
Türkiye'deki e-belgeler UBL-TR (Universal Business Language'ın Türkiye uyarlaması) XML formatındadır. Entegrasyonun kalbi, sisteminizdeki fatura verisini geçerli bir UBL-TR belgesine dönüştürmektir:
- Zorunlu alanlar: VKN/TCKN, vergi dairesi, kalem bazında KDV oranları, ölçü birimleri (GİB kod listesinden), döviz kuru (TL dışı faturalarda).
- Senaryolar: Temel/ticari fatura senaryoları, iade faturası, tevkifatlı fatura, istisna faturası — her biri farklı alan kuralları taşır.
- Şema doğrulama: Belge, hem XSD şemasından hem de GİB'in schematron kurallarından geçmelidir. Entegratörler genellikle ön-doğrulama servisi sunar; canlıya çıkmadan bunu akışa mutlaka ekleyin.
Entegrasyon Mimarisi: Önerdiğimiz Akış
Yüzlerce fatura kesen bir sistemde sağlıklı mimari şu adımlardan oluşur:
- 1. Kuyruk tabanlı gönderim: Fatura oluşturma isteğini senkron API çağrısıyla değil, kuyruk (queue) üzerinden işleyin. Entegratör tarafında yaşanacak birkaç dakikalık kesinti, satış akışınızı durdurmamalı.
- 2. Durum makinesi: Her faturayı taslak → gönderildi → GİB'de → kabul/ret durumlarıyla izleyin. Alıcının e-Fatura mükellefi olup olmadığını (mükellef sorgulama servisi) fatura kesmeden ÖNCE kontrol edin — e-Arşiv/e-Fatura ayrımı buna göre yapılır.
- 3. Yanıt işleme: Ticari faturalarda alıcı 8 gün içinde ret dönebilir. Ret senaryosunu (iade akışı, muhasebe düzeltmesi) baştan tasarlamayan sistemler canlıda en çok burada sıkışır.
- 4. Arşivleme: Yasal saklama süresi boyunca belgelerin imzalı halleriyle erişilebilir olması gerekir. Entegratör arşivi + kendi yedeğiniz şeklinde çift katman öneriyoruz.
Sık Yapılan Hatalar
- Ölçü birimi ve KDV kodlarını sabitlemek: GİB kod listeleri güncellenir; kodları veritabanında yönetilebilir tutun.
- Yuvarlama farkları: Kalem bazlı KDV hesabıyla toplam KDV arasında kuruş farkı schematron'dan döner. Hesaplama stratejinizi (kalem bazlı) baştan sabitleyin.
- Test ortamını atlamak: Her entegratörün test ortamı vardır; tüm senaryoları (iade, tevkifat, ret) testte koşmadan canlıya çıkmayın.
- Tek entegratöre kilitlenmiş kod: Entegratör API'sini soyut bir katmanın arkasına alın; fiyat/hizmet nedeniyle entegratör değişimi Türkiye'de sık yaşanır.
Süre ve Maliyet: Gerçekçi Aralıklar
Orta karmaşıklıkta bir sistem için (tek şirket, standart satış senaryoları) entegrasyon tipik olarak 3-6 haftalık bir geliştirme işidir: UBL-TR eşleme ve doğrulama en az yarısını alır. Çok şirketli (holding/marketplace) yapılarda, iade ve tevkifat senaryolarıyla birlikte süre 8-10 haftaya uzayabilir. Entegratör tarafında ise kontör/fatura başına ücretlendirme yaygındır — hacminize göre yıllık maliyeti entegratörlerle pazarlık etmeye değer.
Sonuç
e-Fatura entegrasyonu, doğru mimariyle kurulduğunda "kur ve unut" kategorisinde çalışan bir sistemdir; yanlış kurulduğunda ise muhasebe ekibinizin her ay elle düzelttiği bir yük haline gelir. Alıcı mükellef sorgulama, ret akışları ve şema doğrulamayı baştan tasarlamak, canlıdaki sorunların %90'ını önler. Bu süreçte UBL-TR ve entegratör API'larıyla daha önce çalışmış bir ekiple ilerlemek, deneme-yanılma maliyetini ciddi biçimde azaltır.
