Muhasebe ekibiniz her sabah sipariş listesini açıp faturaları portala tek tek giriyorsa, ay sonunda da bu faturaları yazılımınızdaki kayıtlarla eşleştirmeye çalışıyorsa sorun personel değil, bağlantı eksikliğidir. e-Fatura ve e-Arşiv entegrasyonu, faturanın satış yazılımınızdan, ERP'nizden veya e-ticaret sitenizden otomatik olarak oluşturulup Gelir İdaresi Başkanlığı (GİB) sistemine iletilmesi demektir. Çoğu işletme için bu bağlantı, GİB'den izinli bir özel entegratörün API'si üzerinden kurulur: yazılımınız fatura verisini entegratöre gönderir, entegratör belgeyi imzalayıp GİB'e iletir ve sonucu size bildirir. Bu yazıda yöntemler arasındaki farkı ve bir API entegrasyonunun adım adım nasıl kurulduğunu anlatıyoruz.
Not: Bu yazı genel bilgilendirme amaçlıdır; vergi danışmanlığı yerine geçmez. Hangi belgeyi düzenlemekle yükümlü olduğunuzu mali müşavirinizle teyit edin.
e-Fatura ile e-Arşiv arasındaki fark
İkisi de elektronik faturadır, ancak alıcıya göre ayrılır. e-Fatura, GİB sistemine kayıtlı iki mükellef arasında düzenlenir ve belge doğrudan alıcının elektronik posta kutusuna (sistemdeki adresine) ulaşır. e-Arşiv fatura ise e-Fatura sistemine kayıtlı olmayan alıcılara, yani nihai tüketicilere veya kayıtlı olmayan firmalara düzenlenir; alıcıya e-posta ya da kâğıt çıktı olarak iletilir ve GİB'e raporlanır.
Yazılım açısından bunun anlamı şudur: her fatura kesilmeden önce alıcının e-Fatura kayıtlı kullanıcısı olup olmadığı kontrol edilmeli ve belge türü buna göre belirlenmelidir. Bu kontrolü elle yapmak, entegrasyonların en çok hata üreten noktalarından biridir.
Hangi işletmelerin e-Fatura ve e-Arşiv uygulamasına geçmek zorunda olduğu ciro, sektör ve fatura tutarı gibi kriterlere bağlıdır ve bu eşikler zaman içinde güncellenir. Güncel kapsamı GİB'in e-Belge portalındaki duyurulardan ve mali müşavirinizden öğrenin; bu yazıda rakam vermiyoruz çünkü eski bir eşik, yanlış bir karara yol açabilir.
Üç kullanım yöntemi: Portal, özel entegratör, doğrudan entegrasyon
| Yöntem | Nasıl çalışır? | Kimin için uygun? | Sınırlama |
|---|---|---|---|
| GİB portalı | Faturalar GİB'in web arayüzünde elle düzenlenir | Fatura sayısı az, otomasyon ihtiyacı olmayan işletmeler | Yazılımınızla bağlantı yok; her belge tek tek girilir |
| Özel entegratör | GİB'den izinli bir firmanın yazılımı veya API'si kullanılır | Düzenli fatura kesen, e-ticaret veya ERP kullanan işletmelerin çoğu | Hizmet bedeli ödenir; entegratörün API kalitesine bağımlısınız |
| Doğrudan entegrasyon | İşletmenin kendi bilgi işlem sistemi doğrudan GİB'e bağlanır | Çok yüksek hacimli, güçlü BT ekibine sahip büyük işletmeler | Teknik, güvenlik ve başvuru gereklilikleri ağırdır |
KOBİ'lerin büyük çoğunluğu için doğru cevap özel entegratördür. Portal, fatura sayısı arttıkça insan kaynağını tüketir; doğrudan entegrasyon ise küçük ve orta ölçekli bir işletmenin taşıyamayacağı bir altyapı ve bakım sorumluluğu getirir. Özel entegratörle çalışırken de iki seçenek vardır: entegratörün kendi web arayüzünü kullanmak ya da yazılımınızı entegratörün API'sine bağlamak. Bu yazının konusu ikincisi.
API entegrasyonu adım adım
Aşağıdaki akış, yazılımınızın (ERP, ön muhasebe, e-ticaret altyapısı veya özel bir iş uygulaması) bir özel entegratör API'sine bağlanmasını anlatır. Alan adları entegratöre göre değişir; buradaki adlandırmalar örnek niteliğindedir.
- Hangi belgeleri keseceğinizi netleştirin. Yalnızca satış faturası mı, yoksa iade, tevkifatlı, istisnalı faturalar ve e-İrsaliye de mi? Mali müşavirinizle birlikte belge türlerini ve senaryoları listeleyin. Neden: entegrasyon kapsamı bu listeye göre belirlenir; sonradan eklenen her belge türü yeni alan eşlemeleri ve testler demektir.
- Entegratörü teknik kriterlerle seçin. Fiyatın yanında API dokümantasyonunun açıklığına, test (sandbox) ortamı olup olmadığına, REST mi SOAP mı kullanıldığına, toplu gönderim ve durum bildirimi (webhook) desteğine, gelen faturaları çekme imkânına ve PDF şablonlarının özelleştirilebilirliğine bakın. Neden: kötü belgelenmiş bir API, geliştirme süresini katlar ve her hata için destek hattına bağımlı kalırsınız.
- Başvuru ve yetkilendirme süreçlerini tamamlayın. e-Fatura uygulamasına kayıt, mali mühür veya elektronik imza ve entegratörle yapılan sözleşme, teknik çalışmaya paralel yürütülebilir. Entegratörden test ortamı için API anahtarı, kullanıcı adı ve şifre gibi kimlik bilgilerini alın; bunları kaynak kodun içine değil, sunucudaki ortam değişkenlerine veya bir gizli anahtar kasasına koyun.
- Veri modelinizi faturaya hazırlayın. e-Fatura, UBL-TR adı verilen ve uluslararası UBL standardına dayanan bir XML biçimindedir. Entegratör API'leri çoğunlukla bu XML'i sizin yerinize üretir, ama ihtiyaç duyduğu veriyi sizin sağlamanız gerekir: alıcının VKN veya TCKN'si, vergi dairesi, adresi; ürünlerin miktarı, birim kodu (örneğin adet için
C62, kilogram içinKGM), birim fiyatı, KDV oranı; varsa iskonto, istisna veya tevkifat kodu. Müşteri ve ürün kartlarınızda bu alanlar eksikse entegrasyondan önce tamamlanmalıdır. - Fatura numarası ve ETTN mantığını kurun. Her e-belgenin bir fatura numarası (seri ön eki, yıl ve sıra numarasından oluşur, örneğin
NXV2026000000001) ve bir ETTN'si (evrensel tekil tanımlayıcı, UUID biçiminde) vardır. Numarayı sizin mi üreteceğinizi yoksa entegratörün mü atayacağını baştan belirleyin. ETTN'yi fatura gönderilmeden önce kendi veritabanınıza yazın; ağ hatası nedeniyle yeniden denemede aynı ETTN ile gönderim yapmak, mükerrer faturayı önlemenin en sağlam yoludur. - Alıcı sorgusunu otomatikleştirin. Fatura oluşturulurken alıcının VKN veya TCKN'si ile e-Fatura kayıtlı kullanıcı sorgusu yapın. Kayıtlıysa belge e-Fatura olarak, alıcının posta kutusu etiketiyle gönderilir; değilse e-Arşiv olarak düzenlenir. Kayıtlı kullanıcı listesini entegratör API'sinden belirli aralıklarla çekip önbelleğe almak, her faturada canlı sorgu yapmaktan daha hızlıdır; ancak listeyi düzenli yenilemeyi unutmayın.
- Senaryoyu doğru seçin. e-Fatura'da en sık kullanılan iki senaryo temel ve ticari fatura senaryolarıdır; ihracat gibi özel durumlar için ayrı senaryolar bulunur. Ticari faturada alıcı, mevzuatta öngörülen süre içinde faturayı kabul veya reddedebilir; temel faturada böyle bir yanıt süreci yoktur. Ticari senaryo kullanıyorsanız yazılımınızın gelen kabul ve red yanıtlarını işleyebilmesi gerekir. Hangi senaryonun size uygun olduğuna mali müşavirinizle karar verin.
- Gönderimi asenkron ve izlenebilir yapın. Fatura entegratöre gönderildiğinde işlem hemen tamamlanmaz: belge önce kuyruğa alınır, imzalanır, GİB'e iletilir ve sonuç döner. Yazılımınızda her faturanın bir durum alanı olmalı (örneğin
taslak,gönderildi,GİB'e iletildi,alıcıya ulaştı,hata). Durumu entegratörün webhook bildirimiyle ya da belirli aralıklarla sorgulayarak güncelleyin. - Belgeyi alıcıya ulaştırın ve saklayın. e-Arşiv faturalarda alıcıya e-posta ile PDF veya bağlantı gönderilmesi gerekir; bunu entegratör yapabilir ya da kendi e-posta altyapınızdan gönderebilirsiniz. Faturanın XML ve PDF hâllerini yasal saklama yükümlülüğünü karşılayacak şekilde arşivleyin; entegratörün saklama hizmeti varsa kapsamını sözleşmede netleştirin.
- Gelen faturaları da bağlayın. Tedarikçilerden gelen e-Faturaları API ile çekip yazılımınıza aktarmak, alış faturalarının elle girilmesini ortadan kaldırır. Gelen faturadaki ürün satırlarını kendi stok kartlarınızla eşleştirmek için tedarikçi ürün kodu ile sizin ürün kodunuzu bağlayan bir eşleme tablosu tutun.
- İptal ve iade süreçlerini tanımlayın. e-Arşiv faturanın iptali, e-Fatura'da iade faturası düzenlenmesi ve ticari faturanın reddedilmesi farklı akışlardır. Her biri için yazılımda ayrı bir işlem ve yetki tanımlayın; fatura silme yetkisini hiçbir kullanıcıya vermeyin.
- Test ortamında uçtan uca deneyin, sonra canlıya alın. Kayıtlı ve kayıtsız alıcı, KDV istisnalı satış, iskontolu satır, iade, iptal ve ağ kesintisi gibi senaryoları test ortamında tek tek çalıştırın. Canlıya geçtikten sonraki ilk günlerde hata alan faturaları gösteren basit bir izleme ekranı hayat kurtarır.
Entegrasyonda sık yapılan hatalar
- Yuvarlama farkları: Satır bazında mı, toplamda mı yuvarlama yapıldığı yazılımınız ile entegratör arasında farklıysa kuruş farkları doğar ve belge reddedilebilir. Hesaplama kuralını tek bir yerde tanımlayın.
- Eksik müşteri bilgisi: Bireysel müşteriler için TCKN alanının boş bırakılması veya kurumsal müşterilerde vergi dairesinin yanlış yazılması sık rastlanan bir sorundur. Formlarda doğrulama kuralları kullanın.
- Mükerrer gönderim: Zaman aşımına uğrayan bir istek yeniden gönderildiğinde, ilk istek aslında başarılı olmuşsa aynı satış için iki fatura oluşabilir. ETTN'yi önceden üretip saklamak bu riski kapatır.
- Durumun takip edilmemesi: "Gönderdik, tamam" varsayımı, hata alan faturaların günlerce fark edilmemesine yol açar. Hata durumundaki belgeler için otomatik bildirim kurun.
- Kimlik bilgilerinin kodda tutulması: API şifresinin kaynak koduna yazılması, kod deposuna erişen herkesin fatura kesebilmesi anlamına gelir.
- Test ve canlı ortamın karışması: Test faturalarının canlı sisteme gitmemesi için ortam ayrımını yapılandırma dosyasıyla yönetin ve canlı ortamda açık bir uyarı gösterin.
E-ticaret siteleri ve pazaryerleri için notlar
Online satışta faturaların çoğu nihai tüketiciye kesildiği için e-Arşiv ağırlıklıdır. İnternet üzerinden yapılan satışlarda e-Arşiv faturada ödeme şekli ve gönderim bilgisi gibi ek alanların doldurulması beklenir; entegratörünüzün dokümanında bu alanların karşılıklarını bulun ve sipariş verisinden otomatik doldurun. Faturanın sipariş "kargoya verildi" durumuna geçtiğinde mi, yoksa ödeme onayında mı kesileceğine iş süreciniz ve mali müşavirinizle birlikte karar verin.
Hazır e-ticaret platformlarının çoğu bilinen entegratörlerle eklenti üzerinden çalışır; özel yazılımla kurulmuş bir sitede ise bağlantı doğrudan entegratör API'siyle yapılır. Sıfırdan bir online mağaza kuruyorsanız faturalama adımının genel süreçteki yerini e-ticaret sitesi kurma rehberimizde görebilirsiniz; altyapı tercihinin entegrasyon esnekliğine etkisini ise e-ticaret altyapısı seçimi yazımızda anlattık. Pazaryerlerinden gelen siparişlerde faturanın kim tarafından ve hangi sistemden kesileceği de ayrıca netleşmelidir; bu konuya pazaryeri entegrasyonu rehberimizde değindik.
ERP ve muhasebe yazılımıyla birlikte düşünün
e-Fatura entegrasyonu tek başına bir proje değil, satış-sevk-fatura-tahsilat zincirinin bir halkasıdır. Fatura e-ticaret sitesinden kesiliyor ama muhasebe kaydı ayrı bir programda tutuluyorsa, iki sistem arasında da bir bağlantı gerekir; aksi hâlde elle aktarım sorunu yer değiştirmiş olur. Bütün bu süreçleri tek bir veri kaynağında toplamak istiyorsanız ERP seçim rehberimiz iyi bir başlangıç noktasıdır.
Bazı işletmeler faturalama sonrasındaki adımları (müşteriye e-posta, muhasebe bildirim kanalına mesaj, tahsilat hatırlatması) bir otomasyon aracıyla bağlar. Bu tür akışların nasıl kurulduğunu n8n ile iş otomasyonu yazımızda örneklerle anlattık. Ancak faturanın kendisini oluşturan çekirdek mantığı, hataları yönetebilen ve kayıt tutan bir yazılım katmanında tutmanızı öneririz.
Proje öncesi kontrol listesi
- Düzenlenecek belge türleri ve senaryolar mali müşavirle birlikte listelendi.
- Entegratörün test ortamı ve API dokümantasyonu incelendi.
- Müşteri kartlarında VKN/TCKN, vergi dairesi ve adres alanları zorunlu hâle getirildi.
- Ürün kartlarında birim kodu ve KDV oranı tanımlandı.
- Fatura numarası ve ETTN üretim kuralı belirlendi.
- Durum takibi, hata bildirimi ve yeniden deneme mantığı tasarlandı.
- İptal, iade ve red akışları için yetkiler tanımlandı.
- Arşivleme ve saklama sorumluluğu sözleşmede netleştirildi.
Sık Sorulan Sorular
Özel entegratör kullanmak zorunlu mu?
Hayır. GİB portalı da kullanılabilir; ancak portal yazılımınızla otomatik bağlantı kurmaz. Faturalarınızı satış veya muhasebe yazılımınızdan otomatik kesmek istiyorsanız pratikte bir özel entegratörle ya da doğrudan entegrasyonla çalışmanız gerekir.
Entegratör değiştirirsek faturalarımız ne olur?
Geçmiş belgelerinizin XML ve PDF hâllerini eski entegratörden eksiksiz teslim almanız gerekir. Sözleşme yaparken veri teslimi ve arşiv erişimi koşullarını yazılı hâle getirin. Yazılım tarafında entegratöre özgü kodu ayrı bir katmanda tutarsanız, entegratör değişikliği tüm sistemi etkilemez.
e-Arşiv faturayı müşteriye nasıl ulaştırmalıyız?
Genellikle e-posta ile PDF veya görüntüleme bağlantısı gönderilir; müşteri isterse kâğıt çıktı da verilebilir. Gönderimi entegratör yapabilir ya da kendi e-posta altyapınızdan gönderebilirsiniz. Hangi yolu seçerseniz seçin, gönderimin kaydını tutun.
Kendi yazdığımız bir yazılımı entegratöre bağlayabilir miyiz?
Evet. Entegratörlerin çoğu REST veya SOAP tabanlı API sunar ve herhangi bir programlama diliyle bağlanılabilir. Kritik olan, veri modelinizin faturada istenen alanları eksiksiz karşılaması ve hata durumlarının doğru yönetilmesidir.
Entegrasyon ne kadar sürede tamamlanır?
Yalnızca satış faturası kesen, veri modeli hazır bir sistemde süre kısadır; iade, tevkifat, e-İrsaliye ve gelen fatura aktarımı eklendikçe test edilecek senaryo sayısı artar. En çok zamanı genellikle kod değil, eksik müşteri ve ürün verisinin tamamlanması alır.
Sonuç
e-Fatura ve e-Arşiv entegrasyonunda başarının sırrı, faturayı bir "dosya gönderme" işi olarak değil, durumları takip edilen, hataları yönetilen ve tekrar denenebilen bir süreç olarak tasarlamaktır. Doğru entegratörü seçmek, veri modelini hazırlamak ve test senaryolarını eksiksiz çalıştırmak, canlıya geçtikten sonraki sürprizleri büyük ölçüde ortadan kaldırır. Mevcut yazılımınızı bir özel entegratöre bağlamak veya faturalamayı da içeren bir iş uygulaması geliştirmek istiyorsanız özel yazılım hizmetimizi inceleyebilir, ihtiyacınızı konuşmak için bize yazabilirsiniz.
