e-Fatura, e-Arşiv, e-Defter ve e-İrsaliye Entegrasyonu: Geliştirici Rehberi

Doğrudan GİB mi, özel entegratör mü?

Üç yol var:

GİB Portalı: GİB'in web arayüzü. Faturalar elle düzenlenir; API sunmaz. Düşük hacimli mükellefler içindir, otomatikleştirme için uygun değildir.

Doğrudan (özel) entegrasyon: Mükellefin kendi bilgi işlem sistemi ve mali mührüyle, GİB başvurusu ve onayıyla kurulur. Teknik ve idari şartları ağırdır; genelde yüksek hacimli büyük firmaların yoludur, küçük ölçek ya da MVP yolu değildir.

Özel entegratörler: GİB'in yetkilendirdiği firmalardır; GİB'in e-Belge sitesindeki güncel listede (Kasım 2026 itibarıyla) 94 özel entegratör yer alıyor; liste değiştiği için seçimden önce yeniden bakılmalıdır. Örnek olarak EDM, Sovos (eski adıyla Foriba), Uyumsoft ve QNB eSolutions sayılabilir. Çoğu REST ya da SOAP tabanlı API ve yüksek hacim yönetimi sunar; webhook desteği ve dokümantasyon kalitesi entegratöre göre değişir.

Yazılım projelerinin çoğunda özel entegratörün API'si kullanılır; aylık işlem hacmine göre paketler sunuluyor, güncel fiyat doğrudan entegratörden alınmalıdır.

UBL-TR 1.2: format standardı

Türkiye'de e-Fatura UBL-TR 1.2 (Universal Business Language Türkiye uyarlaması) standardında. XML yapısı standardize; kısaca şu başlıkları içerir:

• Fatura başlığı (UBLVersionID, CustomizationID = "TR1.2")
• Düzenleyen ve alıcı bilgileri (PartyIdentification, CompanyID — VKN/TCKN)
• Satır kalemleri (Invoice Line) — ürün kodu, miktar, birim fiyat, KDV oranı
• Toplam ve yuvarlama (TaxTotal, LegalMonetaryTotal)
• XAdES imza bloğu

Geliştirme pratikte: XML template kütüphanesi (Node.js için xmlbuilder2, Python için lxml) ve entegratörün sağladığı SDK birleştirilir. Şablonu elle yazmaktan kaçının — entegratörün SDK'ı UBL-TR doğrulamayı baştan yapıyor.

Zaman damgası ve imza

e-Fatura imzalanmadan gönderilemez. GİB'in düzenlemesine göre e-Fatura tüzel kişilerde mali mühürle, gerçek kişilerde nitelikli elektronik sertifikayla onaylanır; mali mühür sertifikasını yalnızca TÜBİTAK BİLGEM Kamu SM verir.

Özel entegratör yönteminde belgeyi entegratörün sistemi imzalar; birçok entegratör bunu kendi mali mührü ya da donanım güvenlik modülüyle yapar. Sizin sertifikanızın bu akışta gerekip gerekmediğini entegratörünüz söyler; gerekiyorsa şifre koda yazılmaz, gizli anahtar kasasında (vault) saklanır. Kendi imza altyapınızı yazmaya gerek yok — XAdES-BES format karmaşık ve hata kaldırmıyor.

e-Arşiv farkı

e-Fatura, mükellefiyet açısından aynı statüdeki alıcıya kesilen fatura. e-Arşiv, e-Fatura mükellefi olmayanlara (son kullanıcı veya küçük mükellef) kesilen fatura. Teknik olarak benzer UBL-TR formatında ama GİB'e ulaşma akışı farklı — e-Fatura eşler arası gibi çalışırken (düzenleyen → GİB → alıcı), e-Arşiv düzenleyen tarafından GİB'e bildirilir ve alıcıya PDF/e-posta ile gönderilir.

B2C uygulamalarda (e-ticaret, perakende) e-Arşiv çoğunlukta; B2B'de e-Fatura. Karma yapılarda her iki akışı yönetebilmek önemli.

e-İrsaliye: lojistik için

Sevk irsaliyesi elektronik ortamda düzenlenen belge. e-İrsaliye; brüt satış hasılatı GİB'in belirlediği eşiği (2021 ve sonrası hesap dönemleri için 10 milyon TL) aşan e-Fatura mükellefleri ile tebliğde sayılan bazı sektörler (ör. demir-çelik) için zorunludur; ilk grup için zorunluluk 1 Temmuz 2022'de başladı. Güncel kapsam GİB'in 509 Sıra No'lu Tebliğ'inden ve değişikliklerinden kontrol edilir. Format UBL-TR benzeri; taşıyıcı, araç plakası, sevk tarihi, sevk adresi ek alanlar.

Entegrasyon e-Fatura ile aynı entegratör üzerinden. Ek mühendislik: sevk kapı çıkışı sırasında irsaliyenin hazır olması (gerçek zamanlı akış), taşıyıcı değişikliği yönetimi ve e-İrsaliye-fatura eşleştirmesi.

Mimari: kuyruklama ve yeniden deneme

Canlıda yüzlerce ila binlerce günlük fatura çıkabilir. Eş zamanlı API çağrısı yapmak sorun yaratır. Önerilen mimari:

• Mesaj kuyruğu (Redis, RabbitMQ, AWS SQS) — her kesilen fatura kuyruğa girer
• Worker süreçleri sırayla entegratör API'sını çağırır, cevap alır, durumu işler
• Yeniden deneme stratejisi — network hatası, rate limit, geçici GİB arızaları için üstel geri çekilme (exponential backoff) ile 3-5 deneme
• Ölü mektup kuyruğu — başarısız çağrılar manuel inceleme için ayrı tutulur
• Durum takibi — her fatura için (kesildi/gönderiliyor/GİB'e ulaştı/onaylandı/reddedildi) durum makinesi

Bu mimari 10 faturalık sistemde aşırı görünür; 10.000 faturalık sistemde hayat kurtarır.

Test ortamı ve canlıya alma

Her özel entegratörün test ortamı var. Akış:

1. Test ortamında kayıt — API anahtarı ve test sertifikası al
2. UBL-TR şablonunu ile örnek fatura kes ve gönder — yanıtı doğrula
3. Hata senaryolarını (yanlış VKN, KDV toplamı uyumsuzluğu, eksik alan) test et
4. Hacim testi — 1000 faturayı paralel gönder, sistem davranışını ölç
5. Müşteri tarafında uç-uca test — müşteri portalında faturayı görmeyi doğrula
6. Canlı ortam sertifikası ve gerçek API anahtarına geç
7. İlk 50 faturayı manuel kontrol et — sistemde yanlış alan varsa fark et

Canlı geçişten önce GİB'in planlı bakım saatlerini takip edin (tipik olarak gece yarısı sonrası); kritik entegrasyon kurulumu bu saatlere planlanmaz.

D'Cloud'un yaklaşımı

Bir GİB entegrasyonunda özel entegratör seçimini, müşterinin hacmi ve ihtiyacına göre birkaç aday üzerinden birlikte değerlendirmeyi öneriyoruz. Kurulum standart olarak sprint bazlı eser sözleşmesiyle — kapsam: entegratör bağlantısı, UBL-TR şablon, kuyruklama altyapısı, durum takibi, test ve canlıya alma. 15 gün ücretsiz hata düzeltme ilk gerçek fatura kesimi sırasında çıkan uyum eksikliklerini kapsar. Bu işler web yazılım ve geliştirme ve ERP ve iş yönetim sistemleri hizmetlerimizin ortak zeminidir.

Sonraki adım

GİB e-Belge zorunluluğu kapsamına giriyor veya mevcut sistemi modernleştiriyorsanız, entegratör seçimi ve mimari karar ilk haftada alınmalı. Ücretsiz online keşif görüşmesi planlayın — üç entegratörü karşılaştırır, hacminize uygun öneriyi paylaşırız.

Sık sorulan sorular

Kendi imzamı mı atayacağım, entegratör mü atacak?

Genellikle entegratör imzalar. Birçok özel entegratör belgeyi kendi mali mührü ya da donanım güvenlik modülüyle imzalar; sizin sertifikanızın gerekip gerekmediğini entegratörünüz söyler. Kendi imza altyapısı yazmak gereksiz karmaşıklık — XAdES-BES formatı incedir ve hatasız uygulanması uzman iş.

Test ortamında hesabım olmasaydı canlıya geçemez miyim?

Geçemezsiniz. Her özel entegratör canlıya almadan önce müşteri doğrulaması, test faturaları ve sözleşme imzası isteyecek. Süreç 1-2 haftayı bulur. Proje planına baştan ekleyin.

Birden fazla entegratöre fatura kesmek mümkün mü?

Teknik olarak mümkün ama pratik olarak tavsiye edilmez. GİB sisteminde her VKN için tek bir "entegrasyon tedarikçisi" kaydı var. Dönüşüm yaparken eski entegratörden yenisine geçiş prosedürü mevcut — birkaç gün kesinti bekleyin ya da paralel dönemi sözleşmede yönetin.

e-Arşiv için PDF'i kim üretir?

Entegratör UBL-TR'den PDF'i otomatik üretir ve size URL verir. Müşteriye e-posta ekinde gönderebilir ya da portalınıza linklenebilir. Kendi PDF şablonunuz olacaksa entegratör API'si bunu destekliyor mu kontrol edin — bazıları tasarımı esnek, bazıları sabit.

e-Defter için ERP'ye bağlı mı kalmalıyız?

Hayır ama pratikte bağlı kalmak kolay. e-Defter muhasebe defterlerinin elektronik hali ve mali müşavirin/ERP'nin ürettiği kayıtlardan otomatik derlenir. Özel geliştirmede muhasebe modülüyle entegrasyon mantıklı; ayrı bir e-Defter servisi kurmak işi ikiye katlar.