WebBlocks Commerce Operatör Rehberi

WebBlocks Commerce eklentisini kurun, yapılandırın, test edin ve işletin.

WebBlocks Commerce Operatör Rehberi

Bu rehber, ilk WebBlocks Commerce MVP eklentisinin nasıl kurulacağını, yapılandırılacağını ve test edileceğini açıklar. Mevcut eklenti, PayPal üzerinden tek ürünlü barındırılan ödemeyi destekler. Bilerek küçük tutulmuştur: ürün yönetimi, salt okunur sipariş yönetimi, gizli bilgileri açığa çıkarmayan hazırlık tanıları, herkese açık satın alma URL'leri, eklentiye ait bir Commerce Buy Button bloğu, PayPal ödeme yönlendirmeleri ve PayPal webhook tahsilat onayı.

Eklenti plugins/webblocks-commerce altında geliştirilir. Elle kurulan bir eklenti paketi olarak kalır ve CMS çekirdeğine taşınmamalıdır.

Mevcut Kullanıcı Akışı

Bir CMS operatörü WebBlocks Commerce'i kurar ve etkinleştirir.
Operatör, eklenti detay ekranından eklenti migration'larını çalıştırır.
Operatör, kurulum ortamında PayPal kimlik bilgilerini yapılandırır.
Operatör, ödeme ve webhook hazırlığını doğrulamak için Commerce Settings ekranını açar.
Operatör bir commerce ürünü oluşturur.
Ürün detay ekranı herkese açık bir satın alma URL'i gösterir.
Operatör bir sayfaya Commerce Buy Button bloğu ekler ve ürünü seçer.
Bir ziyaretçi ödemeyi başlatır, PayPal'da ödemeyi onaylar ve siteye geri döner.
PayPal webhook'u ödemeyi doğrulayıp tahsil edene kadar sipariş beklemede kalır.
Operatör, ödenmiş siparişi Commerce Orders altında inceler.

Eklentiyi Kurun

Eklenti ZIP'ini CMS deposundan derleyin:

php plugins/webblocks-commerce/build-plugin.php

Ardından elle eklenti yaşam döngüsünü tamamlayın:

System -> Plugins ekranını açın.
Üretilen WebBlocks Commerce ZIP'ini yükleyin.
Eklenti detay ekranını gözden geçirin.
Eklentiyi etkinleştirin.
Eklenti Setup required bildiriyorsa eklenti kurulumunu/migration'larını çalıştırın.
Sağlık durumunun setup-required'dan ready'ye geçtiğini doğrulayın.

Eklenti webblocks_commerce_* tablolarının sahibidir. Eklentiyi devre dışı bırakmak rotaları, menüleri, ayarları ve davranışı etkisiz hale getirir. Devre dışı bırakılmış, elle yüklenmiş bir eklentiyi kaldırmak yüklenen paketi siler ancak eklentiye ait tabloları korur.

API Otomasyonu

Güvenilen operatör araçları, CMS API token'ı açıkça eklenti, commerce ve içerik yeteneklerine sahip olduğunda kurulum ve sayfa oluşturma iş akışını /webadmin/api üzerinden gerçekleştirebilir.

Eklenti yaşam döngüsü:

GET /webadmin/api/plugins POST /webadmin/api/plugins/install POST /webadmin/api/plugins/webblocks-commerce/enable POST /webadmin/api/plugins/webblocks-commerce/setup POST /webadmin/api/plugins/webblocks-commerce/disable DELETE /webadmin/api/plugins/webblocks-commerce

Commerce kaynakları:

GET /webadmin/api/commerce/products POST /webadmin/api/commerce/products PATCH /webadmin/api/commerce/products/{product} GET /webadmin/api/commerce/orders GET /webadmin/api/commerce/orders/{order}

Gerekli token yetenekleri bilerek ayrıştırılmıştır:

eklenti yaşam döngüsü: plugins.read, plugins.install, plugins.manage, plugins.setup ve yalnızca gerektiğinde plugins.uninstall
ürün çalışması: commerce.read ve commerce.products.write
sipariş inceleme: commerce.orders.read
sayfaya yerleştirme: content.validate ve content.apply

Satın alma düğmesi eklemenin API akışı:

webblocks-commerce eklentisini kurun, etkinleştirin ve kurulumunu yapın.
POST /webadmin/api/commerce/products ile aktif bir ürün oluşturun.
GET /webadmin/api/block-types veya GET /webadmin/api/content-contract okuyun.
Content validate/apply üzerinden bir webblocks-commerce-buy-button bloğu ekleyin.
settings.commerce_product_id değerini Commerce API'nin döndürdüğü ürün id'sine ayarlayın.

Commerce Buy Button bloğu eklentiye aittir. Eklenti devre dışıyken blok keşfinden gizlenir; content validate/apply eksik, bilinmeyen veya pasif ürün id'lerini reddeder. API kart verisi toplamaz; ziyaretçiler ödemeyi yine herkese açık Commerce/PayPal akışıyla tamamlar.

PayPal Yapılandırması

WebBlocks Commerce, PayPal REST API'lerini kullanır. PayPal, REST API'lerin OAuth 2.0 erişim token'ları kullandığını ve API çağrılarının bir client ID ile client secret'ı erişim token'ıyla takas ettiğini belgeler. Client secret'ı gizli tutun; CMS içeriğine, doküman sayfalarına, ekran görüntülerine veya destek kayıtlarına asla yapıştırmayın.

Resmî PayPal kaynakları:

CMS kurulumunda şu ortam değişkenlerini ayarlayın:

WEBBLOCKS_COMMERCE_GATEWAY=paypal WEBBLOCKS_COMMERCE_PAYPAL_MODE=sandbox WEBBLOCKS_COMMERCE_PAYPAL_CLIENT_ID=your-paypal-client-id WEBBLOCKS_COMMERCE_PAYPAL_CLIENT_SECRET=your-paypal-client-secret WEBBLOCKS_COMMERCE_PAYPAL_WEBHOOK_ID=your-paypal-webhook-id

WEBBLOCKS_COMMERCE_PAYPAL_MODE=live değerini yalnızca sandbox ödemesi ve webhook doğrulaması test edildikten sonra kullanın.

PayPal Sandbox Kurulumu

PayPal Developer Dashboard'da:

Apps & Credentials ekranını açın.
Varsayılan REST API uygulamasını kullanın veya yeni bir uygulama oluşturun.
Sandbox client ID ve client secret'ı kurulum ortamına kopyalayın.
Uygulamanın webhook ayarlarını oluşturun veya açın.
Şu webhook URL'ini ekleyin:

https://your-site.example/commerce/webhooks/paypal

En azından şu olaylara abone olun:

CHECKOUT.ORDER.APPROVED PAYMENT.CAPTURE.COMPLETED

PayPal webhook ID'sini WEBBLOCKS_COMMERCE_PAYPAL_WEBHOOK_ID değişkenine kopyalayın.
Ödeme testleri için PayPal sandbox alıcı ve satıcı hesaplarını kullanın.

Yerel HTTPS tünellerinde, webhook URL'i olarak tünelin HTTPS URL'ini kullanın. Üretimde nihai herkese açık HTTPS site URL'ini kullanın.

Hazırlık Tanıları

Şu ekranı açın:

/webadmin/plugins/webblocks-commerce/settings

Ayarlar ekranı bilerek yalnızca güvenli tanıları gösterir:

aktif gateway
PayPal modu
client ID yapılandırılmış mı
client secret yapılandırılmış mı
webhook ID yapılandırılmış mı
ödeme hazırlığı
webhook hazırlığı
beklenen webhook URL'i
eklenti şema hazırlığı

Ham PayPal client secret'ları, token'lar, webhook yük imzaları veya ödeme kimlik bilgileri görüntülenmemelidir.

Ürün Oluşturun

Şu ekranı açın:

/webadmin/plugins/webblocks-commerce/products

Şu alanlarla bir ürün oluşturun:

başlık
slug
açıklama
durum
fiyat tutarı
para birimi
isteğe bağlı stok miktarı
isteğe bağlı SKU
isteğe bağlı site kapsamı

Ürün ödemeye açık olacaksa durumunu Active yapın. Taslak ve arşivlenmiş ürünler herkese açık ödemeyi başlatmaz.

Ürün detay ekranı, ürünün herkese açık satın alma URL'ini gösterir:

/commerce/products/{slug}/buy

Sayfaya Satın Alma Düğmesi Ekleyin

Eklenti etkinleştirilip kurulumu hazır olduktan sonra, sayfa oluşturucunun blok seçicisinde eklentiye ait bir Commerce Buy Button bloğu görünür.

Önerilen iş akışı:

Sayfa oluşturucuda eser, portfolyo veya "Works" sayfasını açın.
İstenen slota Commerce Buy Button ekleyin.
Aktif bir commerce ürünü seçin.
İsteğe bağlı olarak düğme etiketini, hizalamayı ve fiyat gösterimini değiştirin.
Çevresindeki içerik hazır olduğunda sayfayı yayınlayın.

Blok, şuraya bağlanan herkese açık bir düğme render eder:

/commerce/products/{slug}/buy

Ürün satın alma URL'i, elle eklenen navigasyon öğeleri veya mevcut bağlantı alanları için yedek olarak kullanışlı kalır.

PayPal barındırılan ödeme URL'lerini CMS içeriğine yapıştırmayın. PayPal onay URL'leri sipariş başına üretilir ve yalnızca ödeme başlatma akışından gelmelidir.

Ödeme Davranışı

Bir ziyaretçi satın alma URL'ine tıkladığında:

Satın alma sayfası eklentinin etkin, kurulumun hazır, ürünün aktif ve gateway'in yapılandırılmış olduğunu denetler.
Ziyaretçi ödemeyi başlatır.
WebBlocks Commerce bekleyen bir sipariş, sipariş kalemi ve bekleyen bir ödeme denemesi oluşturur.
PayPal adaptörü bir PayPal Order oluşturur.
Ziyaretçi PayPal onayına yönlendirilir.
Ziyaretçi imzalı bir başarı veya iptal sayfasına geri döner.
Başarı sayfası siparişi ödendi olarak işaretlemez.
PayPal, /commerce/webhooks/paypal adresine bir webhook gönderir.
WebBlocks Commerce, webhook imzasını PayPal ile doğrular.
CHECKOUT.ORDER.APPROVED için WebBlocks Commerce PayPal siparişini tahsil eder.
Tahsilat tamamlanırsa sipariş paid, ödeme denemesi succeeded olarak işaretlenir.

Webhook olayları gateway ve olay ID'sine göre saklanır; böylece tekrarlanan teslimatlar idempotenttir.

Siparişleri İnceleyin

Şu ekranı açın:

/webadmin/plugins/webblocks-commerce/orders

Siparişler MVP'de salt okunurdur. Sipariş detay ekranı şunları gösterir:

sipariş numarası
PayPal döndürdüğünde müşteri e-postası
sipariş durumu
sipariş kalemleri
ödeme denemeleri
gateway ödeme ve tahsilat referansları
zaman damgaları

Elle durum düzenleme, iadeler, kargo, vergiler ve tedarik iş akışları bilerek ertelenmiştir.

Sandbox Doğrulama Kontrol Listesi

Canlı moda geçmeden önce bu kontrol listesini kullanın:

WebBlocks Commerce kurulu, etkin ve kurulumu hazır.
Commerce Settings şemanın hazır olduğunu gösteriyor.
Commerce Settings gateway olarak paypal gösteriyor.
PayPal client ID yapılandırılmış.
PayPal client secret yapılandırılmış.
PayPal webhook ID yapılandırılmış.
Webhook URL'i HTTPS kullanıyor ve /commerce/webhooks/paypal adresini gösteriyor.
Bir ürün aktif ve beklenen fiyat/para birimine sahip.
Ürün satın alma URL'i herkese açık olarak açılıyor.
Commerce Buy Button içeren bir sayfa beklenen ürün etiketini ve satın alma bağlantısını render ediyor.
Ödemeyi başlatmak PayPal'a yönlendiriyor.
Bir sandbox alıcısı ödemeyi onaylayabiliyor.
Ziyaretçi imzalı başarı sayfasına geri dönüyor.
Webhook onayından önce sipariş beklemede kalıyor.
PayPal CHECKOUT.ORDER.APPROVED teslim ediyor.
Webhook başarıyla doğrulanıyor.
PayPal sipariş tahsilatı tamamlanıyor.
CMS siparişi paid oluyor.
Ödeme denemesi succeeded oluyor.
Aynı webhook'un yeniden gönderilmesi ödeme denemelerini çoğaltmıyor.
Geçersiz webhook imzaları reddediliyor ve siparişleri ödendi olarak işaretlemiyor.
Hiçbir PayPal gizli bilgisi admin ekranlarında, herkese açık sayfalarda, kayıtlarda, ekran görüntülerinde veya dokümanlarda görünmüyor.

Canlı Mod Kontrol Listesi

WEBBLOCKS_COMMERCE_PAYPAL_MODE=live değerine geçmeden önce:

PayPal'ın gerektirdiği yerlerde operatörün bir PayPal Business hesabına sahip olduğunu doğrulayın.
PayPal Developer Dashboard'da canlı REST uygulamasını oluşturun veya seçin.
Sandbox client ID, client secret ve webhook ID'yi canlı değerlerle değiştirin.
Canlı webhook URL'ini üretim HTTPS alan adıyla yapılandırın.
Üretim sitesinin herkese açık PayPal webhook isteklerini alabildiğini doğrulayın.
Operatör için uygunsa düşük tutarlı bir canlı ödeme çalıştırın.
Siparişi CMS admin'de inceleyin.

Sandbox ve canlı kimlik bilgilerini ayrı tutun. Sandbox webhook ID'lerini canlı modda yeniden kullanmayın.

Sorun Giderme

Satın alma sayfası ödemenin hazır olmadığını söylüyorsa:

Commerce Settings ekranını açın.
Gateway'in paypal olduğunu doğrulayın.
Client ID ve client secret'ın yapılandırıldığını doğrulayın.
Ürünün aktif ve geçerli bir fiyata sahip olduğunu doğrulayın.
Eklenti migration'larının çalıştığını doğrulayın.

Ödeme PayPal'a yönlendiriyor ama sipariş beklemede kalıyorsa:

PayPal webhook URL'inin doğru olduğunu doğrulayın.
WEBBLOCKS_COMMERCE_PAYPAL_WEBHOOK_ID değerinin PayPal'da yapılandırılan webhook ile eşleştiğini doğrulayın.
PayPal'ın CHECKOUT.ORDER.APPROVED gönderdiğini doğrulayın.
Siteye PayPal'dan HTTPS üzerinden erişilebildiğini doğrulayın.
Webhook imza doğrulamasının başarısız olmadığını doğrulayın.

Bir webhook reddediliyorsa:

Webhook olayının eşleşen PayPal modundan geldiğini denetleyin.
Sandbox kimlik bilgilerinin canlı webhook ID'leriyle karışmadığını denetleyin.
Webhook ID'nin client kimlik bilgileriyle aynı PayPal REST uygulamasına ait olduğunu denetleyin.

Mevcut Sınırlamalar

MVP henüz şunları içermiyor:

sepet veya çok ürünlü ödeme
vergiler
kargo
kuponlar
abonelikler
CMS'ten iadeler
müşteri hesapları
stok rezervasyonu
tedarik iş akışları
CMS içinde PayPal canlı onboarding arayüzü

Bunlar, ilk eklenti dilimi küçük, güvenli ve incelenebilir kalsın diye bilerek ertelenmiştir.