WebBlocks Commerce ile Satışa Başlayın

Commerce, CMS'nize birbiriyle bağlantılı üç bölüm ekler:

• Ürünler: başlık, açıklama, fiyat, para birimi, stok ve ürün vergi sınıfı.
• Ziyaretçinin alışveriş akışı: yerel Commerce Buy Button bloğu, miktar denetimleri olan sepet ve iletişim ile teslimat bilgilerinin alındığı ayrı bir ödeme formu.
• Siparişler ve ödemeler: kaydedilen sipariş kalemleri, müşteri ve teslimat bilgileri, vergi toplamları ve ödeme girişimleri. PayPal ve SumUp ödemeyi kendi barındırdıkları sayfalarda alır; ziyaretçi kart bilgilerini bir CMS içerik bloğuna girmez.

Ürün hikâyesi, fotoğraflar, sık sorulan sorular ve gezinme için normal CMS sayfalarını kullanmaya devam edersiniz. Commerce bloğu bu içerik sayfasını gerçek ürüne bağlar. Satış sayfasındaki bir paragrafı düzenlemek ürünün fiyatını veya stokunu değiştirmez; bunları Commerce → Products bölümünden yönetirsiniz.

Bu yapı küçük bir katalog veya mevcut sayfalardan satılan birkaç ürün için iyi bir başlangıçtır. Kargo ücreti hesaplama motoru, kuponlar, depo sevkiyat iş akışı veya sipariş ekranında iade düğmesi sunmaz. Teslimat adresi almak kargoyu otomatik olarak ayarlamaz. Yinelenen üyelikler ayrı Memberships eklentisini ve kendi kurulumunu kullanır; bu rehberdeki tek seferlik siparişler için ona ihtiyacınız yoktur.

Uç nokta adları, geliştirici entegrasyonu ve ayrıntılı ödeme sözleşmesi için Commerce teknik başvurusunu yanınızda bulundurun. Bu rehber panelde yapacağınız işlemleri izler.

Bir test kurulumu veya henüz müşterilere açılmamış mağaza kullanın. Etkin ödeme ağ geçidini değiştirmek kurulumun Commerce ödeme akışını etkiler; müşteriler alışveriş yaparken çalışan mağazayı test moduna almayın.

Şunlar gereklidir:

• Çalışan bir WebBlocks CMS kurulumu ve kurulum ile ödeme ayarları için Super admin hesabı.
• Seçilen katalog sürümüyle uyumlu CMS sürümü. Commerce 0.16.0, CMS ^1.100.0 gerektirir; katalog uyumluluğunda Laravel 13 de listelenir. Kurmadan önce kataloğu gerçek kurulumunuzla karşılaştırın.
• Hem web hem komut satırı ortamında PHP intl uzantısı. Commerce para birimi biçimlendirme uyarısı veriyorsa barındırma yöneticinizden etkinleştirmesini isteyin.
• CMS'de bir site ve o sitedeki sayfayı düzenleme ve önizleme izni.
• Daha sonra uygun bir PayPal veya SumUp satıcı hesabı, o ortama ait test kimlik bilgileri ve sağlayıcı geri bildirimleri için internetten erişilebilir HTTPS site.

Site Admin, kendisine atanmış sitelerde ürünleri yönetebilir ve siparişleri inceleyebilir. Eklenti kurulumu, Commerce ayarları ve ödeme kimlik bilgileri Super admin görevleridir. İlgili ekran görünmüyorsa yöneticiniz rolünüzü ve site atamanızı kontrol etsin; ikinci hesap oluşturmak kurulumun bir adımı değildir.

Eklenti, WebBlocks eklenti kataloğunda ücretsiz listelenir. Ödeme hizmeti hesabı ayrı bir hizmettir; Commerce kurulumu sizin için böyle bir hesap oluşturmaz veya bağlamaz.

1. CMS'nize giriş yapıp System → Plugins bölümünü açın.
2. Browse Plugin Catalog seçeneğine basıp WebBlocks Commerce sayfasını açın.
3. Uyumluluk sonucunu ve sürüm notlarını okuyun. Uyumlu sürüm sunulduğunda Install from Catalog seçeneğini kullanın.
4. Kurulan eklentinin ayrıntı ekranına dönün. Yeni paket, inceleyebilmeniz için disabled durumunda başlar.
5. Enable Plugin seçeneğine basın. Eklentinin etkin olduğunu doğrulayıp sağlık sonucunu inceleyin.

Güncel CMS sürümlerinde eklenti veritabanı değişiklikleri kurulum, güncelleme ve etkinleştirme sırasında otomatik uygulanır. Migrations Up to Date, elle migration çalıştırmanız gerekmediğini belirtir. Veritabanı hazırlığı başarısız olursa devam etmeden bildirilen sorunu çözün; eklentiyi tekrar tekrar etkinleştirmek eksik veritabanı yetkisini düzeltmez.

Görsel tamamlanmış kurulumu gösterir. Yöneticiniz güvenilir bir sürüm ZIP dosyası sağlıyorsa aynı ekrandaki Plugin ZIP → Upload Plugin ZIP yolunu kullanın, ardından inceleyip etkinleştirin. Mağaza sahibinin bu iki panel kurulum yolu için de eklenti kaynak deposuna veya Composer derleme komutuna ihtiyacı yoktur.

Etkinleştirmenin ardından yan menüye Commerce → Products, Orders, Settings eklenir. Devam etmek için Settings bölümünü açın. Eklenti sağlığı paketin çalışabildiğini doğrular; ödeme hazırlığı Commerce Settings içinde ayrıca kontrol edilir.

1. Commerce → Settings → General bölümünü açın.
2. Gateway alanını Test order (no payment) yapın.
3. Bu örnek için Default Currency değerini EUR seçin.
4. Sonraki testler için PayPal Mode ve SumUp Mode değerlerini Sandbox bırakın.
5. Save Commerce Settings düğmesine basıp Overview bölümüne dönün.

Varsayılan para birimi yeni ürünlerin başlangıç değeridir. Mevcut bir ürünün fiyatını dönüştürmez. Her ürün kendi para birimini korur ve sepetteki tüm ürünlerin para birimi aynı olmalıdır.

Bu alıştırmada önemli kontroller Schema: Ready ve Gateway: Ready durumlarıdır. PayPal ve SumUp etkin değilken Needs config gösterebilir. Ödeme alınmayan test siparişi vermek için sağlayıcı kimlik bilgisi girmeniz gerekmez.

Genel bakış, test ağ geçidini fake adıyla gösterebilir; bu, Test order (no payment) seçeneğinin iç adıdır. Ödenmemiş sipariş kaydeder, stok ayırır ve ödeme sağlayıcısıyla iletişim kurmaz. Başarılı ödeme simülasyonu değildir ve siparişi Paid yapmaz.

Commerce → Products → New Product bölümünü açın. Northstar Studio yerine kendi sitenizi seçerek şu değerleri girin:

Price Amount, ondalıklı satış fiyatı yerine tam sayı alt para birimi kullanır. €18.00 fiyatlı ürün için 18 veya 18.00 yerine 1800 girin. Bazı para birimlerinde alt birim sayısı farklıdır; her para biriminin cent kullandığını varsaymayın. Kaydettikten sonra biçimlendirilmiş fiyatı kontrol edin.

Inventory alanını yalnızca stok takibini bilerek kapatmak istiyorsanız boş bırakın. Boş değer sınırsız bulunabilirlik demektir; tükenmiş anlamına gelmez. Bu anlatım için belirli bir site seçin. Install-wide, Super admin kullanımına yönelik ayrı bir kapsamdır; mevcut sitenizi seçmekle aynı değildir.

Save Product düğmesine basıp ayrıntı ekranında Active, €18.00, Inventory 24 ve Product Available bilgilerini kontrol edin. Ayrıntı ekranı bir Public Buy URL de sunar. Doğrudan ürün bağlantısı gerekiyorsa kurulumunuzun gösterdiği URL'yi kopyalayın; ekran görüntüsündeki localhost adresini kullanmayın.

Sitede ek diller etkinse ürün formunda çevrilmiş başlıklar ve açıklamalar sunulur. Boş çeviride temel içerik kullanılır. CMS satış sayfasının çevirisi ile Commerce ürününün çevirisi ayrı işlerdir; mağazaya yeni dil eklerken ikisini de kontrol edin.

Defter için taslak CMS sayfası oluşturun veya yayımlanmış satış sayfasına aşamalı güncelleme hazırlayın. Ürünle aynı siteyi seçin. Normal Media Library ve Image bloğunu kullanarak başlık, yararlı açıklama ve varsa ürün fotoğrafı ekleyin.

Ardından sayfayı Commerce'e bağlayın:

1. Sayfanın Main alanını açıp istediğiniz konumda Add Block seçeneğini kullanın.
2. Commerce Buy Button bloğunu seçin.
3. Block Fields içindeki Product alanından Studio notebook ürününü seçin.
4. Button Label değerini Add to Cart yapın.
5. Start hizalamasını seçip Show price beside the button seçeneğini etkinleştirin.
6. Save Block düğmesine basıp kaydedilmiş sayfanın Preview görünümünü açın.

Yerel blok seçilen ürünü Commerce sepetine ekler. Sayfa içeriğine Trusted HTML bloğu, kopyalanmış ödeme formu veya sağlayıcı betiği koymanız gerekmez.

Taslak önizleme, sayfayı yayımlamadan test etmenizi sağlar. Önizleme bandı sepet işlemlerini deneme amaçlı etkisiz işlemlere dönüştürmez. Düğmeye basmak oturumunuzun sepetini değiştirir; ödeme adımlarını tamamlamak sipariş oluşturur. Bu nedenle önce ödeme alınmayan ağ geçidini seçtik.

Site başlığında kalıcı sepet bağlantısı istiyorsanız /plugins/webblocks-commerce/cart adresine giden, Cart etiketli ve shopping-cart simgeli gezinme öğesi ekleyin. Commerce bu simge eyleminde sepet miktarını gösterebilir. Öğenin eklenmesi ve sıralanması gezinme menüleri rehberinde açıklanır.

Sayfa önizlemesinde Add to Cart düğmesine basın. Commerce tek defter içeren sepeti açar. Miktar denetimindeki + düğmesine bir kez basarak miktarı iki yapın.

Ürün adını, miktarı ve biçimlendirilmiş fiyatı doğrulayın. Bu rehberin EUR fiyatları ve vergi dâhil örnek verileriyle iki adet €18.00 defterin toplamı €36.00 olur. Miktarı azaltabilir veya kalemi silebilirsiniz. Aynı ürünü tekrar eklemek miktarları birleştirir; farklı para birimindeki ürün reddedilir.

Go to checkout düğmesine basın. İletişim ve teslimat bilgileri bu ayrı ekrandadır. Gerçek müşteri bilgileri yerine Example customer ve customer@example.test gibi kendi test verilerinizi girin.

Form; tam ad, e-posta, sokak ve kapı numarası, posta kodu, şehir ve DE gibi iki harfli ülke kodu ister. Telefon ve ikinci adres satırı isteğe bağlıdır. Toplamı inceleyip Place test order düğmesine basın.

Ürün atölye bileti veya gönderilmeyecek başka bir ürün olsa da form şu anda teslimat bilgilerini toplar. Bunu kargo hizmeti olarak değerlendirmeyin: bu sürümde Commerce teslimat ücreti hesaplamaz ve taşıyıcı rezervasyonu oluşturmaz. Özetteki kargo metni, ücret veya sevkiyat iş akışının yapılandırıldığına kanıt değildir.

Başarılı sonuç Test Order Received der ve ödeme alınmadığını açıklar. Beklenen durum Pending olur. Sonraki adım için sipariş numarasını saklayın; özel sipariş durumu bağlantısını paylaşmanız gerekmez.

Commerce → Orders bölümünü açıp sonuç ekranındaki sipariş numarasını bulun ve açın. Şunları kontrol edin:

• Status: ödenmemiş test siparişi olduğu için Pending.
• Items: Studio notebook, 2 adet, birim fiyat €18.00, toplam €36.00.
• Customer ve Delivery: girdiğiniz kurgusal bilgiler.
• Gateway: ödeme alınmayan mod olan fake.
• Payment Attempts: kaydedilen girişim ve durumu.
• Vergi dökümü: ödeme sırasında kullanılan net ara toplam, KDV ve brüt toplam.

Defter ürününü tekrar açın. Inventory artık 22 olmalıdır: ödeme adımı başladığında iki birim ayrıldı. Ürünü yalnızca sepete eklemek stok ayırmaz. Gerçek sağlayıcıya ait bekleyen siparişler de ödeme alınmayan test siparişleri de stok rezervasyonu tutabilir.

Sipariş ekranı salt okunurdur. Burada durumunu düzenleyerek test siparişini ödenmiş siparişe dönüştüremezsiniz; PayPal veya SumUp'tan tarayıcıya başarılı dönüş de ödeme kanıtı değildir. Gerçek ödeme durumu ancak Commerce sağlayıcı geri bildirimini ve ödeme ayrıntılarını doğruladıktan sonra değişir.

Fiyatlar ve vergi toplamları sipariş sırasında kaydedilir. Ürün fiyatının sonradan değişmesi gelecekteki işlemleri etkiler; mevcut siparişin tutarlarını yeniden yazmaz.

Para birimi: sağlayıcı hem varsayılan para birimini hem arşivlenmemiş mevcut ürünlerin para birimlerini desteklemelidir. Bir ürün desteklenmeyen para birimi kullanıyorsa ağ geçidi değişikliği reddedilebilir. Ürünün para birimini düzeltin veya ürünü bilinçli şekilde arşivleyin; yalnızca varsayılanı değiştirmek kur dönüşümü değildir.

Vergi: ürünün vergi sınıfı, mağazanın vergi ülkesi için sunucuda yapılandırılan oranlarla birleştirilir. Eklenti her teslimat adresinden otomatik yeni vergi yetki alanı seçmez. Sipariş almadan önce mağazanın vergi yapılandırmasını barındırma yöneticinize doğrulatın.

İlgili sunucu ayarları WEBBLOCKS_COMMERCE_TAX_ENABLED, WEBBLOCKS_COMMERCE_PRICES_INCLUDE_TAX ve WEBBLOCKS_COMMERCE_TAX_COUNTRY adlarını taşır. Vergi dâhil fiyatlarda KDV ürün fiyatının içinden ayrıştırılır; vergi hariç fiyatlarda fiyatın üzerine eklenir. Bu testte yapılandırılmış %19 standart oran ve vergi dâhil EUR fiyatları kullanılır: €36.00 toplam, €5.75 KDV ve €30.25 net içerir. Bu, örnek verinin hesaplamasını gösterir; her mağazada uygulanacak oran değildir.

Stok: takip edilen birimler ödeme adımında ayrılır; sipariş desteklenen yaşam döngüsünde başarısız olduğunda, iptal edildiğinde, süresi dolduğunda veya iade edildiğinde serbest bırakılır. Takip edilmeyen ürünlerin miktarı azaltılmaz. Sipariş oluşturulmadan önce güncel fiyat ve bulunabilirlik tekrar kontrol edilir; kayıtlı sepet sabit fiyat veya ayrılmış stok garantisi vermez.

Barındırma yöneticinizden terk edilmiş sipariş temizliğini zamanlamasını isteyin. Eklenti şu komutu sunar:

Örneğin sunucu uygulamasının Laravel zamanlayıcısı ile on beş dakikada bir çalıştırılabilir. Mağazaya ve ödeme akışına uygun süre seçin; komut yalnızca test siparişlerinin değil, bu eşikten eski tüm bekleyen siparişlerin süresini doldurur. Böylece terk edilmiş ödeme işlemlerinin tuttuğu stok serbest kalır. Test siparişleri daha uzun bekleyince ödenmiş olmaz.

Bu bölümde internetten erişilebilir HTTPS test sitesi kullanın. Sağlayıcı sunucu geri bildirimini yerel ekran görüntülerindeki 127.0.0.1 adresine gönderemez.

1. PayPal Developer Dashboard içinde Apps & Credentials bölümünü açıp uygulamanızın sandbox client ID ve client secret bilgilerini alın. Bu mağaza için ayrılmış uygulamayı ve satıcı hesabını kullanın.
2. Commerce → Settings → General bölümünde PayPal seçin; PayPal Mode için Sandbox, varsayılan para birimi için desteklenen bir değer seçip kaydedin.
3. PayPal sekmesini açıp Client ID ve Client Secret bilgilerini girin.
4. Kurulumunuzun oluşturduğu Webhook URL adresini kopyalayın. PayPal'da aynı uygulama ve mod için bu HTTPS uç noktasını kaydedin; entegrasyonun kullandığı CHECKOUT.ORDER.APPROVED olayını da ekleyin. Oluşan Webhook ID değerini Commerce'e geri kopyalayın.
5. Kaydedip Overview ve PayPal sekmesindeki ödeme ile webhook hazırlığını kontrol edin.
6. Yeni sipariş başlatıp uygun sandbox alıcı hesabıyla onaylayın. Yalnızca tarayıcı dönüş sayfasına güvenmek yerine doğrulanmış geri bildirimden sonra siparişin Paid olduğunu kontrol edin.

Herkese açık uç noktanızın yolu /plugins/webblocks-commerce/webhooks/paypal olur. Alan adı ve protokolün gerçek kurulumla eşleşmesi için panelden kopyalayın. Client ID, secret ve webhook ID aynı PayPal uygulamasına ve ortama ait olmalıdır.

PayPal'ın REST kurulum yönergeleri uygulama kimlik bilgilerini ve sandbox hesaplarını, Webhooks başvurusu webhook aboneliklerini açıklar. Panel iş akışı için bu API'leri kendiniz uygulamanız gerekmez.

General ayarlarında tek etkin sipariş ağ geçidi seçersiniz. İki sağlayıcının bilgilerini de yapılandırmak ödeme ekranına ziyaretçi için sağlayıcı seçimi eklemez.

1. SumUp test satıcı hesabını ve ona ait API anahtarı ile satıcı kodunu hazırlayın. Bu değerlerin nereden alınacağından emin değilseniz SumUp bağlantı anlatımını izleyin.
2. Commerce → Settings → General bölümünde SumUp, SumUp Mode için Sandbox ve uyumlu varsayılan para birimini seçip kaydedin.
3. SumUp sekmesinde API Key ve Merchant Code bilgilerini girip kaydedin.
4. Hazırlık durumunu ve oluşturulan webhook URL'sini kontrol edin. Herkese açık HTTPS yolu /plugins/webblocks-commerce/webhooks/sumup erişilebilir olmalıdır.
5. Sepetten yeni ödeme işlemi başlatın. Commerce barındırılan ödeme oturumunu oluşturup müşteriyi SumUp ödeme sayfasına gönderir. Testi orada tamamlayın, siteye dönün ve kaydedilen siparişi inceleyin.
6. Siparişin ancak Commerce sağlayıcının ödeme sonucunu alıp doğruladıktan sonra Paid olduğunu teyit edin.

Commerce her ödeme oturumunu oluştururken SumUp geri bildirim URL'sini sağlar. Sizden ayrı SumUp Webhook ID istemez. Modu Sandbox yapmak gerçek satıcı anahtarını test anahtarına dönüştürmez; hesap, satıcı kodu ve anahtar hedeflenen ortama ait olmalıdır.

SumUp'ın çevrimiçi ödeme özeti barındırılan ödeme alımını, Checkouts API başvurusu ödeme oturumunu ve sunucu geri bildirimini açıklar. CMS bu akışı sizin için kullanır; kart bilgileri SumUp'ın barındırdığı yüzeyde kalır.

Sağlayıcı kimlik bilgisi alanları yalnızca yazılabilirdir. Kaydettikten sonra form yeniden boş görünür ve değerin yapılandırılıp yapılandırılmadığını gösterir. Boş alan, kayıtlı bilginin kaybolduğu anlamına gelmeyebilir. Kayıtlı alanı boş bırakmak değerini korur; Clear saved value seçeneğini yalnızca kaldırmak istediğinizde kullanın.

Commerce Settings içinde kaydedilen değerler depolamada şifrelenir. Yönetici bunun yerine karşılık gelen sunucu ortam değerlerini yönetebilir. Bunlar önceliklidir ve Managed by environment olarak görünür; geçersiz kılınan alan panelde salt okunurdur. System sekmesi desteklenen ortam değişkeni adlarını değerlerini göstermeden listeler.

Kaydettiğiniz yeni değer etkisiz görünüyorsa tekrar girmeden önce alanın kaynak etiketini kontrol edin. Ortam değişikliklerini barındırma yöneticinizle koordine edin. Anahtar veya sırları sayfaya, HTML bloğuna, ekran görüntüsüne veya destek mesajına koymayın.

Ödeme ayarları kurulum düzeyinde ortaktır. Site kapsamlı ürünler ve Site Admin yetkileri her site için ayrı satıcı yapılandırması oluşturmaz.

Önce ödeme alınmayan alıştırmayı tamamlayın, ardından seçilen sağlayıcının sandbox akışıyla ayrı bir uçtan uca test yapın. Bu rehberin görselleri yalnızca ödeme alınmayan alıştırmayı gösterir; satıcı hesabınızın veya herkese açık geri bildirimlerinizin çalıştığını kanıtlamaz.

Satış sayfasını ziyaretçilere açmadan önce şunları doğrulayın:

• Seçilen sağlayıcı, mod, satıcı kimlik bilgileri ve webhook ayarları birbiriyle eşleşiyor.
• Site ve geri bildirim URL'leri doğru herkese açık HTTPS alan adını kullanıyor ve erişilebilir kalıyor.
• Satmak istediğiniz her ürün Active, doğru siteye atanmış, doğru fiyatlandırılmış ve desteklenen para biriminde.
• Vergi yapılandırması ve gerçek teslimat/sevkiyat süreci sayfanızın vaatleriyle eşleşiyor.
• Sandbox ödemesi, sağlayıcı doğrulamasından sonra Commerce → Orders içinde Paid oluyor. İptali ve ilgili hata yollarını da test edin.
• Bekleyen sipariş temizliği zamanlanmış ve süre eşiği gözden geçirilmiş.
• Sayfa, gezinme, iletişim bilgileri ve etkin dil sürümleri önizlenmiş.

Gerçek ödemeye bilinçli olarak geçtiğinizde gerçek satıcının live kimlik bilgilerini, eşleşen canlı modu ve doğru canlı webhook ayarlarını kullanın. Sandbox ve canlı bilgiler veya webhook kimlikleri birbirinin yerine kullanılamaz. Etkin ağ geçidini ve hazırlığını tekrar doğrulayıp normal inceleme ve yayımlama iş akışınızı izleyin.

Sayfayı yayımlamak satıcı hesabını yapılandırmaz. Ağ geçidini değiştirmek de yayımlamadan ayrı bir işlemdir ve ödeme akışını hemen etkiler.

Ürünü hazırlarken Draft, satın almaya hazır olduğunda Active kullanın. Yeni satın almaları durdurmak istediğinizde ürünü arşivleyin; ürünü göstermeye devam eden sayfa ve bağlantıları gözden geçirin. Geçmiş sipariş kalemleri kaydedilmiş adlarını ve tutarlarını korur.

Eklentiyi güncellemeden önce sürüm notlarını ve uyumluluk bilgisini okuyun, normal kurulum sürecinizle yedek alın ve ardından sepet/ödeme testini tekrarlayın. Güncel CMS sürümleri eklenti veritabanı değişikliklerini güncelleme ve etkinleştirme sırasında uygular.

Commerce'i devre dışı bırakmak yollarını, menülerini, ayarlarını ve katkılarını etkisizleştirir. Çalışan mağazada bunu yapmadan önce ziyaretçileri, yerleştirilmiş Commerce bloklarını ve sağlayıcı geri bildirimlerini planlayın. Devre dışı yüklenmiş paketi kaldırmak eklenti veritabanı tablolarını korur; sipariş verisi temizleme işlemi değildir.

Temel akış artık hazır: ürün → CMS sayfası → sepet → ödeme → sipariş inceleme. Otomasyon ve ileri tanılama için Commerce başvuru belgelerine, günlük sayfa, medya ve ekip işleri için tüm rehberlere geçebilirsiniz.