e-Fatura Entegrasyonu: Mimari, Entegratör API ve Tuzaklar

Kurumsal projelerde "e-faturaya sonra bakarız" cümlesi, projeyi en az bir ay geciktiren cümledir. Sipariş, sevkiyat ve tahsilat akışı tasarlanır; fatura ise "entegratörün bir API'si var, bağlanırız" diye ertelenir. Sonra numaralama kuralı, KDV yuvarlaması, ticari faturanın sekiz günlük kabul süreci, e-arşiv raporlaması ve entegratörün bakım penceresi teker teker ortaya çıkar.

Bu yazıda e-Fatura, e-Arşiv ve e-İrsaliye kavramlarını, kurumsal yazılımın Gelir İdaresi Başkanlığı (GİB) sistemine hangi yollarla bağlanabileceğini, özel entegratör API'si üzerinden kurulan referans mimariyi, numaralama ve durum takibi gibi kritik noktaları ve sahada en sık gördüğümüz tuzakları anlatıyoruz. Zorunluluk kapsamı (ciro eşikleri, sektörler) her yıl güncellendiği için güncel eşikleri GİB duyurularından ve mali müşavirinizden teyit edin; burada mevzuatı değil mimariyi ele alıyoruz.

Kavramlar: hangi belge, hangi durumda?

Belge	Ne zaman	Akış	Teknik not
e-Fatura	Alıcı da e-fatura mükellefiyse	Gönderici → GİB → alıcı; GİB posta kutusu üzerinden	Temel senaryoda alıcı yanıt veremez; ticari senaryoda 8 gün içinde kabul/ret
e-Arşiv fatura	Alıcı e-fatura mükellefi değilse (nihai tüketici, kayıtsız firma)	Gönderici → alıcı (e-posta/SMS/portal); GİB'e raporlanır	Kabul/ret yok; iptal ve düzeltme kuralları farklı
e-İrsaliye	Malın sevkiyatı	e-Fatura ile aynı altyapı; alıcı yanıtı var	Sevkiyat anında düzenlenir; faturadan bağımsız numara serisi

Yazılımın ilk sorusu her faturada aynıdır: alıcı e-fatura mükellefi mi? Cevap GİB'in kayıtlı kullanıcı listesinden (VKN/TCKN ile sorgu) gelir ve belgenin türünü belirler. Bu liste günlük değişir; sistemde önbelleklenir ama her fatura öncesi tazelenir.

GİB'e bağlanmanın üç yolu

GİB portalı: Elle kullanım; çok düşük hacimli işletmeler için. Kurumsal yazılımla entegre edilmez.
Doğrudan entegrasyon: Kendi sunucunuz GİB ile doğrudan konuşur; test süreçleri, mali mühür altyapısı ve 7/24 erişilebilirlik sorumluluğu sizdedir. Çok büyük hacimli ve teknik ekibi güçlü kurumlar dışında tercih edilmez.
Özel entegratör: GİB'den izinli bir hizmet sağlayıcının API'si (SOAP ya da REST) üzerinden gönderim, alım, imzalama, raporlama ve saklama. Kurumsal projelerin neredeyse tamamı bu yolu kullanır ve aşağıdaki mimari bu senaryo içindir.

Referans mimari

[Sipariş / Sevkiyat / Tahsilat]           iş akışı
          │
          ▼
[Fatura oluşturma — domain]               kalemler, KDV, iskonto, kur, numara tahsisi
          │
          ▼
[UBL-TR üretimi — eşleme katmanı]         Fatura → UBL-TR 1.2 XML, şema doğrulama
          │
          ▼
[Outbox: gönderilecek belgeler]           kayıt + gönderim aynı transaction'da
          │
          ▼
[Entegratör adaptörü]                     imza/mühür, gönderim, mükellef sorgusu, durum sorgusu
          │                                (timeout, retry, circuit breaker)
          ▼
[Durum takibi — zamanlanmış iş]           gönderildi → GİB'e ulaştı → alıcıya teslim → kabul/ret
          │
          ▼
[Arşiv + muhasebe entegrasyonu]           XML/PDF saklama, muhasebe fişi, mutabakat

Üç tasarım kararı bu mimariyi ayakta tutar:

Entegratör bir adaptörün arkasında. Uygulama FaturaGonderici, MukellefSorgu, DurumSorgu gibi kendi arayüzleriyle konuşur; entegratörün SOAP zarfları ve alan adları adaptörde kalır. Entegratör değiştirmek bir adaptör yazmaktır, projeyi yeniden yazmak değil.
Gönderim asenkron ve outbox üzerinden. Fatura kaydı ile "gönderilecek" kaydı aynı transaction'da yazılır; gönderici iş entegratör kesintisinde kuyruğu bekletir, açılınca yeniden dener. Kullanıcı ekranı entegratörün yanıt süresine bağlı değildir.
Durum bir durum makinesidir. Fatura oluşturulmakla bitmez; her aşama kayıt altındadır ve tersine geçişler (ret, iptal) kurallıdır.

public enum FaturaDurumu {
    TASLAK, NUMARALANDI, GONDERIM_KUYRUGUNDA, ENTEGRATORDE, GIBE_ULASTI,
    ALICIYA_TESLIM, KABUL_EDILDI, REDDEDILDI, IPTAL, HATA
}

public interface EntegratorPort {                       // uygulamanın kendi sözleşmesi
    boolean eFaturaMukellefiMi(VknTckn kimlik);
    GonderimSonucu gonder(Ettn ettn, byte[] ublXml, BelgeTuru tur);
    Optional<BelgeDurumu> durumSorgula(Ettn ettn);
    List<GelenBelge> gelenKutusu(Instant sonKontrol);
}

@Scheduled(fixedDelay = 60_000)
void durumlariGuncelle() {
    for (Fatura f : faturalar.bekleyenDurumdakiler(200)) {        // ENTEGRATORDE, GIBE_ULASTI, ALICIYA_TESLIM
        entegrator.durumSorgula(f.ettn()).ifPresent(d -> {
            f.durumGuncelle(d);                                     // kurallı geçiş; geçersizse istisna
            if (d.durum() == REDDEDILDI) olaylar.yayinla(new FaturaReddedildi(f.no(), d.gerekce()));
        });
    }
}

Kritik noktalar

Numaralama

Fatura numarası 16 hanelidir: üç haneli seri (birim kodu), dört haneli yıl ve dokuz haneli sıra numarası. GİB kuralı gereği seri içinde yıl bazlı, boşluksuz ve sıralı olmalıdır. Bu, numaranın yalnızca "kaydet" anında ve tek bir noktada (veritabanı sırası ya da kilitli sayaç tablosu) üretilmesi demektir. Numarayı taslak aşamasında ayırıp faturayı iptal etmek boşluk yaratır; iki uygulama örneğinin aynı sayacı kilitsiz artırması çift numara üretir. e-Fatura ve e-Arşiv için ayrı seriler kullanılır.

ETTN ve idempotency

Her belgenin evrensel tekil tanımlayıcısı ETTN (UUID) uygulama tarafından üretilir ve entegratöre iletilir. Aynı ETTN ile ikinci gönderim, entegratörde "zaten alındı" cevabı verir; bu, gönderim yeniden denemelerini güvenli kılan anahtardır. ETTN'yi her denemede yeniden üretmek çift fatura demektir.

KDV ve yuvarlama

UBL-TR'de kalem tutarları, vergi matrahları ve toplamlar ayrı ayrı yer alır ve şema doğrulamasında tutarlı olmalıdır. Kalem bazında yuvarlanan KDV toplamı ile toplam üzerinden hesaplanan KDV bir kuruş farklı çıkabilir; hangi yöntemin kullanıldığı muhasebeyle baştan kararlaştırılır ve tek yerde uygulanır. Yabancı para faturalarında kur, kur tarihi ve TL karşılıkları zorunlu alanlardır.

Ret, iptal ve iade

Ticari e-faturada alıcı sekiz gün içinde reddedebilir; ret, faturayı hukuken hükümsüz kılar ve sistemde REDDEDILDI durumu muhasebe fişini ters çevirmelidir. Temel e-faturada ret yoktur; düzeltme iade faturasıyla yapılır. e-Arşiv faturada iptal ve düzeltme kuralları GİB kılavuzuna bağlıdır. Bu üç akışın üçü de tasarlanmalıdır; sahada en çok "iptal ettik ama GİB'de duruyor" sorununu görürüz.

Gelen faturalar

Entegrasyon tek yönlü değildir: tedarikçilerinizin e-faturaları entegratörün gelen kutusuna düşer. Bunları çekip satın alma siparişiyle eşleştirmek, ticari faturaları süresi içinde kabul/ret etmek ve muhasebeye aktarmak ayrı bir akıştır ve çoğu zaman gönderimden daha fazla iş üretir.

Sahada en sık gördüğümüz tuzaklar

Entegratör API'sini doğrudan servis katmanında çağırmak: Kesintide kullanıcı bekler, entegratör değişince her şey değişir.
Mükellef listesini önbelleklemeden sorgulamak ya da hiç tazelememek: İlki entegratör kotasını tüketir, ikincisi yanlış belge türü üretir.
Durum takibini "gönderildi" ile bitirmek: GİB'e ulaşmayan ya da reddedilen fatura haftalarca fark edilmez.
Saat dilimi: Fatura tarihi ve saati Türkiye saatiyle; UTC saklayan sistemlerde gün kayması numaralama ve dönem hatası yaratır.
Test ortamında gerçek VKN'lerle çalışmak: Entegratörlerin test ortamı ayrı kimlikler kullanır; üretim mükellef sorgusu test faturasına karışmamalıdır.
Arşivi entegratöre bırakıp kendi kopyanızı tutmamak: Saklama yükümlülüğü mükellefe aittir; XML ve PDF'nin bir kopyası kendi depolamanızda olmalıdır.

Test ve mutabakat

Şema doğrulama: Üretilen her UBL-TR, gönderimden önce XSD ve schematron kurallarına karşı doğrulanır; hatalı belge entegratöre gitmeden yakalanır.
Contract testleri: Entegratörün gerçek yanıtları stub olarak kaydedilir; API'de değişiklik CI'da görünür.
Günlük mutabakat: Uygulamadaki fatura listesi ile entegratörden çekilen liste karşılaştırılır; eksik, fazla ve durum uyuşmazlıkları raporlanır.

Sık sorulan sorular

Entegratör değiştirmek ne kadar iş?

Entegratör bir adaptörün arkasındaysa birkaç hafta: yeni adaptör, kimlik/sertifika kurulumu, test ortamında doğrulama, geçiş gününde seri ve numara devamlılığı. Doğrudan servis katmanına gömülmüş entegrasyonlarda aylar sürebilir.

e-Arşiv raporlamasını kim yapar?

Özel entegratör kullanıldığında günlük e-Arşiv raporunu entegratör hazırlar ve GİB'e iletir; uygulamanın görevi belgeleri zamanında ve doğru göndermektir. Doğrudan entegrasyonda raporlama sizin sorumluluğunuzdadır.

Faturayı önce PDF olarak mı üretmeliyiz?

Hayır; kaynak belge UBL-TR XML'dir, PDF görselleştirmedir. PDF entegratörün ya da uygulamanın XSLT şablonuyla XML'den üretilir; iki belge arasında tutarsızlık olmaması için tek kaynaktan türetilmelidir.

Sonuç

e-Fatura entegrasyonu bir API çağrısı değil; numaralama, belge türü kararı, asenkron gönderim, durum makinesi, ret/iptal akışları, gelen kutusu ve arşivden oluşan bir alt sistemdir. Entegratörü adaptörün arkasında tutan, gönderimi outbox'tan yapan ve her belgenin durumunu izleyen bir tasarım, hem mevzuat değişikliklerine hem entegratör kesintilerine dayanır.

Mevcut uygulamanıza e-fatura, e-arşiv ve e-irsaliye entegrasyonu eklemek ya da sorunlu bir entegrasyonu güvenilir hale getirmek için entegrasyon ve otomasyon ve kurumsal uygulama geliştirme hizmetlerimize göz atabilirsiniz. Keşif görüşmesi ve ilk tahmin ücretsizdir.