WooCommerce Merchant API Entegrasyon Mimarisi Rehberi
WooCommerce ile Google Merchant Center arasında güvenilir bir bağlantı kurmak yalnızca ürünleri bir uç noktaya göndermekten ibaret değildir. Sağlıklı bir entegrasyon; ürün verisinin hazırlanmasını, kimlik doğrulamayı, zamanlamayı, hata yönetimini, yeniden denemeleri, değişiklik takibini ve mağaza ile Google tarafındaki durumların eşleştirilmesini birlikte ele almalıdır. Bu rehber, WooCommerce ürünlerini Merchant API üzerinden yöneten bir sistemin temel mimarisini açıklar.
Doğru tasarlanmış bir mimarinin amacı, WooCommerce mağazasını ana veri kaynağı olarak korurken Google Merchant Center’daki ürün bilgilerinin güncel kalmasını sağlamaktır. Fiyat, stok, başlık, açıklama, görsel veya ürün durumu değiştiğinde entegrasyon bu değişikliği algılamalı, gerekli veriyi doğrulamalı ve yalnızca ilgili güncellemeyi güvenli biçimde göndermelidir.
Temel veri akışı
Entegrasyonun başlangıç noktası WooCommerce ürün kaydıdır. Basit ürünlerde tek bir ürün nesnesi bulunurken varyasyonlu ürünlerde ana ürün ile her varyasyonun ayrı ayrı değerlendirilmesi gerekir. Sistem; ürün kimliği, SKU, başlık, açıklama, bağlantı, görsel, fiyat, indirimli fiyat, stok durumu, marka, GTIN, MPN, ürün durumu ve gönderim için gerekli diğer alanları WooCommerce’ten okur.
Okunan veriler doğrudan gönderilmeden önce bir dönüştürme katmanından geçirilmelidir. WooCommerce alan adları ile Google’ın beklediği alanlar bire bir aynı değildir. Bu katman para birimini, stok değerlerini, bağlantıları, görsel adreslerini ve ürün tanımlayıcılarını Merchant API biçimine dönüştürür. Eksik veya geçersiz alanlar bu aşamada işaretlenir.
- WooCommerce ürün veya varyasyon kaydını oku.
- Gönderim için gerekli alanları normalleştir.
- Zorunlu ve önerilen alanları doğrula.
- Merchant API isteğini oluştur.
- İsteği yetkilendirilmiş bağlantı üzerinden gönder.
- Yanıtı ve ürün durumunu kaydet.
- Geçici hataları yeniden deneme kuyruğuna al.
WooCommerce ana veri kaynağıdır
Ürün başlığı, fiyatı veya stok bilgisi hem WooCommerce’te hem de başka bir yönetim ekranında ayrı ayrı düzenlenirse veri uyuşmazlığı oluşabilir. Bu nedenle mimari, WooCommerce’i ürün verisinin ana kaynağı kabul etmelidir. Merchant Center tarafında yapılan manuel değişiklikler bir sonraki eşitlemede üzerine yazılabileceğinden kalıcı ürün düzenlemeleri WooCommerce üzerinden yapılmalıdır.
Bu yaklaşım, mağazada müşteriye gösterilen bilgilerle Google’a gönderilen bilgilerin aynı kaynaktan gelmesini sağlar. Özellikle fiyat ve stok uyuşmazlıklarının azaltılması için ürün sayfası, yapılandırılmış veri ve Merchant API yükü arasında tutarlılık önemlidir.
Kimlik doğrulama ve yetkilendirme
Merchant API bağlantısı, Google OAuth 2.0 yetkilendirme akışıyla kurulmalıdır. Kullanıcı Google hesabını seçer, istenen izinleri görür ve açıkça onaylar. Eklenti Google hesabı parolasını görmemeli veya saklamamalıdır. Başarılı bağlantı sonrasında erişim belirteçleri güvenli biçimde yönetilmeli ve yalnız gerekli API işlemleri için kullanılmalıdır.
İstenen kapsamlar mümkün olan en dar yetkiyle sınırlandırılmalıdır. Bir işlev yalnız ürünleri okumayı gerektiriyorsa gereksiz hesap izinleri istenmemelidir. Ürün oluşturma, güncelleme veya silme işlevleri kullanılıyorsa kapsam açıklaması bu işlevlerle tutarlı olmalıdır.
Erişim belirteçleri günlük kayıtlara, hata iletilerine veya yönetim ekranına açık metin olarak yazılmamalıdır. Bağlantı kesildiğinde ya da kullanıcı yeniden kurulum yapmak istediğinde kayıtlı yetkilendirme bilgilerini güvenli biçimde kaldıran bir sıfırlama işlemi bulunmalıdır.
Ürün eşleme ve kararlı kimlikler
Her WooCommerce ürünü Google tarafında kararlı bir teklif kimliğiyle eşleştirilmelidir. Bu kimlik, ürün yeniden gönderildiğinde değişmemelidir. Aksi durumda mevcut ürün güncellenmek yerine yinelenen yeni bir ürün oluşturulabilir. Basit ürünlerde WooCommerce ürün kimliği veya güvenilir SKU kullanılabilir. Varyasyonlu ürünlerde her varyasyonun benzersiz teklif kimliği bulunmalıdır.
Ana ürün ile varyasyonlar arasındaki ilişki, ortak bir ürün grubu kimliği kullanılarak korunmalıdır. Renk, beden, malzeme veya desen gibi varyasyon özellikleri ilgili varyasyona doğru şekilde aktarılmalıdır. Satın alınamayan ana değişken ürünün ayrıca satış teklifi olarak gönderilmesi çoğu durumda doğru değildir; satın alınabilir varyasyonlar ayrı ürünler olarak işlenmelidir.
Doğrulama katmanı
API isteğinden önce yapılan yerel doğrulama, gereksiz hataları ve tekrarları azaltır. Sistem en azından şu kontrolleri yapmalıdır:
- Ürün başlığı ve açıklaması boş mı?
- Ürün bağlantısı ve görsel adresi HTTPS üzerinden erişilebilir mi?
- Fiyat sayısal mı ve geçerli para birimiyle birlikte mi?
- Stok durumu desteklenen bir değere dönüştürüldü mü?
- Ürün yeni, yenilenmiş veya kullanılmış olarak doğru tanımlandı mı?
- Marka, GTIN ve MPN alanları ürünün niteliğine uygun mu?
- Varyasyon özellikleri ile ürün grubu kimliği tutarlı mı?
- Hedef ülke ve dil ayarları mağaza verisiyle uyumlu mu?
Doğrulama sonucunda ürünler uygun, sorunlu veya kritik gibi anlaşılır gruplara ayrılabilir. Kullanıcı yalnız hata kodunu değil, hangi WooCommerce alanını nasıl düzeltmesi gerektiğini de görebilmelidir.
İlk eşitleme ve artımlı güncellemeler
İlk kurulumda ürün kataloğunun tamamı kontrollü gruplar hâlinde gönderilebilir. Binlerce ürünü tek HTTP isteğinde işlemeye çalışmak zaman aşımına, bellek kullanımına ve yarım kalan işlemlere neden olabilir. Bu nedenle katalog küçük partilere ayrılmalı ve her partinin sonucu ayrı kaydedilmelidir.
İlk eşitlemeden sonra tüm kataloğu sürekli yeniden göndermek yerine artımlı güncelleme kullanılmalıdır. WooCommerce ürününde fiyat, stok, başlık, açıklama veya görsel değiştiğinde yalnız ilgili ürün kuyruğa eklenir. Bir ürün kalıcı olarak silindiğinde veya yayından kaldırıldığında Google tarafındaki karşılığı da uygun işlemle kaldırılmalıdır.
Değişiklik yakalama işlemi WordPress ve WooCommerce kancaları üzerinden yapılabilir. Ancak ürün kaydedilirken aynı olayın birden fazla kez tetiklenmesi mümkündür. Kuyruk sistemi aynı ürün için yinelenen görevleri birleştirmeli ve gereksiz API trafiğini önlemelidir.
Kuyruk ve zamanlanmış işlemler
Uzun süren API işlemleri normal sayfa isteği içinde çalıştırılmamalıdır. Kullanıcı ürün kaydettiğinde yönetim ekranının API yanıtını beklemesi kötü bir deneyim oluşturur. Bunun yerine değişiklik güvenli bir kuyruğa yazılmalı ve arka plan çalışanı tarafından işlenmelidir.
Kuyruktaki her görev ürün kimliği, işlem türü, oluşturulma zamanı, deneme sayısı ve son hata bilgisi gibi sınırlı fakat yeterli veriyi içermelidir. Hassas OAuth bilgileri görev gövdesine kopyalanmamalıdır. İşlem başarıyla tamamlandığında görev kapatılmalı; geçici hata oluştuğunda kontrollü gecikmeyle yeniden denenmelidir.
Hata yönetimi ve yeniden deneme
Tüm hatalar aynı şekilde ele alınmamalıdır. Ağ kesintisi, zaman aşımı veya geçici sunucu hatası yeniden denenebilir. Geçersiz fiyat, eksik başlık veya hatalı ürün bağlantısı ise veri düzeltilmeden tekrar gönderilmemelidir. Sistem kalıcı veri hatalarıyla geçici altyapı hatalarını ayırmalıdır.
Yeniden denemelerde artan bekleme süresi kullanılabilir. Bir görev arka arkaya başarısız oluyorsa sınırsız döngüye girmemeli; belirlenen deneme sayısından sonra kullanıcı incelemesine bırakılmalıdır. Yönetim ekranı son hatayı, zamanı ve önerilen düzeltmeyi göstermelidir.
Günlük kayıtları ve gizlilik
Tanılama kayıtları sorun çözmek için yararlıdır ancak gereğinden fazla veri toplamamalıdır. Ürün kimliği, işlem türü, yanıt durumu ve maskelenmiş hata bilgisi genellikle yeterlidir. Erişim belirteçleri, müşteri verileri, parolalar ve diğer güvenlik sırları günlüğe yazılmamalıdır.
Kayıtların saklama süresi sınırlandırılmalı ve yönetici tarafından temizlenebilmelidir. Kullanıcıya sunulan hata metni teknik ayrıntıyı açıklarken sunucu yollarını, SQL sorgularını veya kimlik doğrulama sırlarını açığa çıkarmamalıdır.
Performans ve ölçeklenebilirlik
Büyük mağazalarda bütün ürün nesnelerini aynı anda belleğe almak yerine sayfalama kullanılmalıdır. Yalnız gerekli alanlar okunmalı, sorgular indeksli sütunlar üzerinden yapılmalı ve her görev tamamlandıktan sonra bellek serbest bırakılmalıdır. Aynı ürünün kısa sürede çok kez değişmesi durumunda yalnız son durumun gönderilmesi API kullanımını azaltabilir.
Arka plan görevleri sitenin normal ziyaretçi trafiğini etkilemeyecek büyüklükte çalıştırılmalıdır. Barındırma ortamı yavaşsa parti boyutu küçültülebilir. Başarılı bir mimari yalnız hızlı değil, kesintiden sonra kaldığı yerden devam edebilir olmalıdır.
Durum eşitleme ve izleme
Bir ürünün API tarafından kabul edilmesi, Google’da hemen onaylandığı anlamına gelmez. Ürün daha sonra politika, veri kalitesi veya hedef ülke koşulları nedeniyle incelemeye alınabilir. Bu nedenle sistem gönderim sonucuyla Merchant Center ürün durumunu ayrı göstermelidir.
Yönetim ekranında son başarılı eşitleme zamanı, bekleyen görev sayısı, başarısız görevler, uygun ürünler ve düzeltme gerektiren ürünler görülebilir. Bu görünüm, kullanıcının yalnız işlemin çalışıp çalışmadığını değil, ürünlerin Google tarafındaki gerçek durumunu anlamasına yardımcı olur.
Güvenli kaldırma ve yeniden bağlantı
Kullanıcı Merchant hesabını değiştirmek isteyebilir. Yeniden bağlantı süreci mevcut hesabın kimliğini açıkça göstermeli, yanlış hesaba ürün gönderme riskine karşı onay istemeli ve eski bağlantıya ait belirteçleri kaldırmalıdır. Bağlantının sıfırlanması WooCommerce ürünlerini silmemeli veya mağaza verisini değiştirmemelidir.
Eklenti kaldırılırken uzak Merchant Center ürünlerinin otomatik silinmesi varsayılan davranış olmamalıdır. Böyle bir işlem sunuluyorsa sonucu açıkça anlatılmalı ve ayrıca onay alınmalıdır.
Sonuç
WooCommerce Merchant API entegrasyonu; veri dönüştürme, doğrulama, güvenli OAuth bağlantısı, kararlı ürün kimlikleri, artımlı eşitleme, kuyruk yönetimi ve anlaşılır hata raporlamasının birlikte çalıştığı bir sistemdir. Bu katmanlardan biri eksik olduğunda yinelenen ürünler, güncel olmayan fiyatlar, kaybolan görevler veya çözülmesi zor bağlantı sorunları ortaya çıkabilir.
İyi tasarlanmış bir mimari WooCommerce’i ana ürün kaynağı olarak korur, yalnız gerekli değişiklikleri gönderir, geçici sorunlardan sonra kendini toparlar ve kullanıcıya Merchant Center durumunu anlaşılır biçimde gösterir. Böylece ürün kataloğu büyüdükçe entegrasyonun güvenilirliği ve yönetilebilirliği korunabilir.