İki yol var:
Doğrudan GİB portalı: GİB'in kendi sunduğu entegrasyon. Maliyet düşük, özellik sınırlı. Teknik olarak SOAP/REST karışımı eski bir API. Büyük hacim ve otomatikleştirme için yetersiz.
Özel entegratörler: Türkiye'de 30+ onaylı entegratör var. En yaygınları EDM, TNB, Foriba (şimdi QNB Finansinvest), Uyumsoft, Mikrogrup, Digital Planet. Modern REST API, webhook desteği, yüksek hacim yönetimi, daha iyi dokümantasyon.
Çoğu B2B yazılım projesinde özel entegratör anlamlı — aylık işlem hacmine göre paketler, 500 TL/ay'dan yüksek hacimli kurumsal anlaşmalara kadar değişiyor. Doğrudan GİB sadece çok küçük ölçek ya da maliyet hassas MVP'lerde tercih edilebilir.
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:
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.
e-Fatura imzalanmadan gönderilemez. Türkiye'de yetkili zaman damgası sağlayıcıları (TÜBİTAK BİLGEM Kamu SM, TurkTrust, E-Güven) sertifika satıyor. Yıllık tipik maliyet düşük — kurumsal sertifika 500–2000 TL bandında.
Entegratör seçilen sertifikayla imzayı otomatik atar; siz sadece sertifika dosyasını yükler ve şifreyi API'ye iletir (gizli tutulur, vault'ta saklanır). Kendi imza altyapınızı yazmaya gerek yok — XAdES-BES format karmaşık ve hata kaldırmıyor.
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.
Sevk irsaliyesi elektronik ortamda düzenlenen belge. 2022'den beri lojistik, üretim ve toptan ticaret sektörlerinde zorunlu. 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.
Canlıda yüzlerce ila binlerce günlük fatura çıkabilir. Eş zamanlı API çağrısı yapmak sorun yaratır. Önerilen mimari:
Bu mimari 10 faturalık sistemde aşırı görünür; 10.000 faturalık sistemde hayat kurtarır.
Her özel entegratörün test ortamı var. Akış:
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.
Her GİB entegrasyonu projesinde özel entegratör seçimi için üç aday değerlendirip müşteriyle karar veriyoruz. 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.
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.
Genellikle entegratör. Siz sertifikanızı yükler, şifresini API'ye güvenli iletir; entegratör her faturayı adınıza imzalar. Kendi imza altyapısı yazmak gereksiz karmaşıklık — XAdES-BES formatı incedir ve hatasız uygulanması uzman iş.
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.
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.
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.
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.