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

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

İ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.

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. 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-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. 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.

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ı

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.

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. 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ş.

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.