WooCommerce e-Arşiv entegrasyonu, sipariş verisini bir fatura sağlayıcısına göndermekten daha kapsamlıdır. Siparişin ne zaman faturalaşacağı, alıcının e-Fatura kullanıcısı olup olmadığı, vergi ve adres alanlarının nasıl eşleneceği, başarısız isteklerin nasıl tekrar deneneceği ve oluşan belgenin müşteriye nasıl ulaştırılacağı birlikte planlanmalıdır. Bu kararlar verilmeden kurulan bir eklenti, aynı sipariş için mükerrer belge veya eksik müşteri bilgisi gibi ciddi operasyon sorunları üretebilir.
Bu rehber, WooCommerce ile e-Belge sistemi arasındaki teknik mimariyi ve kontrol noktalarını açıklar. Geçiş zorunluluğu, belge türü, istisnalar ve güncel mali yükümlülükler işletmenin durumuna göre değişebilir. Uygulamadan önce Gelir İdaresi Başkanlığı e-Belge portalındaki güncel tebliğ ve kılavuzları inceleyin; mali müşaviriniz ile kullandığınız yetkili hizmet sağlayıcıdan doğrulama alın. Bu yazı mali veya hukuki danışmanlık değildir.
WooCommerce e-Arşiv entegrasyonu hangi parçalardan oluşur?
Sağlıklı bir entegrasyonda WooCommerce, mali belgenin kendisini üretmeye çalışan tek sistem olmamalıdır. Mağaza sipariş ve müşteri verisinin kaynağıdır; GİB yöntemleri veya yetkili özel entegratör ise belge oluşturma, imzalama, iletme ve mevzuata uygun saklama süreçlerinde rol alır. WordPress eklentisinin görevi iki sistem arasında güvenilir ve izlenebilir bir akış kurmaktır.
GİB dokümanlarında portal, özel entegrasyon ve bilgi işlem sisteminin entegrasyonu gibi yararlanma yöntemleri açıklanır. Küçük ve orta ölçekli WooCommerce mağazalarında genellikle API sunan yetkili bir özel entegratör tercih edilir; fakat sağlayıcının yetkisini, desteklediği belge türlerini ve sözleşme koşullarını güncel resmî bilgilerle doğrulamak gerekir. Doğrudan GİB entegrasyonu yalnızca bir API adresi eklemekten ibaret değildir; teknik yeterlilik, test ve operasyon sorumlulukları doğurabilir.
Temel veri akışı
- WooCommerce siparişi belirlenen iş durumuna ulaşır.
- Eklenti, faturalama için gerekli alanları doğrular ve değişmez bir istek kaydı oluşturur.
- Alıcının ve işlemin niteliğine göre uygun belge senaryosu belirlenir.
- İstek, kimliği doğrulanmış API bağlantısıyla hizmet sağlayıcıya gönderilir.
- Sağlayıcıdan gelen belge numarası, UUID, durum ve hata bilgileri siparişle ilişkilendirilir.
- Belgenin kesin durumu arka planda sorgulanır; PDF veya görüntüleme bağlantısı müşteriye güvenli biçimde iletilir.
- İptal, iade ve itiraz gibi sonraki olaylar ilk belgenin kimliği üzerinden yönetilir.
Fatura oluşturma adımını ödeme ekranında eşzamanlı çalıştırmayın. Müşteri siparişi tamamlarken uzaktaki servis yavaşlar veya hata verirse ödeme sayfası gereksiz yere bekler. WooCommerce ödeme sayfası terk sorunlarını azaltmak için belge işlemini sipariş kaydedildikten sonra arka plan göreviyle yürütün.
Entegrasyon yöntemini seçerken hangi sorular sorulmalı?
Bir eklenti satın almadan veya özel geliştirmeye başlamadan önce iş gereksinimlerini yazılı hale getirin. Günlük sipariş sayısı tek başına yeterli ölçüt değildir. B2B ve B2C satış oranı, yabancı para, kısmi iade, kupon, kargo, pazar yeri siparişleri, birden fazla şirket ve birden fazla depo gibi ayrıntılar veri modelini değiştirir.
Hazır eklenti mi, özel API entegrasyonu mu?
Hazır eklenti, desteklenen standart akışlarda daha hızlı devreye alınabilir. Bunun karşılığında alan eşleme, sıra dışı vergi senaryosu veya çoklu şirket yapısında sınırlı kalabilir. Özel API entegrasyonu daha fazla kontrol sağlar; ancak kimlik doğrulama, kuyruk, hata yönetimi, güncelleme ve denetim kayıtlarının sorumluluğu geliştiriciye geçer.
Karar verirken şu bilgileri sağlayıcıdan yazılı olarak isteyin:
- GİB tarafından izin verilen hizmet ve belge kapsamı
- Test ortamı, API dokümanı ve sürüm değişikliği politikası
- e-Fatura kullanıcısı sorgulama ve belge türü belirleme yöntemi
- İstek sınırları, zaman aşımı ve bakım pencereleri
- Mükerrer belgeyi önleyen idempotency veya harici referans desteği
- İptal, iade, itiraz ve kısmi işlem desteği
- Belge saklama, erişim, dışa aktarma ve hizmetten ayrılma prosedürü
- Kişisel verilerin işlendiği ve barındırıldığı ortamlar
Özellikle WooCommerce dijital ürün satışı yapıyorsanız teslim anı, ürün türü ve vergi alanlarını hazır eklentinin varsayımlarına bırakmayın. Ürün kataloğundaki vergi sınıfları ile muhasebe sistemindeki kodların birebir eşleştiğini test edin.
Sipariş alanları fatura alanlarına nasıl eşlenir?
WooCommerce sipariş nesnesi fatura için gereken verilerin çoğunu içerir; fakat varsayılan alanlar her ticari senaryo için yeterli olmayabilir. Firma unvanı, vergi dairesi, VKN/TCKN gibi alanların hangi müşteriden ve hangi koşulda isteneceğini belirleyin. Zorunlu olmayan bilgileri tüm müşterilere dayatmak, ödeme deneyimini ve veri minimizasyonunu olumsuz etkileyebilir.
Kontrol edilmesi gereken alan grupları
- Alıcı: Ad, soyad veya unvan; vergi kimliği; ülke ve iletişim bilgileri
- Adres: Fatura adresi, il, ilçe, posta kodu ve ülke kodu
- Satırlar: Ürün adı, miktar, birim, birim fiyat, indirim ve vergi bilgileri
- Toplamlar: Ara toplam, kupon, kargo, vergi, yuvarlama ve genel toplam
- İşlem: Sipariş numarası, tarih, para birimi, ödeme yöntemi ve dış sistem referansı
Toplamı fatura sisteminde yeniden hesaplamak yerine WooCommerce satırlarını ve vergi kırılımlarını açık biçimde aktarın; ardından iki sistemdeki toplamları karşılaştırın. Kuruş farkı varsa belge üretimini sessizce sürdürmek yerine siparişi inceleme kuyruğuna alın. Kupon ve kargo vergisi bulunan siparişleri ayrıca test edin; WooCommerce kupon yapılandırması ile fatura eşlemesinin aynı indirim mantığını kullandığını doğrulayın.
Belge türü kararını sabit kodlamayın
Müşterinin yalnızca “firma adı” yazmasına bakarak belge türü seçmek güvenilir değildir. Güncel kayıtlı kullanıcı sorgusu, mükellef bilgisi ve sağlayıcının desteklediği karar mekanizması birlikte kullanılmalıdır. Kararın sonucunu siparişe kaydedin; ancak harici servisten gelen tüm yanıtı kontrolsüz biçimde WordPress veritabanına yazmayın.
Güvenilir bir WordPress entegrasyon mimarisi
Özel geliştirmede fatura API çağrısını tema dosyasına veya ödeme tamamlandı kancasına doğrudan eklemek kırılgan bir çözümdür. Entegrasyonu ayrı bir eklentide; ayarlar, veri doğrulama, API istemcisi, kuyruk ve günlük katmanlarına ayırın. Böylece tema değişikliği faturalandırmayı etkilemez ve hata ayıklama daha yönetilebilir olur.
Tekrarlanan belgeyi idempotency ile önleyin
Aynı sipariş olayı; sayfa yenileme, zaman aşımı veya kuyruk tekrar denemesi nedeniyle birden fazla kez çalışabilir. Her belge isteği için sipariş kimliği ve işlem türünden türetilen benzersiz bir referans kullanın. Sağlayıcı idempotency anahtarı destekliyorsa aynı anahtarı yeniden gönderin. Siparişte “istek oluşturuldu”, “sağlayıcı kabul etti” ve “belge kesinleşti” durumlarını ayrı tutun.
HTTP zaman aşımı, işlemin başarısız olduğu anlamına gelmeyebilir. Servis belgeyi üretmiş fakat cevap mağazaya ulaşmamış olabilir. Böyle bir durumda yeni belge göndermeden önce dış referans veya UUID ile durum sorgulayın. Bu kural, mükerrer fatura riskini azaltan en önemli teknik kontrollerden biridir.
Kuyruk ve tekrar deneme
WooCommerce’in zamanlanmış görev altyapısı veya güvenilir bir harici kuyruk kullanılabilir. Ağ hatalarında artan bekleme süreleriyle sınırlı tekrar deneme uygulayın. Veri doğrulama hatasını otomatik tekrar etmeyin; eksik VKN veya uyumsuz toplam yeni bir denemeyle düzelmez. Bu kayıtları yönetici incelemesine yönlendirin.
Sağlayıcı sonucu webhook ile bildiriyorsa imzayı doğrulayın, yalnızca HTTPS kullanın ve gelen olayın sipariş ile dış referansa uyduğunu kontrol edin. WooCommerce webhook dokümanı, teslimatların ve hata günlüklerinin yönetim ekranından izlenebildiğini açıklar. Ancak fatura sağlayıcısının webhook biçimi ve doğrulama yöntemi kendi dokümanına göre uygulanmalıdır.
API anahtarları, kişisel veriler ve günlükler
API kullanıcı adı, parola, özel anahtar veya token değerlerini tema dosyasına, JavaScript’e ya da herkese açık depoya koymayın. Sağlayıcı izin veriyorsa IP kısıtlaması, kısa ömürlü token ve ayrı test/canlı anahtarları kullanın. WordPress yönetiminde ayar gösterilecekse gizli değerleri tekrar ekrana basmayın ve yalnızca gerekli rollere erişim verin.
Günlükler hata çözmek için gereklidir; fakat fatura isteğinin ham gövdesini olduğu gibi kaydetmek kişisel veri ve güvenlik riski oluşturur. VKN/TCKN, adres, e-posta ve token gibi alanları maskeleyin. Şu bilgileri saklamak genellikle teşhis için daha uygundur:
- Sipariş kimliği ve dış sistem referansı
- İşlem türü ve zaman damgası
- Sağlayıcı durum kodu ve güvenli hata özeti
- Deneme sayısı ve bir sonraki deneme zamanı
- Belge UUID veya numarası
- İşlemi başlatan sistem olayı veya yetkili kullanıcı
Günlük saklama süresini, yedekleri ve erişim yetkilerini işletmenin mevzuat ve gizlilik yükümlülükleriyle birlikte belirleyin. WooCommerce güvenlik kontrollerindeki rol, güncelleme ve yedekleme adımlarını entegrasyon eklentisine de uygulayın.
İptal, iade ve değişiklik senaryoları
Belge üretildikten sonra WooCommerce siparişini düzenlemek, dış sistemdeki faturayı kendiliğinden değiştirmez. Adres düzeltmesi, ürün iadesi, kısmi ödeme iadesi ve sipariş iptali için sağlayıcının desteklediği mali belge akışını önceden tanımlayın. WooCommerce sipariş notu operasyon kaydıdır; resmî iptal veya itiraz işleminin yerine geçmez.
GİB’in güncel e-Arşiv iptal ve itiraz bildirim kılavuzu bu işlemlerin sistem tarafındaki çerçevesini açıklar. Süre ve yöntemleri kendi belge türünüz için güncel metinlerden doğrulayın. Mağaza tarafındaki müşteri ve stok akışını ise WooCommerce iade ve değişim sayfası ile tutarlı hale getirin.
Canlıya almadan önce test planı
Test ortamında yalnızca tek bir standart sipariş oluşturmak yeterli değildir. En az şu senaryoları belgeleyin:
- Bireysel ve kurumsal alıcı
- e-Fatura kayıtlı ve kayıtlı olmayan alıcı sonucu
- Vergili, farklı vergi sınıflı ve kargo ücretli sipariş
- Kuponlu, ücretsiz ve farklı para birimli sipariş
- Tam ve kısmi iade
- API zaman aşımı, kimlik doğrulama hatası ve geçersiz alan
- Aynı olayın iki kez çalışması
- Belge e-postasının müşteriye ulaşmaması
Her testte WooCommerce toplamı, dış sistem toplamı, belge numarası, müşteri bilgisi ve durum geçişini karşılaştırın. Belge e-postalarını gerçek bir SMTP akışıyla doğrulayın; sorun yaşanırsa WooCommerce sipariş e-postası gitmiyor rehberindeki gönderim günlüklerini kontrol edin.
Canlıya geçişte önce sınırlı sayıda siparişi manuel onay kuyruğunda izlemek güvenli bir yaklaşım olabilir. Başarı oranı veya işlem süresi için tahmin üretmeyin; kendi mağazanızın gerçek günlüklerinden ölçüm yapın. Sağlayıcı güncellemesi, WooCommerce sürüm değişikliği veya vergi ayarı değişikliğinde regresyon testlerini tekrarlayın.
Sıkça Sorulan Sorular
WooCommerce tek başına e-Arşiv fatura oluşturur mu?
WooCommerce sipariş ve vergi verisini tutar; GİB kurallarına uygun e-Belge üretimi için seçilen resmî yöntem veya yetkili hizmet sağlayıcıyla bağlantı gerekir. Kurulumun kapsamı kullandığınız yönteme ve ticari senaryoya göre değişir.
Her tamamlanan siparişte hemen fatura kesilmeli mi?
Tetikleyici durum mağazanın ödeme, teslimat ve mali süreçlerine göre belirlenmelidir. “Sipariş oluşturuldu” olayı her zaman ödemenin kesinleştiğini göstermez. Kararı mali müşavirinizle doğrulayıp eklentide açık bir durum kuralı olarak tanımlayın.
API zaman aşımında isteği yeniden göndermek güvenli mi?
Durum sorgulamadan doğrudan yeniden göndermek mükerrer belgeye yol açabilir. Önce aynı dış referansla belge oluşup oluşmadığını kontrol edin; idempotency anahtarı ve sınırlı tekrar deneme kullanın.
Fatura PDF dosyasını WordPress ortam kütüphanesinde saklamalı mıyım?
Herkese açık veya tahmin edilebilir bir medya adresi kişisel veri sızıntısına yol açabilir. Sağlayıcının güvenli görüntüleme yöntemi ve işletmenin saklama yükümlülükleri değerlendirilmeden PDF’yi normal medya kütüphanesine yüklemeyin.
Hazır eklenti seçerken en önemli teknik kontrol nedir?
Tek bir ölçüt yoktur. Sağlayıcının yetkisi, güncel API desteği, belge türleri, mükerrer işlem koruması, iptal/iade akışı, loglama, veri güvenliği ve test ortamı birlikte incelenmelidir.
Sonuç
WooCommerce e-Arşiv entegrasyonu, sipariş verisini güvenilir biçimde doğrulayan, uygun belge senaryosuna yönlendiren ve sonucu izlenebilir tutan bir sistem olarak tasarlanmalıdır. Entegrasyon yöntemini güncel resmî gereksinimlere göre seçin; sipariş alanlarını açıkça eşleyin; çağrıları kuyrukta yürütün; idempotency, durum sorgulama ve maskelenmiş günlüklerle hata riskini yönetin.
Canlıya geçmeden önce mali kuralları uzmanla, teknik formatı sağlayıcı ve GİB dokümanlarıyla doğrulayın. Böylece yalnızca “fatura kes” düğmesi ekleyen kırılgan bir çözüm yerine; ödeme, iade, müşteri iletişimi ve denetim süreçleriyle uyumlu bir entegrasyon kurabilirsiniz.
