e-Fatura WebSocket Çalışmıyor: GİB İmzalama Aracı Çözüm Rehberi
e-Fatura WebSocket bağlantısı veya GİB İmzalama Aracı çalışmıyorsa mali mühür sürücüsü, Windows bileşenleri, tarayıcı, güvenlik yazılımı ve logları hangi sırayla kontrol etmeniz gerektiğini öğrenin.
e-Fatura WebSocket Hatası Ne Anlama Gelir?
e-Fatura Portalı, e-Arşiv Portalı veya e-Fatura İptal/İtiraz ekranında mali mühürle işlem yapılırken tarayıcı ile bilgisayarda çalışan imzalama uygulaması arasında yerel bir bağlantı kurulur. Kullanıcının gördüğü “WebSocket çalışmıyor”, “imzalama aracına ulaşılamadı”, “sertifika bulunamadı” veya imzalama penceresinin hiç açılmaması gibi belirtiler çoğu zaman faturanın kendisinden değil bu yerel iletişim zincirinden kaynaklanır.
Bu zincirde tarayıcı, GİB İmzalama Aracı, akıllı kart sürücüsü, mali mühür cihazı, Windows bileşenleri ve güvenlik yazılımları birlikte çalışır. Bu nedenle yalnızca Java kurup kaldırmak her bilgisayarda doğru çözüm değildir. Güncel yaklaşım, önce GİB’in Java gerektirmeyen resmi İmzalama Aracı’nı ve onun gereksinimlerini kontrol etmektir.
Hızlı Çözüm Sırası
İşleme başlamadan önce açık belgelerinizi kaydedin. GİB’in resmi kurulumunun bazı eksik bileşenleri yüklemesi ve bilgisayarı yeniden başlatması gerekebilir.
- Mali mühür veya e-imza cihazının Windows tarafından görüldüğünü doğrulayın.
- GİB İmzalama Aracı’nı masaüstü simgesinden çalıştırın ve işlem boyunca kapatmayın.
- Doğru e-Belge portalını İmzalama Aracı’nın açtığı tarayıcı sekmesinden deneyin.
- KamuSM akıllı kart sürücüsünü, Visual C++ Redistributable paketlerini ve .NET Framework sürümünü kontrol edin.
- Tarayıcıyı, İmzalama Aracı’nı ve bilgisayarı yeniden başlatın.
- Sorun sürüyorsa İmzalama Aracı içinden log klasörünü açarak hatanın hangi aşamada oluştuğunu belirleyin.
- Eski Java Web Start yöntemini kullanmak yerine GİB’in güncel, Java gerektirmeyen aracını resmi adresten yeniden kurun.
1. Mali Mühür ve Akıllı Kart Sürücüsünü Kontrol Edin
WebSocket uyarısı ekranda görünse de asıl sorun mali mühür sürücüsü olabilir. USB cihazı takıldığında Windows Aygıt Yöneticisi’nde tanınmayan cihaz uyarısı bulunmamalıdır. Kart yönetim yazılımı açılmalı ve sertifika görülebilmelidir.
GİB’in İmzalama Aracı Kullanım Kılavuzu, kurulum öncesinde KamuSM Sürücü 6.4.1 veya sonraki bir sürümün bulunmasını ister. Kullanılan mali mühür farklı bir elektronik sertifika hizmet sağlayıcısına aitse yalnızca o sağlayıcının resmi sürücüsü tercih edilmelidir. İnternette bulunan rastgele sürücü paketleri mali mühür güvenliği açısından kullanılmamalıdır.
Aynı bilgisayarda eski ve yeni birden fazla kart sürücüsünün birlikte bulunması da sertifika seçimini bozabilir. Böyle bir durumda kaldırma ve yeniden kurma işlemi yapılmadan önce mevcut sürücü adı ile sürümü kaydedilmelidir.
2. GİB İmzalama Aracı’nın Açık Olduğundan Emin Olun
Kurulum tamamlandıktan sonra masaüstüne gelen GİB İmzalama Aracı simgesi çalıştırılmalıdır. Araç açıldığında kendi menüsü görünür ve desteklenen e-Belge uygulamalarını tarayıcıda sekmeler hâlinde açabilir. GİB kılavuzuna göre uygulama, imza işlemi tamamlanıncaya kadar kapatılmamalıdır.
İmzalama Aracı açık görünmesine rağmen portal bağlantı kuramıyorsa uygulamayı tamamen kapatıp yeniden açın. Görev Yöneticisi’nde aynı uygulamaya ait birden fazla takılı kalmış süreç varsa Windows’u yeniden başlatmak, süreçleri tek tek sonlandırmaktan daha güvenli bir başlangıçtır.
3. Gerekli Windows Bileşenlerini Doğrulayın
GİB’in resmi kılavuzu İmzalama Aracı için Visual C++ Redistributable kütüphaneleri ile .NET Framework 4.7.2 veya üstünü gerekli bileşenler arasında sayar. Windows Update’in uzun süredir kapalı olması, bozuk sistem dosyaları veya eksik çalışma zamanı paketleri uygulamanın açılıyor gibi görünmesine rağmen yerel servisi başlatamamasına yol açabilir.
Kontrol sırasında şu noktaları kaydedin:
- Windows sürümü ve sistem mimarisi: 64 bit veya 32 bit.
- GİB İmzalama Aracı sürümü ve kurulum tarihi.
- Akıllı kart sürücüsünün adı ve sürümü.
- .NET Framework ve Visual C++ paketlerinin kurulu durumu.
- Hatanın tüm tarayıcılarda mı yoksa yalnızca bir tarayıcıda mı oluştuğu.
Eksik bileşenleri yalnızca Microsoft ve ilgili kurumun resmi indirme sayfalarından yükleyin.
4. Tarayıcı ile Yerel Bağlantıyı Kontrol Edin
WebSocket bağlantısı internet üzerindeki başka bir sunucuya değil, çoğunlukla bilgisayarınızda çalışan yerel imzalama bileşenine ulaşır. Bu nedenle internet açık olsa bile bağlantı kurulamayabilir.
Tarayıcıyı tamamen kapatıp GİB İmzalama Aracı üzerinden tekrar açmayı deneyin. Gizli pencere, katı güvenlik uzantıları, reklam engelleyiciler veya kurumsal tarayıcı politikaları yerel bağlantıyı engelleyebilir. Test sırasında uzantıları kalıcı olarak kaldırmak yerine kontrollü bir tarayıcı profiliyle karşılaştırma yapın.
Tarayıcının önbelleğini temizlemek bazen eski portal dosyalarını kaldırır; ancak çerezleri silmeden önce açık e-Belge oturumlarının kapanacağını unutmayın. Sistem tarihi, saati ve saat dilimi de doğru olmalıdır. Yanlış saat, sertifika doğrulaması ve güvenli bağlantı kontrollerinde hata oluşturabilir.
5. Firewall ve Antivirüs Engelini Ayırın
Windows Güvenlik Duvarı, kurumsal firewall politikası veya uç nokta güvenliği yazılımı İmzalama Aracı’nın yerel port dinlemesini engelleyebilir. Güvenlik yazılımını tamamen kapatmak doğru ilk adım değildir. Önce engelleme günlüğü kontrol edilmeli, uygulamanın dosya yolu ve imzası doğrulanmalı, ardından yalnızca gerekli uygulama için kontrollü izin tanımlanmalıdır.
Özellikle merkezi yönetilen şirket bilgisayarlarında kullanıcı kendi başına istisna eklememelidir. BT yöneticisi; uygulama kontrolü, davranış analizi, yerel ağ bağlantısı ve SSL inceleme kayıtlarını birlikte incelemelidir. Kalıcı ve geniş bir güvenlik istisnası yerine en dar kapsamlı kural uygulanmalıdır.
6. GİB İmzalama Aracı’nı Temiz Kurun
Yukarıdaki kontroller sonuç vermiyorsa resmi aracı temiz kurmak gerekir. Açık çalışmalarınızı kaydedin, İmzalama Aracı’nı kapatın ve mevcut sürümü Windows Uygulamalar bölümünden kaldırın. Bilgisayarı yeniden başlattıktan sonra güncel kurulum paketini doğrudan GİB e-Belge sitesinden indirin.
Kurulum paketini açın, setup.exe dosyasını çalıştırın ve kurulum sihirbazındaki adımları tamamlayın. Eksik .NET veya Visual C++ bileşenleri kurulursa bilgisayar otomatik yeniden başlayabilir. Kurulumdan sonra önce mali mühür cihazını kontrol edin, sonra İmzalama Aracı’nı açın ve uygulamanın açtığı portal sekmesinden giriş yapın.
Güvenlik nedeniyle “çalışan eski Java sürümü” adıyla paylaşılan üçüncü taraf paketleri kullanmayın ve Java güncellemelerini kalıcı olarak kapatmayın. Eski bir kurumsal uygulama Java Web Start gerektiriyorsa bu durum, e-Belge sürecinden ayrı olarak kurumun BT sorumlusu tarafından değerlendirilmelidir.
7. Log Kayıtlarıyla Sorunun Aşamasını Bulun
GİB İmzalama Aracı menüsündeki “Log Klasörünü Aç” seçeneği, bilgisayar üzerinde tutulan günlük kayıtlarına ulaşmayı sağlar. Loglarda kişisel veya kurumsal bilgiler bulunabileceğinden dosyaları herkese açık alanlarda paylaşmayın.
Destek talebi açarken şu bilgileri birlikte iletmek çözümü hızlandırır:
- Hatanın görüldüğü tarih ve saat.
- Kullanılan portal: e-Fatura, e-Arşiv, e-Defter veya İptal/İtiraz.
- Windows, tarayıcı, kart sürücüsü ve İmzalama Aracı sürümleri.
- Ekrandaki hata mesajının görüntüsü.
- Hata saatine karşılık gelen log bölümü.
- Sorunun aynı mali mühürle başka bilgisayarda tekrarlanıp tekrarlanmadığı.
Mali mühür PIN kodunu, özel anahtar bilgilerini veya kişisel erişim parolalarını destek kaydına eklemeyin.
e-Fatura Portalında Doğru Giriş Sırası
GİB kılavuzunda e-Fatura Portalı için önce portal adresine girilmesi, “İmzalama aracı desteğiyle giriş” seçeneğinin kullanılması ve elektronik imza ekranında “Başla” düğmesine basılması anlatılır. Ardından uygun akıllı kart işlemcisi seçilir, kart şifresi girilir ve sertifika bilgisi onaylanır.
Taslak faturanın onayında “Onay (İmza Aracıyla)” seçilir. Mali mühür PIN’i yalnızca resmi imza penceresine girilmelidir. İşlem tamamlandığında portal üzerinde dosyanın başarıyla onaylandığını belirten sonuç görülmelidir.
e-Arşiv ve İptal/İtiraz Portalında Dikkat Edilecekler
Aynı araç e-Arşiv, e-Defter, e-Bilet ve e-Fatura İptal/İtiraz işlemlerini de destekler. Ancak her portalın işlem akışı ve adresi farklıdır. Arama sonuçlarından rastgele bir bağlantı açmak yerine GİB’in resmi e-Belge sayfasındaki portal bağlantılarını kullanın.
e-Fatura iptal talebinde fatura numarası ile ödenecek tutar birebir doğru girilmelidir. GİB kılavuzu, hatalı fatura numarası, tutarsız tutar veya daha önce iptal edilmiş bir fatura için hata alınabileceğini belirtir. Bu durum WebSocket arızası değildir; işlem verisi doğrulama hatasıdır.
En Sık Yapılan Yanlışlar
- Sorunun kaynağını görmeden Java’yı tekrar tekrar kurmak.
- Güvenlik yazılımını tamamen kapatıp kalıcı olarak korumasız çalışmak.
- Güncel olmayan veya resmi olmayan kurulum paketleri kullanmak.
- Mali mühür PIN kodunu uzaktan destek mesajında paylaşmak.
- İmzalama Aracı’nı işlem bitmeden kapatmak.
- Farklı portal adreslerini ve eski yer imlerini karıştırmak.
- Saat, sürücü ve Windows bileşenlerini kontrol etmeden tarayıcıyı suçlamak.
Ne Zaman Teknik Destek Alınmalı?
Mali mühür başka bilgisayarda çalışıyor fakat belirli bilgisayarda bağlantı kurulamıyorsa yerel Windows, güvenlik politikası veya çalışma zamanı bileşeni incelenmelidir. Aynı mali mühür hiçbir bilgisayarda görünmüyorsa kart, USB okuyucu, sertifika veya sürücü tarafına öncelik verilmelidir. Birden fazla kullanıcı aynı anda aynı portal hatasını alıyorsa GİB duyuruları ve hizmet durumu kontrol edilmelidir.
DKAVİS teknik destek ekibi; sürücü ve bileşen kontrolü, temiz kurulum, log analizi, tarayıcı ve güvenlik politikası ayrıştırması için uzaktan veya yerinde destek sağlayabilir. Mali mühür şifresi kullanıcı tarafından girilir; şifre destek personeliyle paylaşılmaz.
Sık Sorulan Sorular
e-Fatura WebSocket Hatası İçin Java Kurmak Şart mı?
Güncel GİB İmzalama Aracı Java gerektirmeden çalışacak şekilde sunulmuştur. Eski Java Web Start dosyalarıyla çalışan özel bir yapı bulunmadıkça önce resmi güncel araç tercih edilmelidir.
İmzalama Aracı Açık Ama Portal Görmüyor, Ne Yapmalıyım?
Aracı ve tarayıcıyı kapatıp bilgisayarı yeniden başlatın; uygulamayı tekrar açarak onun yönlendirdiği portal sekmesini kullanın. Devam ederse güvenlik yazılımı kayıtları, Windows bileşenleri ve uygulama logları kontrol edilmelidir.
Mali Mühür Başka Bilgisayarda Çalışıyorsa Sorun Nerededir?
Bu karşılaştırma cihaz ve sertifikanın çalıştığını düşündürür. Sorunlu bilgisayarda sürücü çakışması, eksik .NET veya Visual C++ bileşeni, yerel güvenlik kuralı ya da bozuk İmzalama Aracı kurulumu araştırılmalıdır.
Antivirüsü Kapatmak Güvenli Bir Çözüm müdür?
Hayır. Sorunu ayırmak için bile korumayı kontrolsüz biçimde kapatmak yerine ürünün engelleme günlüğü incelenmeli ve yalnızca doğrulanmış GİB uygulaması için dar kapsamlı izin tanımlanmalıdır.
e-Fatura İptal Ekranındaki Her Hata WebSocket Kaynaklı mıdır?
Hayır. Yanlış fatura numarası, tutar uyuşmazlığı, daha önce oluşturulmuş talep veya portal işlem kuralları da hata oluşturabilir. Önce imza penceresinin açılıp açılmadığı, sonra işlem bilgilerinin doğruluğu ayrıştırılmalıdır.
DKAVİS Teknik Ekibi
Bu rehber, uygulama deneyimi ve ulaşılabilen birincil kaynaklar dikkate alınarak hazırlanmış; anlaşılabilirlik ve teknik tutarlılık açısından kontrol edilmiştir.
Yayın ve güncelleme ilkelerimizi inceleyin →