E-Fatura Entegrasyonu Nasıl Yapılır? Entegratör Seçimi ve API Tarafı

Kısa cevap

E-fatura üç yöntemle kullanılabilir: GİB portalı üzerinden manuel, özel entegratör aracılığıyla ya da doğrudan entegrasyonla. Yazılımınızdan otomatik fatura kesmek istiyorsanız pratikte özel entegratör seçersiniz; entegratörün API’sine bağlanır, sipariş verinizi UBL-TR formatına dönüştürüp gönderirsiniz.

Bu konuda bulacağınız içeriklerin neredeyse tamamı entegratörlerin kendi pazarlama sayfalarıdır ve hepsi entegrasyonu “birkaç satır kod” olarak anlatır. Fatura göndermek gerçekten kolaydır. Zor olan, sipariş verisini doğru faturaya çevirmektir.

Hangi yöntemi seçmelisiniz?

Karar, aylık fatura adedi ve yazılım kapasitenizle ilgilidir.

GİB portalı. Ücretsiz, kurulum gerektirmez, tarayıcıdan fatura kesilir. Aylık birkaç fatura kesen işletme için yeterli. E-ticarette değil, çünkü her siparişi elle girmek ölçeklenmez.

Özel entegratör. GİB tarafından yetkilendirilmiş firmalar. API sunar, saklama yükümlülüğünü üstlenir, GİB ile teknik iletişimi yönetir. E-ticaret siteleri ve ERP kullanan işletmelerin standart tercihi.

Doğrudan entegrasyon. Kendi sisteminiz GİB ile doğrudan konuşur. Test ve sertifikasyon süreci, sürekli teknik uyum ve saklama sorumluluğu size aittir. Yalnızca çok yüksek hacimde ve kendi teknik ekibi olan kurumlar için anlamlı.

E-fatura ile e-arşivi de ayırmak gerekir. E-fatura, sistemde kayıtlı mükellefler arasında kapalı devre çalışır. Sistemde olmayan alıcılara, yani çoğu son tüketiciye, e-arşiv fatura düzenlenir. E-ticaret sitelerinin faturalarının büyük çoğunluğu e-arşiv faturadır ama B2B satış da yapıyorsanız iki senaryoyu birlikte kurmanız gerekir.

Zorunluluk eşikleri 509 sıra numaralı VUK Genel Tebliği ve sonraki değişiklikleriyle belirleniyor. Eşikler yıllar içinde kademeli olarak aşağı çekildi ve internet üzerinden satış yapanlar için genel eşikten daha düşük bir sınır uygulanıyor. Güncel rakamı GİB’in yayımladığı tebliğ metninden ya da mali müşavirinizden teyit edin.

Entegratör seçerken neye bakmalı?

Fiyat listeleri birbirine benzer, farkı yaratan teknik ayrıntılardır. Şu soruları sorun:

Dokümantasyon herkese açık mı? Sözleşme imzalamadan API dokümanını okuyabiliyor musunuz? Kapalı dokümantasyon, geliştirme tahmini yapmanızı imkânsız kılar. Bu tek başına eleyici bir kriter.

Test ortamı var mı, nasıl açılıyor? Gerçek fatura kesmeden uçtan uca deneme yapabilmelisiniz. Test ortamı için ayrı sözleşme ya da ek ücret isteyen sağlayıcı, geliştirme sürecinizi yavaşlatır.

Fiyatlama nasıl işliyor? Kontör paketi mi, aylık abonelik mi? Kullanılmayan kontör devrediyor mu? İptal edilen fatura kontör yakıyor mu? Bu son soru e-ticarette önemli: iade oranı yüksekse iptal ve iade faturaları maliyeti ikiye katlayabilir. Kontör bedeli, e-ticaret sitesi kurma maliyetinin en sık atlanan kalemlerinden biri.

Kapsam ne? E-fatura ve e-arşivin yanında e-irsaliye, e-serbest meslek makbuzu, e-müstahsil gerekiyor mu? Sonradan başka sağlayıcıya geçmek zahmetlidir.

Webhook desteği var mı? Fatura durum değişikliklerini (kabul, ret, iade) sürekli sorgulamak yerine bildirimle almak isteyeceksiniz.

Rate limit ve toplu gönderim. Kampanya günlerinde saatte yüzlerce fatura kesmeniz gerekebilir. Saniyede kaç istek atabileceğinizi ve toplu gönderim desteğini önceden öğrenin.

Şablon özelleştirme. Faturanın görsel şablonunu (XSLT) kendiniz düzenleyebiliyor musunuz, yoksa her değişiklik destek talebi mi?

Çıkış senaryosu. Sözleşme bittiğinde arşivinizi hangi formatta alacaksınız? Faturaların yasal saklama süresi uzundur; verinin taşınabilir olması sözleşmede yazılı olmalı.

Kriter	Neden önemli	Nasıl doğrularsınız
Açık dokümantasyon	Efor tahmini yapılabilir	Sözleşme öncesi linki isteyin
Test ortamı	Canlıda hata riski düşer	Demo hesap açtırın
Kontör iadesi	İptal maliyeti	Sözleşme metninde arayın
Webhook	Sorgu yükü azalır	Doküman içinde kontrol edin
Rate limit	Kampanya günü tıkanmaz	Yazılı sayı isteyin
Arşiv çıkışı	Sağlayıcı değişimi	Sözleşme maddesi olarak isteyin

Geçiş sırası: önce başvuru, sonra kod

Entegrasyona başlamadan tamamlanması gereken idari adımlar var ve bunlar geliştirme takvimini belirler.

Önce mali mühür ya da elektronik imza temin edilir. Başvuru ve teslim süresi birkaç haftayı bulabilir, bu yüzden ilk yapılacak iş budur. Ardından GİB üzerinden e-fatura ve e-arşiv uygulamalarına başvuru yapılır ve kullanım yöntemi olarak özel entegratör seçilir. Entegratörle sözleşme imzalandıktan sonra test hesabı açılır.

Geliştirme, test hesabı açıldıktan sonra başlar. Bu sıralamayı tersine çevirip önce kod yazan ekipler, hazır olan entegrasyonu haftalarca bekletir. Mali müşavirinizle başvuru tarihini ve zorunluluk başlangıcını birlikte planlayın; zorunluluk tarihinden sonra kesilen kâğıt fatura sorun yaratır.

API tarafında gerçekte ne yapılıyor?

Teknik akış her entegratörde benzerdir, isimlendirme değişir.

Kimlik doğrulama. Kullanıcı adı ve parola ile token alınır, token belirli bir süre geçerlidir. Token’ı her istekte yeniden almak yerine önbellekleyin, süresi dolduğunda yenileyin.

Belgenin hazırlanması. Fatura, UBL-TR formatında XML olarak üretilir. Çoğu entegratör JSON kabul edip dönüşümü kendisi yapar. JSON kolaydır ama alan eşlemesi hatalıysa hatayı geç fark edersiniz.

Gönderim ve asenkron sonuç. Gönderim çoğu zaman anında sonuç dönmez. Bir kuyruk numarası alır, durumu sonra sorgularsınız. Kodunuzun bu bekleme durumunu yönetmesi gerekir: “gönderildi” ile “kabul edildi” farklı durumlardır.

Idempotency. Aynı sipariş için iki kez fatura kesilmesi, düzeltmesi en zahmetli hatadır. Her fatura isteğine siparişe bağlı benzersiz bir anahtar verin ve gönderim öncesi o sipariş için fatura var mı diye kontrol edin. Ağ hatası sonrası yeniden deneme mantığı bu kontrol olmadan tehlikelidir.

ETTN ve PDF saklama. Fatura numarası ve ETTN sipariş kaydına yazılmalı. Müşteri “faturam nerede” dediğinde entegratör paneline girmek zorunda kalmayın.

Hata kuyruğu. Başarısız fatura istekleri sessizce kaybolmamalı. Yeniden denenebilir bir kuyruğa düşmeli ve belirli sayıda denemeden sonra insana bildirim gitmeli. Ay sonunda “on iki fatura kesilmemiş” keşfetmek istemezsiniz.

Sipariş verisini faturaya çevirmenin zor kısımları

Entegrasyonun asıl işi burada. Sipariş modeli ile fatura modeli birebir örtüşmez.

Kargo bedeli. Ayrı bir satır mı, ürün fiyatına dahil mi? KDV oranı hangi orandan hesaplanacak? Ücretsiz kargo kampanyasında satır sıfır tutarla mı görünecek?

Kupon ve indirim dağıtımı. Sepet geneline uygulanan 100 TL indirim, farklı KDV oranlı üç ürüne nasıl bölünecek? Orantılı dağıtım yapılmazsa fatura KDV toplamı sepet toplamıyla tutmaz. Bu, en sık karşılaşılan mutabakat sorunudur.

Yuvarlama. Kuruş farkları birikir. Satır bazında mı yoksa toplamda mı yuvarlama yapılacağına karar verin ve her yerde aynı kuralı uygulayın.

Alıcı tipi tespiti. Alıcı e-fatura mükellefiyse e-arşiv değil e-fatura kesilmeli. Bunun için GİB mükellef listesinin sorgulanması gerekir. Liste güncellenir, bu yüzden fatura anında sorgulamak, kayıt anında sorgulamaktan daha doğrudur.

Fatura kesim anı. Ödeme onaylandığında mı, ürün kargoya verildiğinde mi? Vergi mevzuatı faturanın malın teslim veya hizmetin ifa tarihinden itibaren belirli bir süre içinde düzenlenmesini ister ve bu sürenin vergilendirme dönemini aşmaması gerekir. E-ticarette pratik çözüm, kargoya verme anını tetikleyici yapmaktır. Kesin uygulamayı mali müşavirinizle netleştirin.

İptal ve iade. Kesilen fatura silinmez. Aynı gün içinde iptal edilebilecek durumlar ile iade faturası gerektiren durumlar farklıdır. Kısmi iadede yalnızca iade edilen satırlar için belge düzenlenir. Bu senaryoların hepsi kodda karşılığını bulmalı.

Sık sorulan sorular

Entegrasyon ne kadar sürer? Sadece fatura gönderimi birkaç gün. İptal, iade, kısmi iade, mükellef sorgusu ve hata kuyruğu dahil edildiğinde iki ile dört hafta arası bir iş çıkar. Süreyi belirleyen entegratörün API’si değil, sizin sipariş modelinizin karmaşıklığı.

Hazır e-ticaret altyapısı kullanıyorum, yine geliştirme gerekir mi? Çoğu altyapının hazır entegratör modülü vardır; WooCommerce mağazalarında ve Shopify kurulumlarında standart senaryolar çalışır. İndirim dağıtımı, farklı KDV oranları ve kısmi iade gibi konularda özelleştirme ihtiyacı çıkabilir.

Entegratör değiştirmek zor mu? API değişikliği bir geliştirme işidir ama asıl konu arşiv. Eski faturalarınızın yasal saklama süresi boyunca erişilebilir kalması gerekir. Geçiş planını arşiv devrini konuşarak başlatın.

Fatura kesildiğini müşteri nasıl görecek? Sipariş onay e-postasına PDF eklenebilir ya da hesabım sayfasında listelenebilir. İkisini birden yapmak destek yükünü azaltır.

Mali müşavirime ne düşer? Zorunluluk kapsamı, fatura kesim zamanı, KDV oranları ve iade belgeleri onun alanı. Yazılım tarafı bu kararları uygular, vermez.

---

Sipariş yönetiminizle muhasebe tarafını konuşturan entegrasyonları yazılım geliştirme hizmetlerimiz kapsamında kuruyoruz. Entegratör seçimini bağımsız değerlendiriyor, sonrasında hata kuyruğu ve mutabakat raporlarıyla birlikte teslim ediyoruz.