E-Fatura Entegrasyonu: QNB eSolutions API ile Kapsamlı Teknik Rehber (2026)

Türkiye’de dijital dönüşüm sürecinin en kritik bileşenlerinden biri olan e-fatura uygulaması, işletmelerin muhasebe ve finans süreçlerini temelden değiştirmiştir. Gelir İdaresi Başkanlığı (GİB) tarafından zorunlu hale getirilen e-fatura sistemi, yalnızca yasal bir zorunluluk olmaktan öte, işletmelere operasyonel verimlilik, maliyet tasarrufu ve hızlı iş akışları sunmaktadır.

E-fatura entegrasyonu, kurumsal kaynak planlama (ERP) sistemleri, muhasebe yazılımları veya özel iş uygulamalarının, e-fatura altyapı sağlayıcılarının API’leri üzerinden otomatik olarak fatura oluşturmasını, göndermesini, almasını ve yönetmesini sağlayan teknik bir süreçtir. Bu entegrasyon sayesinde manuel veri girişi ortadan kalkar, hata oranları azalır ve gerçek zamanlı fatura takibi mümkün olur.

Bu kapsamlı rehberde, QNB eSolutions’ın sunduğu e-fatura API’sinin derinlemesine teknik detaylarını, entegrasyon süreçlerini, best practice’leri ve karşılaşılabilecek senaryoları ele alacağız.

QNB eSolutions API: Genel Mimarisi ve Sunduğu Çözümler

QNB eSolutions, e-fatura ekosisteminde çözüm ortakları ve müşteriler için web servis tabanlı bir entegrasyon platformu sunmaktadır. Platform, sadece e-fatura değil, aynı zamanda e-irsaliye, e-arşiv fatura ve e-defter gibi farklı elektronik belge türlerini de destekleyen kapsamlı bir yapıya sahiptir.

Platform Özellikleri

QNB eSolutions API’si, SOAP (Simple Object Access Protocol) tabanlı web servisleri kullanarak entegrasyon sağlar. Bu tercih, kurumsal sistemlerde yaygın kullanımı, güvenlik standartlarına uygunluğu ve hata yönetimi konusundaki olgunluğu nedeniyle önemlidir. Platform, hem senkron hem de asenkron işlem akışlarını destekleyerek farklı kullanım senaryolarına uyum sağlar.

API, stateless ve stateful olmak üzere iki farklı kimlik doğrulama mekanizması sunarak geliştiricilere esneklik kazandırır. WSSE (Web Services Security) standardına uyumlu güvenlik altyapısı, veri bütünlüğü ve gizlilik açısından endüstri standartlarını karşılar.

Kimlik Doğrulama: İki Farklı Authentication Yöntemi

E-fatura API entegrasyonunda güvenlik, en kritik konulardan biridir. QNB eSolutions, iki farklı kimlik doğrulama mekanizması sunarak farklı mimari yaklaşımlara destek sağlar.

SOAP Header Authentication (Stateless Yaklaşım)

İlk yöntem, her API çağrısında kullanıcı adı ve şifre bilgilerinin SOAP başlığında (header) gönderilmesini gerektirir. Bu yöntem, WSSE UsernameToken standardını kullanır ve stateless bir yapıya sahiptir. Her istek bağımsızdır ve sunucuda oturum bilgisi saklanmaz.

Bu yaklaşımın avantajları:

• Microservices mimarilerine uygunluk
• Ölçeklenebilirlik (horizontal scaling kolaylığı)
• Oturum yönetimi gerektirmemesi
• Load balancer arkasında sorunsuz çalışma

SOAP Header yöntemi özellikle dağıtık sistemlerde, container tabanlı deployment’larda ve cloud-native uygulamalarda tercih edilir.

Cookie Container Authentication (Stateful Yaklaşım)

İkinci yöntem, HTTP oturumu bazlı çerez (cookie) yönetimine dayanır. İlk olarak wsLogin metodu ile giriş yapılır ve dönen cookie bilgisi sonraki isteklerde kullanılır. Bu yöntem CookieContainer parametresi ile yönetilir.

Bu yaklaşımın avantajları:

• Her istekte kimlik bilgisi göndermeme
• Potansiyel performans avantajı (authentication overhead azalması)
• Geleneksel web uygulamalarıyla uyumluluk

Stateful yaklaşım, özellikle monolitik uygulamalarda ve session yönetimi olan sistemlerde tercih edilebilir. Ancak oturum süresi dolduğunda yeniden login gerektiği unutulmamalıdır.

e-Fatura Gönderim Süreci: Adım Adım Teknik Akış

e-fatura gönderimi, birden fazla adımdan oluşan asenkron bir süreçtir. Bu yaklaşım, sistem performansını optimize ederken aynı zamanda hata yönetimi ve takip konusunda esneklik sağlar.

Adım 1: Fatura Oluşturma ve Gönderme (belgeGonderExt)

e-fatura gönderimi için belgeGonderExt metodu kullanılır. Bu metot, faturanın sisteme yüklenmesini ve işleme kuyruğuna alınmasını sağlar. Metodun temel parametreleri şunlardır:

vergiTcKimlikNo: Alıcının 10 haneli vergi numarası veya 11 haneli TC kimlik numarası. Bu parametre, faturanın doğru muhatabına ulaşması için kritik önem taşır.

belgeTuru: E-fatura için “FATURA_UBL” değeri kullanılır. UBL (Universal Business Language), uluslararası standart bir XML formatıdır ve Türkiye’deki e-fatura altyapısı bu standartta çalışır.

belgeNo: Yerel sisteminizdeki fatura numarası. Bu numara, kendi ERP sisteminizde oluşturduğunuz benzersiz fatura kimliğidir ve sonraki sorgulama işlemlerinde referans olarak kullanılabilir.

veri: Fatura XML içeriğinin Base64 encode edilmiş hali. UBL formatında oluşturulmuş XML belgesi, güvenli veri transferi için Base64 kodlaması yapılarak gönderilir.

belgeHash: Fatura içeriğinin MD5 hash değeri. Bu parametre, veri bütünlüğünün kontrolü için kullanılır ve transfer sırasında verinin değişip değişmediğini tespit etmeyi sağlar.

mimeType: Genellikle “application/xml” değeri kullanılır ve gönderilen verinin içerik tipini belirtir.

belgeVersiyon: E-fatura için “1.0” değeri kullanılır. Bu, kullanılan UBL şema versiyonunu belirtir.

Metot başarılı olduğunda dönen en önemli değer belgeOid’dir. Bu, sistemde oluşturulan belgenin tekil tanımlayıcısıdır (unique identifier) ve sonraki tüm durum sorgulama işlemlerinde kullanılır.

Kritik bir nokta: Fatura gönderimi gerçekleştirildiğinde, fatura hemen gönderilmez, önce işleme kuyruğuna alınır. Bu asenkron yaklaşım, sistemin yüksek yük altında da stabil çalışmasını sağlar.

Adım 2: Durum Sorgulama ve Takip (gidenBelgeDurumSorgulaExt)

Fatura kuyruğa alındıktan sonra, işlenme durumunun takip edilmesi zorunludur. gidenBelgeDurumSorgulaExt metodu bu amaçla kullanılır ve sistematik olarak çağrılmalıdır.

Metodun parametreleri:

belgeNo: Sorgulanacak belgenin numarası. Bu değer iki farklı formatta gönderilebilir: - OID: Sistemin ürettiği belgeOid değeri (önerilen) - YEREL: Kendi sisteminizde kullandığınız belge numarası

belgeTuru: “FATURA” değeri ile sorgu yapılır.

Response içerisinde gelen kritik bilgiler:

durumKodu: İşleme durumunu gösterir: - 1 (Alındı): Fatura başarıyla alındı ve işlenmeyi bekliyor - 2 (İşleme Hatası): Şema, şematron veya business rule kontrollerinde hata oluştu - 3 (İşlendi): Fatura başarıyla işlendi ve GİB’e gönderilmeye hazır

aciklama: Duruma ait detaylı açıklama. Özellikle hata durumlarında bu alan, sorunu tespit etmek için hayati önem taşır.

Durum 2 (İşleme Hatası) alındığında, response içerisindeki açıklamaya göre gerekli düzenlemeler yapılarak belge yeniden belgeGonderExt ile gönderilmelidir. Yaygın hatalar arasında eksik zorunlu alanlar, yanlış format, tutarsız hesaplamalar bulunur.

Adım 3: Gönderim Durumu ve Alıcı Yanıtı Takibi

Fatura işlendikten sonra, GİB üzerinden alıcıya gönderim süreci başlar. Bu süreçte farklı durum kodları ile karşılaşılabilir:

Gönderim Durum Kodları:

•             -2 (İptal Edildi): Fatura iptal edildi ve gönderilmeyecek

•             -1 (Kuyruğa Eklendi): Fatura gönderim kuyruğunda bekliyor

•             0 (Gönderilemedi): Geçici bir sorun nedeniyle gönderilemedi, sistem otomatik olarak yeniden deneyecek

•             1 (Gönderilecek): Fatura gönderime hazır

•             2 (Gönderildi): Fatura GİB sistemine başarıyla gönderildi

•             3 (GİB Merkez Yanıtı Geldi): GİB’den onay yanıtı alındı

•             4 (Alıcı Yanıtı Geldi): Alıcıdan uygulama yanıtı geldi

Alıcı Durum Kodları:

•             1200: Fatura GİB ile alıcı sistemi arasında

•             1210: Alıcıya iletim başarısız, sistem yeniden denemeye devam ediyor

•             1215: 5 deneme sonrası iletim başarısız oldu (kritik durum)

•             1220: Alıcıya başarıyla iletildi, yanıt bekleniyor

•             1230: Alıcıdan başarısız sistem yanıtı geldi

Bu durum kodlarının düzenli olarak sorgulanması ve log’lanması, hem müşteri hizmetleri hem de teknik destek açısından son derece önemlidir. Özellikle 1215 kodunun geldiği durumlar (5 deneme sonrası başarısızlık) manuel müdahale gerektirebilir.

Kayıtlı Kullanıcı Sorgulama: E-Fatura Mükellefi Kontrolü

E-fatura gönderebilmek için alıcının e-fatura sistemine kayıtlı olması zorunludur. Aksi takdirde fatura, e-arşiv fatura olarak düzenlenmelidir. Bu nedenle fatura düzenlemeden önce alıcının e-fatura mükellefi olup olmadığının sorgulanması kritik öneme sahiptir.

efaturaKullaniciBilgisi Metodu

Bu metot, bir vergi/TC kimlik numarasının e-fatura sisteminde kayıtlı olup olmadığını ve ilgili detay bilgilerini sorgular.

Request Parametresi: - vergiTcKimlikNo: Sorgulanacak 10-11 haneli kimlik numarası

Response Parametreleri:

etiket: Mükellefin sistemdeki kayıtlı e-fatura posta kutusu adresi. Her e-fatura mükellefi, GİB tarafından oluşturulan veya kendi belirlediği bir etiket adresine sahiptir. Bu etiket, e-faturaların yönlendirilmesi için kullanılır.

kamuKurulusu: Boolean değer olarak döner. True ise alıcı bir kamu kurumudur ve bazı özel kurallar uygulanabilir.

kayitZamani: Mükellefin e-fatura sistemine dahil olduğu tarih. Bu bilgi son derece kritiktir çünkü dokümantasyonda açıkça belirtildiği üzere: “Kayıt zamanından önceki tarihe düzenlenecek faturalar, e-Arşiv Fatura olarak düzenlenmelidir.”

Örneğin, bir müşteriniz 15 Mayıs 2024’te e-fatura sistemine katıldıysa, 1 Mayıs 2024 tarihli bir geçmiş fatura düzenlemeniz gerekiyorsa, bu faturanın e-arşiv olarak düzenlenmesi gerekir.

unvan: Mükellefin resmi şirket unvanı. Bu bilgi, fatura düzenleme sırasında alıcı bilgilerinin doğrulanması için kullanılabilir.

Kayıtlı Kullanıcı Listesinin Toplu Olarak Alınması

E-fatura sistemine yeni katılan veya çıkan mükelleflerin güncel listesini almak için kayitliKullaniciListeleExtended metodu kullanılır.

Parametreler:

gecmisEklensin: “1” değeri gönderildiğinde, etiket değişikliği yapan mükelleflerin hem eski hem yeni bilgileri listeye dahil edilir. Bu parametre, mükellef bilgilerinin geçmişini takip etmek için kritiktir.

urun: E-fatura için “EFATURA” sabit değeri kullanılır.

Response: Base64 formatında sıkıştırılmış (zip) bir dosya döner. Bu dosya decode ve unzip edildikten sonra XML formatında mükellef listesine ulaşılır.

Önemli bir not: Kayıtlı kullanıcı listesi, sistemde 4 saatlik periyotlarda güncellenmektedir. Bu nedenle, gerçek zamanlı sorgulama yerine cache mekanizmaları kullanarak bu listeyi lokal olarak saklamak ve 4 saatte bir güncellemek, performans açısından önerilir.

Gelen Fatura Yönetimi: Alıcı Perspektifinden Entegrasyon

E-fatura entegrasyonu sadece fatura göndermekle sınırlı değildir. Alınan faturaların sisteme otomatik olarak çekilmesi, muhasebe sistemine kaydedilmesi ve gerektiğinde yanıt gönderilmesi de entegrasyonun önemli bir parçasıdır.

gelenBelgeleriListeleExt Metodu

Bu metot, sisteme gelen faturaların listelenmesi için kullanılır. Pagination yaklaşımı ile çalışır ve maksimum 100 belgeyi tek seferde döner.

Zorunlu Parametreler:

vergiTcKimlikNo: Faturaları alınacak mükellefin kimlik numarası

sonAlinanBelgeSiraNumarasi: Sayfalama için kullanılan sıra numarası. İlk çağrıda “0” gönderilir, sonraki çağrılarda sistemin döndüğü son belge sıra numarası kullanılır. Bu yaklaşım, cursor-based pagination mantığıyla çalışır.

Opsiyonel Parametreler:

belgeTuru: Filtreleme için kullanılır. Değerler: - FATURA: Sadece e-faturalar - UYGULAMA_YANITI: Gönderilen faturalara alıcılardan gelen yanıtlar

alanEtiket: Belirli bir etiket adresinden gelen belgeleri filtrelemek için kullanılır.

belgelerAlindiMi: Daha önce alınan belgelerin tekrar listelenmesini kontrol eder.

ettn: Belirli bir ETTN (Elektronik Transfer Tanımlama Numarası) değerine sahip belgeyi sorgulamak için kullanılır.

faturaTarihiBaslangic ve faturaTarihiBitis: Tarih aralığına göre filtreleme için kullanılır. Format: yyyy-MM-dd

Response Yapısı:

Dönen liste, belgeSiraNo değerine göre küçükten büyüğe sıralanır. Bu sıralama garantisi sayesinde, hiçbir faturanın atlanmadan çekildiğinden emin olunabilir.

Her belge için dönen temel bilgiler: - belgeOid: Sistemdeki tekil tanımlayıcı - belgeSiraNo: Pagination için kullanılan sıra numarası - ettn: Elektronik transfer tanımlama numarası - belgeNo: Fatura numarası - belgeninGonderenininVKNTCKN: Gönderen tarafın kimlik numarası - belgeTarih: Belge tarihi - durumKodu: Belgenin durumu

Gelen Faturaları Periyodik Olarak Çekme Stratejisi

Gelen faturaların kaçırılmaması için sistematik bir polling stratejisi uygulanmalıdır:

1.          İlk çağrıda sonAlinanBelgeSiraNumarasi = 0 ile başlayın

2.          Dönen her batch’te en yüksek belgeSiraNo değerini saklayın

3.          Sonraki çağrıda bu değeri kullanarak kaldığınız yerden devam edin

4.          Response’ta hiç belge dönmeyene kadar devam edin

5.          Periyodik olarak (örn: her 15 dakikada) bu döngüyü tekrarlayın

Bu yaklaşım, hem tüm faturaların alınmasını garanti eder hem de gereksiz API çağrılarını minimize eder.

Belge İndirme İşlemleri: Görselleştirme ve Arşivleme

E-faturaların ham XML formatı dışında, PDF veya HTML formatında görselleştirilmiş hallerine ihtiyaç duyulabilir. Bu, hem son kullanıcıların faturaları incelemesi hem de yasal arşivleme gereksinimleri için önemlidir.

gidenBelgeleriIndirExt ve gelenBelgeleriIndirExt Metodları

Bu metodlar, giden ve gelen belgelerin farklı formatlarda indirilmesini sağlar.

Parametreler:

vergiTcKimlikNo: İlgili mükellef kimlik numarası

belgeOidListesi veya belgeEttn: İndirilecek belgelerin tanımlayıcıları. Birden fazla belge aynı anda indirilebilir.

belgeTuru: İndirilecek belge tipi: - FATURA: E-fatura - IRSALIYE: E-irsaliye - UYGULAMA_YANITI: Uygulama yanıtları - IRSALIYE_YANITI: İrsaliye yanıtları

belgeFormati: İstenilen çıktı formatı: - UBL: Ham XML formatı (programatik işlemler için) - PDF: Yazdırılabilir PDF formatı (arşivleme ve inceleme için) - HTML: Web tabanlı görüntüleme için

Response Yapısı:

Metodlar, Base64 encode edilmiş ZIP dosyası döner. Bu dosyanın işlenme adımları:

1.          Base64 string’i decode edin

2.          Elde edilen binary veriyi ZIP dosyası olarak kaydedin

3.          ZIP dosyasını extract edin

4.          İçerisindeki PDF/HTML/XML dosyalarına erişin

Bu yaklaşım, birden fazla belgenin tek bir response’ta verimli şekilde transfer edilmesini sağlar. Özellikle toplu belge indirme senaryolarında bandwidth kullanımını optimize eder.

e-Fatura Görüntüleme Linkleri

E-fatura görüntüleme linkleri doğrudan API metodları tarafından üretilmemektedir. Bu konuda ihtiyacınız varsa proje@destek.qnbesolutions.com.tr adresine başvurunuz.

Belge Formatı Seçim Stratejisi

UBL (XML) Format: - Programatik işlemler için idealdir - Parsing ve veri extraction gerektiğinde kullanılır - ERP sistemine veri aktarımı için tercih edilir - En küçük dosya boyutu

PDF Format: - Son kullanıcı görüntüleme için en uygun - Yazdırma ve email gönderimi için kullanılır - Yasal arşivleme standartlarına uygun - Her ortamda standart görünüm

HTML Format: - Web uygulamalarında inline görüntüleme için - Daha esnek görselleştirme imkanı - Browser’da direkt açılabilir - Responsive tasarım uyumlu

e-Arşiv Fatura: Senkron İşlem Akışı

e-Arşiv fatura, e-fatura mükellefi olmayan alıcılara kesilen faturalar için kullanılan bir sistemdir. E-fatura’dan farklı olarak e-arşiv senkron çalışır, yani fatura oluşturma isteği gönderildiğinde, sistem işlemi tamamlayıp sonucu hemen döner.

faturaOlusturExt Metodu

e-Arşiv fatura oluşturmak için kullanılan metoddur.

Parametreler:

donenBelgeFormati: Sistemin döneceği format: - 0: UBL (XML) - 2: HTML - 3: PDF - 9: Belge dönmeyecek (sadece işlem yapılacak)

islemId: UUID veya ETTN değeri. Her fatura için benzersiz bir tanımlayıcı sağlanmalıdır. Java’da UUID.randomUUID(), C#’ta Guid.NewGuid() kullanılabilir.

vkn: Fatura kesen tarafın vergi kimlik numarası

sube: Şube kodu. Portal üzerinden çalışıyorsanız “DFLT” değeri otomatik tanımlanır.

kasa: Kasa kodu. Benzer şekilde portal için “DFLT” kullanılır.

erpKodu: Entegrasyon yapan sistemin kodu. Bu parametre zorunludur ve sisteminizi tanımlar.

belgeIcerigi: UBL formatında XML içeriğinin Base64 encoded hali.

Response Yapısı:

output: İstenilen formatta (PDF/HTML/UBL) belge içeriği. Base64 encoded olarak döner.

resultExtra: Properties formatında ek bilgiler: - faturaURL: Faturanın web’de görüntülenebileceği URL - uuid: Sistemin oluşturduğu benzersiz tanımlayıcı - faturaNo: Sistemin atadığı fatura numarası - iptalTarihi: İptal durumunda iptal tarihi

e-Arşiv Faturada Otomatik Email Gönderimi

Dokümantasyonda belirtilen önemli bir özellik: “Programınız üzerinden gönderilecek e-Arşiv Fatura XML dosyası içerisinde eğer alıcı e-posta adresi varsa, sistemimiz mail gönderimini otomatik olarak sağlayabilmektedir.”

Bu özellik sayesinde, UBL XML içerisinde alıcının email adresi doğru şekilde tanımlanırsa, sistem otomatik olarak faturayı email ile alıcıya iletir. Bu, manuel email gönderimi ihtiyacını ortadan kaldırarak operasyonel verimliliği artırır.

XML içerisinde email adresi, genellikle cac:Contact/cbc:ElectronicMail veya cac:Party/cac:Contact/cbc:ElectronicMail tag’leri içerisinde tanımlanır.

Hata Yönetimi ve Best Practices

E-fatura entegrasyonunda karşılaşılabilecek hatalar ve bunların yönetimi, sistemin güvenilirliği açısından kritik öneme sahiptir.

Yaygın Hata Senaryoları ve Çözümleri

Durum 2 (İşleme Hatası) Alınması:

Fatura gönderildikten sonra durumKodu = 2 alındığında, response içerisindeki “aciklama” alanında hatanın detayı yer alır. Yaygın hatalar:

1.          Şema Hatası: XML’in UBL şemasına uygun olmaması

–            Çözüm: XML validasyon tool’ları ile gönderim öncesi kontrol

–            XSD dosyaları ile offline validasyon yapılmalı

2.          Şematron Hatası: İş kurallarının ihlal edilmesi

–            Örnek: KDV oranının yanlış hesaplanması

–            Çözüm: Business logic kontrolleri entegre edilmeli

–            Toplam tutarlar, KDV hesaplamaları otomatik doğrulanmalı

3.          Eksik Zorunlu Alanlar: Zorunlu field’ların doldurulmaması

–            Çözüm: Template validation ve mandatory field checking

–            Unit testlerde zorunlu alanların varlığı kontrol edilmeli

Alıcıya İletim Başarısızlığı (Durum Kodu 1215):

5 deneme sonrası alıcıya iletilemeyenler için: - Alıcının sistem durumunu kontrol edin - Alıcının etiket bilgisinin güncel olduğunu doğrulayın - GİB portal üzerinden manuel kontrol yapın - Gerekirse alıcı ile iletişime geçin

Retry Mekanizması ve Idempotency

Ağ hataları veya geçici sistem sorunları durumunda retry mekanizması implementasyonu önerilir:

Retry Stratejisi:
- İlk deneme: Anında
- 2. deneme: 5 saniye sonra
- 3. deneme: 30 saniye sonra
- 4. deneme: 2 dakika sonra
- 5. deneme: 5 dakika sonra

Kritik nokta: Her fatura için unique belgeNo kullanılmalı ve aynı belgeNo ile yapılan tekrar gönderimler idempotent olmalıdır. Yani aynı faturanın birden fazla kez gönderilmesi durumunda sistem duplikasyon oluşturmamalıdır.

Logging ve Monitoring

Üretim ortamında kapsamlı logging implementasyonu zorunludur:

Loglanması Gereken Bilgiler: - Her API çağrısının timestamp’i - Request ve response payload’ları (hassas bilgiler maskelenerek) - belgeOid ve yerel belge numarası eşleşmeleri - Durum kodu değişiklikleri ve transitions - Hata mesajları ve stack trace’ler - Retry attempt’leri ve sonuçları

Monitoring Metrikleri: - API response süreleri - Başarı/başarısızlık oranları - Durum 2 alma oranları (kalite metrigi) - Alıcıya iletim başarısızlık oranları - Ortalama fatura işlenme süresi

Transaction Yönetimi

E-fatura entegrasyonunda distributed transaction yönetimi dikkat gerektirir:

1.          Yerel ERP sisteminde fatura kaydı oluşturulur

2.          E-fatura API’sine gönderim yapılır

3.          belgeOid alınır ve yerel kayda mapping yapılır

4.          Durum kontrolü yapılır

Bu süreçte herhangi bir adımda hata oluşursa: - Yerel kayıt ile API durumu senkronize tutulmalı - Orphan record’lar (API’de var ama yerel sistemde yok veya tersi) tespit edilmeli - Reconciliation job’ları periyodik olarak çalıştırılmalı

Entegrasyon Kod Örnekleri ve İmplementation Detayları

C# .NET Entegrasyonu

QNB eSolutions dokümantasyonunda C# için örnek kod yapısı sunulmaktadır:

Authentication ve Service Client Oluşturma:

// Service client oluşturma
var service = new EFaturaServiceClient();

// Cookie Container ile session yönetimi
var cookies = new CookieContainer();
service.CookieContainer = cookies;

// Login işlemi
var loginResponse = service.wsLogin(userId, password, "tr");

// MD5 hash hesaplama (belgeHash için)
using (var md5 = MD5CryptoServiceProvider.Create())
{
    byte[] inputBytes = Encoding.UTF8.GetBytes(xmlContent);
    byte[] hashBytes = md5.ComputeHash(inputBytes);
    string hash = BitConverter.ToString(hashBytes).Replace("-", "").ToLower();
}

Fatura Gönderimi:

// XML içeriğini Base64'e encode etme
byte[] xmlBytes = Encoding.UTF8.GetBytes(xmlContent);
string base64Xml = Convert.ToBase64String(xmlBytes);

// belgeGonderExt çağrısı
var response = service.belgeGonderExt(
    vergiTcKimlikNo: "YOUR_VKN",
    belgeTuru: "FATURA_UBL",
    belgeNo: "FTR2024000001",
    veri: base64Xml,
    belgeHash: hash,
    mimeType: "application/xml",
    belgeVersiyon: "1.0"
);

string belgeOid = response.belgeOid;

Java Entegrasyonu

Java için SOAP client oluşturma ve authentication:
// Service endpoint URL
String endpointUrl = "https://api.qnbesolutions.com.tr/...";

// Service proxy oluşturma
EFaturaService service = new EFaturaService();
EFaturaServiceSoap port = service.getEFaturaServiceSoap();

// Endpoint adresini set etme
BindingProvider bp = (BindingProvider) port;
bp.getRequestContext().put(
    BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
    endpointUrl
);

// SOAP Handler ile authentication
bp.getBinding().setHandlerChain(
    Arrays.asList(new AuthenticationHandler(username, password))
);

// Cookie yönetimi için CookieManager
CookieManager cookieManager = new CookieManager();
CookieHandler.setDefault(cookieManager);
SOAP Handler Implementation:
public class AuthenticationHandler implements SOAPHandler<SOAPMessageContext> {
    private String username;
    private String password;

    @Override
    public boolean handleMessage(SOAPMessageContext context) {
        Boolean outbound = (Boolean) context.get(
            MessageContext.MESSAGE_OUTBOUND_PROPERTY
        );

        if (outbound) {
            try {
                SOAPEnvelope envelope = context.getMessage()
                    .getSOAPPart().getEnvelope();
                SOAPHeader header = envelope.getHeader();

                // WSSE Security header ekleme
                addSecurityHeader(header, username, password);
            } catch (SOAPException e) {
                throw new RuntimeException(e);
            }
        }
        return true;
    }
}

Python Entegrasyonu

Python ile SOAP entegrasyonu için zeep kütüphanesi kullanılabilir:

from zeep import Client
from zeep.wsse.username import UsernameToken
import base64
import hashlib

# WSDL URL
wsdl_url = 'https://api.qnbesolutions.com.tr/...?wsdl'

# Client oluşturma (WSSE authentication ile)
client = Client(
    wsdl_url,
    wsse=UsernameToken(username, password)
)

# XML içeriğini Base64'e encode etme
xml_content = """<Invoice>...</Invoice>"""
base64_xml = base64.b64encode(xml_content.encode('utf-8')).decode('utf-8')

# MD5 hash hesaplama
md5_hash = hashlib.md5(xml_content.encode('utf-8')).hexdigest()

# Fatura gönderimi
response = client.service.belgeGonderExt(
    vergiTcKimlikNo='YOUR_VKN',
    belgeTuru='FATURA_UBL',
    belgeNo='FTR2024000001',
    veri=base64_xml,
    belgeHash=md5_hash,
    mimeType='application/xml',
    belgeVersiyon='1.0'
)

belge_oid = response['belgeOid']

Asenkron İşlem Yönetimi için Örnek Akış

import time
from typing import Dict, List

class EFaturaManager:
    def __init__(self, client):
        self.client = client
        self.pending_invoices: Dict[str, str] = {}  # belgeOid -> yerel_no

    def send_invoice(self, xml_content: str, local_invoice_no: str) -> str:
        """Fatura gönder ve tracking başlat"""
        # Base64 encoding ve hash
        base64_xml = base64.b64encode(xml_content.encode()).decode()
        md5_hash = hashlib.md5(xml_content.encode()).hexdigest()

        # API çağrısı
        response = self.client.service.belgeGonderExt(
            # ... parametreler
        )

        belge_oid = response['belgeOid']
        self.pending_invoices[belge_oid] = local_invoice_no

        return belge_oid

    def check_processing_status(self, belge_oid: str) -> Dict:
        """İşlenme durumunu kontrol et"""
        response = self.client.service.gidenBelgeDurumSorgulaExt(
            belgeNo=belge_oid,
            belgeTuru='FATURA'
        )

        return {
            'durum_kodu': response['durumKodu'],
            'aciklama': response['aciklama'],
            'belge_oid': belge_oid
        }

    def monitor_pending_invoices(self):
        """Bekleyen faturaları sürekli kontrol et"""
        completed = []

        for belge_oid in self.pending_invoices.keys():
            status = self.check_processing_status(belge_oid)

            if status['durum_kodu'] == 3:  # İşlendi
                print(f"Fatura işlendi: {belge_oid}")
                completed.append(belge_oid)
                # Veritabanını güncelle, tracking başlat

            elif status['durum_kodu'] == 2:  # Hata
                print(f"Fatura hatası: {belge_oid} - {status['aciklama']}")
                # Hata yönetimi, notification gönder
                completed.append(belge_oid)

        # Tamamlananları listeden çıkar
        for belge_oid in completed:
            del self.pending_invoices[belge_oid]

Performans Optimizasyonu ve Ölçeklendirme Stratejileri

Yüksek hacimli e-fatura operasyonlarında performans optimizasyonu kritik önem taşır.

Batch Processing

Toplu fatura gönderimlerinde: - Faturaları gruplar halinde işleyin (örn: 50’şer) - Her grup için parallel processing uygulayın - Rate limiting’e dikkat edin (API limitleri varsa) - Circuit breaker pattern ile API hatalarını yönetin

Caching Stratejileri

Mükellef Bilgisi Caching: - efaturaKullaniciBilgisi sonuçlarını 24 saat cache’leyin - Redis veya Memcached kullanın - Cache invalidation stratejisi belirleyin

Kayıtlı Kullanıcı Listesi: - 4 saatte bir güncelleyin (sistem periyodu ile senkron) - In-memory veya disk bazlı storage kullanın - Startup’ta ilk yükleme yapın

Database İndexleme

Entegrasyon veritabanında kritik indexler: - belgeOid (primary index, unique) - yerel_fatura_no (business key) - durum_kodu (filtering için) - olusturma_tarihi (range query için) - vergi_no + fatura_tarihi (composite index)

Asenkron Queue Yönetimi

Message queue (RabbitMQ, Kafka, SQS) kullanarak: - Fatura gönderim işlemlerini queue’ya alın - Worker process’ler ile parallel işleme - Failed message için Dead Letter Queue - Retry logic ile fault tolerance

Güvenlik Best Practices

Credential Yönetimi

•             API credentials’ları environment variable’larda saklayın

•             Secret management tool’ları kullanın (Azure Key Vault, AWS Secrets Manager)

•             Kodda hardcoded credential asla bulunmamalı

•             Credential rotation policy uygulayın

Veri Güvenliği

•             HTTPS zorunlu kullanılmalı

•             XML içerisinde hassas veriler (kredi kartı, şifre) bulunmamalı

•             Loglar içerisinde PII (Personally Identifiable Information) maskelenmelidir

•             Veritabanı encryption at rest uygulanmalı

API Security

•             Rate limiting implement edin

•             IP whitelisting kullanın (mümkünse)

•             API çağrılarını audit log’layın

•             Anomaly detection ile şüpheli aktiviteleri tespit edin

Sonuç ve Öneriler

E-fatura entegrasyonu, teknik karmaşıklık içeren ancak doğru yaklaşımlarla başarılı şekilde gerçekleştirilebilecek bir süreçtir. QNB eSolutions API’si, SOAP tabanlı yapısı ve kapsamlı metodları ile güçlü bir entegrasyon altyapısı sunar.

Başarılı Entegrasyon için Kontrol Listesi

1.          Planlama Aşaması:

–            İş süreçlerini haritalayın

–            E-fatura ve e-arşiv senaryolarını belirleyin

–            Geçmiş fatura datası migrasyon stratejisi

–            Exception handling senaryoları

2.          Development Aşaması:

–            Test environment’ta başlayın

–            Unit test coverage > %80 hedefleyin

–            Integration testleri otomatize edin

–            Logging framework’ünü kurun

3.          Test Aşaması:

–            Pozitif ve negatif test senaryoları

–            Yük testi (özellikle ay sonu faturaları için)

–            Failover ve recovery testleri

–            End-to-end business flow validation

4.          Production Aşaması:

–            Phased rollout stratejisi

–            Monitoring dashboard’ları kurun

–            Alert mekanizmaları tanımlayın

–            Incident response planı hazırlayın

–            Documentation ve knowledge base

5.          Operasyonel Süreç:

–            Daily reconciliation job’ları

–            Weekly performance review

–            Monthly API usage analysis

–            Continuous improvement cycle

İleri Seviye Konular

Machine Learning Entegrasyonu: - OCR ile kağıt faturaların e-faturaya dönüşümü - Fatura tutarsızlıklarının otomatik tespiti - Fraud detection algoritmaları - Predictive analytics ile nakit akışı tahmini

Microservices Architecture: - E-fatura servisini bağımsız microservice olarak tasarlama - Event-driven architecture ile loosely coupled sistemler - Service mesh ile inter-service communication - Kubernetes ile container orchestration

Regulatory Compliance: - KVKK uyumluluk gereksinimleri - Veri saklama süreleri ve arşivleme - Audit trail gereksinimleri - Yasal raporlama yükümlülükleri

E-fatura entegrasyonu, dijital dönüşüm yolculuğunuzun önemli bir adımıdır. Doğru teknik altyapı, kapsamlı test stratejisi ve sürekli monitoring ile bu süreci başarıyla tamamlayabilir, işletmenize operasyonel verimlilik ve maliyet tasarrufu kazandırabilirsiniz.

e-İrsaliye Entegrasyonu: Lojistik Süreçlerin Dijitalleşmesi

e-İrsaliye, e-fatura ile benzer yapıda çalışan ancak mal hareketlerinin elektronik ortamda belgelenmesini sağlayan bir sistemdir. QNB eSolutions API’si, e-irsaliye işlemlerini de kapsamlı şekilde destekler.

e-İrsaliye ve E-Fatura Arasındaki Teknik Farklar

e-İrsaliye entegrasyonu, e-fatura ile aynı metodları kullanır ancak bazı parametreler farklıdır:

belgeTuru Değerleri:

• e-Fatura için: “FATURA_UBL” 
• e-İrsaliye için: “IRSALIYE_UBL”
• İrsaliye yanıtları için: “IRSALIYE_YANITI_UBL”

belgeVersiyon: - E-fatura: “1.0” - E-irsaliye: “1.2”

Bu versiyon farkı, e-irsaliye UBL şemasının daha güncel bir standartta olmasından kaynaklanır.

e-İrsaliye Gönderimi

e-İrsaliye göndermek için aynı belgeGonderExt metodu kullanılır, ancak parametreler e-irsaliye’ye özgü olarak ayarlanır:

belgeGonderExt(
    vergiTcKimlikNo: "YOUR_VKN",
    belgeTuru: "IRSALIYE_UBL",
    belgeNo: "IRS2024000001",
    veri: base64_encoded_xml,
    belgeHash: md5_hash,
    mimeType: "application/xml",
    belgeVersiyon: "1.2"
)

e-İrsaliye Mükellefi Sorgulama

e-İrsaliye sistemine kayıtlı kullanıcıları sorgulamak için eIrsaliyeKullanicisi metodu kullanılır. Bu metot, efaturaKullaniciBilgisi ile aynı şekilde çalışır ancak e-irsaliye mükelleflerini sorgular.

Önemli Not: Bir firma hem e-fatura hem de e-irsaliye mükellefi olabilir veya sadece birinde kayıtlı olabilir. Bu nedenle her iki sisteme kayıt durumunu ayrı ayrı kontrol etmek gerekebilir.

Gelen e-İrsaliyeleri Listeleme

Gelen e-İrsaliyeleri listelemek için gelenBelgeleriListeleExt metodu kullanılır ve belgeTuru parametresi “IRSALIYE” olarak set edilir:

gelenBelgeleriListeleExt(
    vergiTcKimlikNo: "YOUR_VKN",
    sonAlinanBelgeSiraNumarasi: 0,
    belgeTuru: "IRSALIYE"
)

e-İrsaliye Görüntüleme Linkleri

e-İrsaliye görüntüleme linkleri doğrudan API metodları tarafından üretilmemektedir. Bu konuda ihtiyacınız varsa proje@destek.qnbesolutions.com.tr adresine başvurunuz.

e-Defter Entegrasyonu: Muhasebe Defterlerinin Elektronik Ortamda Tutulması

e-Defter, muhasebe defterlerinin (yevmiye, kebir, envanter) elektronik ortamda tutulmasını ve GİB’e raporlanmasını sağlayan bir sistemdir. QNB eSolutions, e-defter işlemleri için üç aşamalı bir süreç sunar.

Aşama 1: CSV Dosya Yükleme (eDefterCsvFileYukle)

e-Defter verilerinin sisteme yüklenmesi için öncelikle verilerinizi CSV formatında hazırlamanız gerekir.

Metot Parametreleri:

donem: Defter dönemi “yyyyMM” formatında (örn: “202401” - Ocak 2024)

subeKodu: Şube kodu bilgisi

vknTckn: Mükellef vergi kimlik numarası

parameterList: Ek parametreler (dosya türü, defter tipi vb.)

Dosya Adlandırma Kuralı:

Yüklenecek dosyalar şu formatta adlandırılmalıdır:

VKN_Subekodu_Donem_ParcaNumarasi.zip

Örnek: XXXXXXXXXXXX_MERKEZ_202401_001.zip

Performans Optimizasyonu:

Dokümantasyonda belirtildiği üzere: “CSV satır sınırı: 20.000 (hızlı işlem için)”. Bu, büyük veri setlerini 20.000 satırlık parçalara bölerek göndermek gerektiği anlamına gelir. Bu yaklaşım, hem upload performansını optimize eder hem de hata durumunda sadece problemli parçanın yeniden gönderilmesini sağlar.

Aşama 2: Durum Sorgulama (eDefterCsvDurumSorgula)

Dosya yüklendikten sonra, işlenme durumunu kontrol etmek için bu metot kullanılır.

Parametreler:

donem: Sorgulanacak dönem (yyyyMM)

vknTckn: Mükellef kimlik numarası

yuklenenDefterTuru: “CSV” veya “XML”

Response Bilgileri:

durumAciklama: İşlem durumuna ait açıklayıcı metin

durumKodu: Numerik durum kodu

hataDosya: Eğer validasyon hataları varsa, hataların detaylarını içeren dosya Base64 formatında döner. Bu dosya decode edilerek hata raporuna ulaşılabilir.

Aşama 3: İşlem Başlatma (eDefterCsvDosyaIsle)

Tüm parçalar başarıyla yüklendikten sonra, şematron kontrolü ve imzalama işlemini başlatmak için bu metot çağrılır.

Kritik Bilgi: Dokümantasyonda belirtildiği üzere: “İmzalama sürecinin sistemimiz tarafından yapılması, operasyonel olarak tüm süreçlerinizi kısaltacaktır.”

Bu metot çağrıldığında: 1. Tüm CSV dosyaları birleştirilerek XML formatına dönüştürülür 2. Şematron kontrolleri yapılır 3. E-imza işlemi otomatik olarak gerçekleştirilir 4. GİB’e gönderim yapılır

e-Defter İşlem Akışı Örneği

# 1. Dönem verilerini 20.000'lik parçalara böl
parts = split_csv_data(data, 20000)

# 2. Her parçayı yükle
for index, part in enumerate(parts, start=1):
    zip_filename = f"{vkn}_{sube}_{donem}_{index:03d}.zip"
    create_zip(part, zip_filename)

    response = client.service.eDefterCsvFileYukle(
        donem=donem,
        subeKodu=sube,
        vknTckn=vkn,
        parameterList=params
    )
    print(f"Parça {index} yüklendi")

# 3. Tüm parçaların durumunu kontrol et
status = client.service.eDefterCsvDurumSorgula(
    donem=donem,
    vknTckn=vkn,
    yuklenenDefterTuru="CSV"
)

# 4. Eğer hata yoksa işleme başlat
if status['durumKodu'] == SUCCESS:
    process_response = client.service.eDefterCsvDosyaIsle(
        donem=donem,
        vknTckn=vkn
    )

Belge Yeniden Gönderme Metodları: Hata Düzeltme ve İyileştirme

Bazı durumlarda, daha önce gönderilen belgelerin yeniden gönderilmesi gerekebilir. QNB eSolutions, bu amaçla üç farklı metot sunar.

belgeleriTekrarGonder

Genel amaçlı yeniden gönderim metodu. Belirli kriterlere uyan belgeleri toplu olarak yeniden gönderir.

Kullanım Senaryoları: - Geçici sistem sorunları nedeniyle gönderilememiş belgeler - Alıcı sisteminde yaşanan sorunlar sonrası yeniden iletim - Toplu yeniden gönderim gereksinimleri

belgeleriTekrarGonderBelgeOid

Belirli bir belgeOid değerine sahip belgenin yeniden gönderilmesi için kullanılır.

Avantajları: - Spesifik belge kontrolü - Hata takibi kolaylığı - Daha güvenli (yanlış belge gönderimi riski yok)

belgeleriTekrarGonderYerelBelgeNo

Yerel sisteminizdeki belge numarası ile yeniden gönderim yapmanızı sağlar.

Kullanım Durumu: - Yerel ERP sisteminizde belgeOid mapping’i kaybolmuşsa - Batch işlemlerde yerel numaralar ile çalışırken - Reconciliation süreçlerinde

Best Practice: belgeOid kullanımı tercih edilmelidir çünkü bu, sistemde unique identifier olarak garanti edilir. Yerel belge numaraları farklı dönemlerde tekrar edebilir.

ETTN ile Sorgulama: Doğrudan Belge Erişimi

ETTN (Elektronik Transfer Tanımlama Numarası), her e-faturanın global olarak benzersiz tanımlayıcısıdır. UUID formatında 36 karakterlik bir string’dir.

ETTN Kullanım Avantajları

•             Sistemler arası standart referans

•             Müşteri iletişiminde kullanım kolaylığı

•             Portal ve API arasında tutarlı referans

•             Global uniqueness garantisi

ETTN ile Sorgulama Kısıtlaması

Dokümantasyonda önemli bir not: “ETTN ile sorgulama sadece ‘İşlendi’ durumundaki belgeler için geçerli”

Bu, ETTN’nin ancak belge tam olarak işlendikten sonra atandığı anlamına gelir. İşleme kuyruğundaki veya hata almış belgeler için ETTN henüz mevcut olmayabilir. Bu nedenle:

1.          İlk sorgularda belgeOid kullanın

2.          Belge “İşlendi” durumuna geçtikten sonra ETTN’yi kaydedin

3.          Sonraki sorgularda ETTN kullanabilirsiniz

Uygulama Yanıtları: İki Yönlü İletişim

E-fatura sisteminde, alıcı taraf gelen faturaya yanıt gönderebilir. Bu yanıtlar, faturanın kabul/red durumunu ve varsa açıklamaları içerir.

Uygulama Yanıtı Tipleri

Kabul (KABUL): Fatura alıcı tarafından onaylandı Red (RED): Fatura reddedildi, red gerekçesi eklenir İade (IADE): Mal iadesi durumu İtiraz (ITIRAZ): Fatura tutarı veya içeriğine itiraz

Gelen Uygulama Yanıtlarını Çekme

gelenBelgeleriListeleExt(
    vergiTcKimlikNo: "YOUR_VKN",
    sonAlinanBelgeSiraNumarasi: 0,
    belgeTuru: "UYGULAMA_YANITI"
)

Bu çağrı, size gönderilen faturalara karşı taraftan gelen yanıtları getirir.

Uygulama Yanıtı Gönderme

Alınan bir faturaya yanıt göndermek için yine belgeGonderExt metodu kullanılır, ancak belgeTuru “UYGULAMA_YANITI_UBL” olarak ayarlanır.

Önemli: Yanıt UBL XML’i, orijinal fatura ETTN’sini referans almalı ve standartta belirtilen ApplicationResponse formatında hazırlanmalıdır.

Troubleshooting: Yaygın Sorunlar ve Çözümleri

Sorun 1: “Connection Timeout” Hatası

Belirti: API çağrısı timeout veriyor ve yanıt gelmiyor

Olası Nedenler:

• Firewall/proxy kuralları API endpoint’ini engelliyor 
• Network latency çok yüksek
• API sunucusu geçici olarak yavaş

Çözüm:

1. Firewall loglarını kontrol edin
2. Timeout değerini artırın (örn: 30 saniye -> 60 saniye)
3. Retry mekanizması implement edin
4. Network connectivity test edin (ping, traceroute)

Sorun 2: “Authentication Failed” Hatası

Belirti: Her API çağrısında authentication hatası

Olası Nedenler: - Yanlış credentials - Credential’lar expire olmuş - SOAP Header yanlış formatlanmış - Cookie session timeout

Çözüm:

1. Credentials’ları doğrulayın (copy-paste hatalarına dikkat)
2. WSSE header formatını kontrol edin
3. Cookie-based auth kullanıyorsanız session’ı yenileyin
4. Test ortamı credentials’larını production’da kullanmamaya dikkat edin

Sorun 3: Durum Kodu 2 (İşleme Hatası) Sürekli Alınıyor

Belirti: Gönderilen tüm faturalar işleme hatası veriyor

Olası Nedenler: - XML şema validasyonu başarısız - Zorunlu alanlar eksik - KDV hesaplaması yanlış - Format hataları (tarih, tutar vb.)

Çözüm:

1. Response’taki “aciklama” alanını detaylı inceleyin
2. XML’i offline XSD validator ile kontrol edin
3. Örnek valid XML ile karşılaştırın
4. Matematiksel hesaplamaları double-check edin
5. Tarih formatlarını kontrol edin (yyyy-MM-dd)

Sorun 4: Gelen Faturalar Çekilemiyor

Belirti: gelenBelgeleriListeleExt boş liste döndürüyor

Olası Nedenler: - Yanlış vergiTcKimlikNo kullanılıyor - belgeTuru parametresi yanlış - sonAlinanBelgeSiraNumarasi çok yüksek - Gerçekten gelen fatura yok

Çözüm:

1. Portal üzerinden gelen faturaları kontrol edin
2. sonAlinanBelgeSiraNumarasi’ni 0’dan başlatın
3. belgeTuru parametresini kontrol edin
4. Tarih filtrelerini kaldırıp genel sorgulama yapın

Sorun 5: Base64 Decode Hatası

Belirti: İndirilen belgeleri decode ederken hata

Olası Nedenler:

• Base64 string corrupted 
• Encoding charset uyumsuzluğu
• Padding karakterleri eksik

Çözüm:

import base64

# Doğru decode yöntemi
try:
    decoded = base64.b64decode(response_data)
    with open('output.zip', 'wb') as f:
        f.write(decoded)
except Exception as e:
    print(f"Decode hatası: {e}")
    # Padding kontrolü
    missing_padding = len(response_data) % 4
    if missing_padding:
        response_data += '=' * (4 - missing_padding)
        decoded = base64.b64decode(response_data)

Gelişmiş Entegrasyon Senaryoları

Senaryo 1: Multi-Tenant SaaS Uygulaması

Birden fazla müşteriyi aynı uygulama üzerinden yöneten SaaS sistemlerde:

Mimari Yaklaşım:

• Her tenant için ayrı credentials kullanın
• Connection pool yönetimi ile paralel işlem
• Tenant-based rate limiting - Isolated error handling ve logging

Kod Örneği:

class MultiTenantEFaturaManager:
    def __init__(self):
        self.tenant_clients = {}

    def get_client(self, tenant_id):
        if tenant_id not in self.tenant_clients:
            credentials = get_tenant_credentials(tenant_id)
            self.tenant_clients[tenant_id] = create_soap_client(credentials)
        return self.tenant_clients[tenant_id]

    def send_invoice(self, tenant_id, invoice_data):
        client = self.get_client(tenant_id)
        return client.service.belgeGonderExt(**invoice_data)

Senaryo 2: Event-Driven Architecture

Microservices mimarisinde event-based entegrasyon:

Akış: 1. ERP sistemi “invoice.created” event’i publish eder 2. E-fatura service event’i consume eder 3. API’ye gönderim yapar 4. “invoice.sent” event’i publish eder 5. Monitoring service durumu takip eder 6. Durum değişikliklerinde notification gönderir

Avantajlar: - Loose coupling - Scalability - Fault tolerance - Audit trail

Senaryo 3: Hybrid Entegrasyon (Batch + Real-time)

Kritik faturalar için real-time, diğerleri için batch processing:

Strateji:

def process_invoice(invoice):
    if invoice.is_critical:
        # Immediate processing
        send_immediately(invoice)
        monitor_status_sync(invoice)
    else:
        # Batch queue
        add_to_batch_queue(invoice)

# Scheduled job (her saat)
def process_batch():
    invoices = get_queued_invoices(limit=100)
    parallel_send(invoices)

Sonuç: Başarılı E-Fatura Entegrasyonu için Son Öneriler

E-fatura entegrasyonu, teknik bir süreç olmanın ötesinde, işletmenizin dijital dönüşüm stratejisinin kritik bir bileşenidir. QNB eSolutions API’si ile bu süreci başarıyla tamamlamak için:

Teknik Hazırlık

1.          Test ortamında kapsamlı PoC (Proof of Concept) çalışması yapın

2.          Tüm edge case’leri test edin (ağ kesintisi, timeout, veri bütünlüğü)

3.          Performans testleri yapın (özellikle ay sonu yoğunluğu için)

4.          Disaster recovery planı hazırlayın

Operasyonel Hazırlık

1.          İç ekipleri eğitin (muhasebe, IT, müşteri hizmetleri)

2.          Runbook hazırlayın (yaygın sorunlar ve çözümleri)

3.          Escalation policy tanımlayın

4.          SLA hedeflerinizi belirleyin

İş Süreci Optimizasyonu

1.          Manuel süreçleri minimize edin

2.          Exception handling’i otomatize edin

3.          Dashboard ve raporlama araçlarını kurun

4.          Sürekli iyileştirme döngüsü oluşturun

Bu kapsamlı rehber, QNB eSolutions e-fatura API entegrasyonunuz için sağlam bir temel oluşturacaktır. Her işletmenin ihtiyaçları farklı olduğundan, bu rehberdeki bilgileri kendi özel gereksinimlerinize göre adapte etmeniz önemlidir.

Başarılı e-Fatura Entegrasyonu için Son Öneriler

e-Fatura entegrasyonu, teknik bir süreç olmanın ötesinde, işletmenizin dijital dönüşüm stratejisinin kritik bir bileşenidir. QNB eSolutions API’si ile bu süreci başarıyla tamamlamak için:

Teknik Hazırlık
1.    Test ortamında kapsamlı PoC (Proof of Concept) çalışması yapın
2.    Tüm edge case’leri test edin (ağ kesintisi, timeout, veri bütünlüğü)
3.    Performans testleri yapın (özellikle ay sonu yoğunluğu için)
4.    Disaster recovery planı hazırlayın

Operasyonel Hazırlık
1.    İç ekipleri eğitin (muhasebe, IT, müşteri hizmetleri)
2.    Runbook hazırlayın (yaygın sorunlar ve çözümleri)
3.    Escalation policy tanımlayın
4.    SLA hedeflerinizi belirleyin

İş Süreci Optimizasyonu
1.    Manuel süreçleri minimize edin
2.    Exception handling’i otomatize edin
3.    Dashboard ve raporlama araçlarını kurun
4.    Sürekli iyileştirme döngüsü oluşturun

Bu kapsamlı rehber, QNB eSolutions e-fatura API entegrasyonunuz için sağlam bir temel oluşturacaktır. Her işletmenin ihtiyaçları farklı olduğundan, bu rehberdeki bilgileri kendi özel gereksinimlerinize göre adapte etmeniz önemlidir.

Başarılı bir e-fatura entegrasyonu, sadece teknik bir başarı değil, aynı zamanda operasyonel mükemmellik ve müşteri memnuniyeti için önemli bir adımdır. Bu yolculukta başarılar dileriz!

Sıkça Sorulan Sorular (SSS)

Teknik Sorular

S: SOAP yerine REST API desteği var mı?

C: QNB eSolutions API’si şu an SOAP tabanlı çalışmaktadır. REST desteği için lütfen teknik destek ile iletişime geçin.

S: Test ortamı mevcut mu?

C: Evet, production ortamına geçmeden önce test/sandbox ortamında entegrasyon testlerinizi yapmalısınız. Test ortamı endpoint bilgilerini teknik destek ekibinden alabilirsiniz.

S: Maksimum dosya boyutu limiti nedir?

C: XML belgeler için tavsiye edilen maksimum boyut 5MB’tır. Daha büyük belgeler için lütfen dokümantasyonu kontrol edin veya destek alın.

S: API rate limiting var mı?

C: API kullanım limitleri hesabınıza özel olarak belirlenebilir. Yüksek hacimli işlemler için özel kota talep edebilirsiniz.

İşlevsel Sorular

S: Bir faturayı hem e-fatura hem e-arşiv olarak gönderebilir miyim?

C: Hayır. Alıcı e-fatura mükellefi ise e-fatura, değilse e-arşiv olarak gönderilmelidir. Bu kontrol efaturaKullaniciBilgisi metodu ile yapılır.

S: Geçmişe dönük fatura düzenlenebilir mi?

C: Evet, ancak alıcının e-fatura kayıt tarihinden önce bir tarihli fatura düzenlenecekse, bu e-arşiv olarak düzenlenmelidir.

S: İptal edilen fatura tekrar gönderilebilir mi?

C: Hayır, iptal edilmiş bir fatura yeniden gönderilemez. Yeni bir fatura oluşturulması gerekir.

S: Alıcıya ulaşmayan fatura ne olur?

C: Sistem 5 deneme yapar. 5 deneme sonrası başarısız olursa (durum kodu 1215), manuel müdahale gerekir.

Güvenlik Soruları

S: API credentials ne sıklıkla değiştirilmeli?

C: En az 3 ayda bir credential rotation yapılması güvenlik best practice’i olarak önerilir.

S: SSL/TLS zorunlu mu?

C: Evet, tüm API çağrıları HTTPS üzerinden yapılmalıdır. HTTP desteklenmez.

S: İki faktörlü authentication desteği var mı?

C: API seviyesinde 2FA yoktur ancak portal erişimi için 2FA aktif edilebilir.