VibeFox bpost Cubee for OpenCart — Yardım

Gereksinimler

OpenCart: 3.0.x (3.0.5.0 ile test edildi) veya 4.0.2 ve sonrası (4.1.0.3 ile test edildi).

PHP: 8.0 veya üzeri.

bpost Shipping Platform hesabı (yalnızca teslim alma noktası seçici için): uzantı, teslim alma noktalarını bpost Shipping Platform API'si üzerinden arar. plugins.bpost.be adresinde bpost Shipping Platform hesabınıza giriş yapın ve anahtarları Settings > Key management bölümünde oluşturun. Üç değere ihtiyacınız vardır: Account ID (genel anahtar), Passphrase (özel anahtar) ve bir App ID (X-APPID). App ID, entegrasyonunuz için bpost tarafından verilir; bpost e-ticaret desteğine (eol@bpost.be) başvurun. Ayrıca sözleşmenizin taşıyıcı kimliğine (68 = bpost) ihtiyacınız vardır. Eksiksiz anahtarlar olmadan yöntem sabit fiyatlarla çalışmaya devam eder, ancak müşteriden teslim alma noktası seçmesi istenmez.

VibeFox lisans anahtarı: vibefox.net üzerinden satın alınır. Bir anahtar tek bir alan adında çalışır.

Kurulum

İndirme, her iki OpenCart sürümü için paketleri içeren tek bir zip dosyasıdır. Bilgisayarınızda açın. İçinde README.txt, OpenCart 3 paketi vfd_bpost_cubee-oc3-(version).ocmod.zip ve OpenCart 4 paketi vfd_bpost_cubee.ocmod.zip bulunur. Yalnızca OpenCart sürümünüze ait paketi kurun. Lisans anahtarı her iki sürüm için aynıdır.

OpenCart 3

1. Yönetici panelinde Extensions > Installer sayfasına gidin, Upload düğmesine tıklayın ve vfd_bpost_cubee-oc3-(version).ocmod.zip dosyasını seçin. Uzantı OCMOD değişikliği eklemez, bu yüzden Extensions > Modifications sayfasını yenilemeniz gerekmez. Installer yerine, paketteki upload klasörünün içeriğini mağazanızın kök klasörüne de kopyalayabilirsiniz.

2. Extensions > Extensions sayfasına gidin ve uzantı türü olarak Shipping seçin. VibeFox bpost Cubee uzantısını bulun ve Install düğmesine (yeşil + düğmesi) tıklayın.

3. Ayarlar sayfasını açmak için Edit düğmesine (kalem düğmesi) tıklayın.

4. Edit sayfasının üst kısmındaki lisans bloğunda License key alanına VibeFox lisans anahtarınızı girin ve Activate düğmesine tıklayın (bkz. Lisans anahtarı).

5. Fiyatlarınızı girin, örneğin BE=4.95 ve *=9.95; teslim alma noktası seçici için bpost API anahtarlarını da girin (bkz. Yapılandırma). Enable/Disable seçeneğini açın ve Save düğmesine tıklayın.

OpenCart 4

1. Yönetici panelinde Extensions > Installer sayfasına gidin, Upload düğmesine tıklayın ve dosya olarak vfd_bpost_cubee.ocmod.zip paketini seçin. Dosyanın adını değiştirmeyin: OpenCart 4 uzantı kodunu dosya adından alır ve adı değiştirilmiş bir paket çalışmaz.

2. Paket, aynı sayfadaki yüklü uzantılar listesinde görünür. Yanındaki Install düğmesine (yeşil + düğmesi) tıklayın.

3. Extensions > Extensions sayfasına gidin ve Shipping türünü seçin. VibeFox bpost Cubee uzantısını bulun, Install düğmesine (yeşil + düğmesi) ve ardından Edit düğmesine (kalem düğmesi) tıklayın.

4. Lisans anahtarını ve ayarları OpenCart 3 için 4. ve 5. adımlardaki gibi girin. Ayarlar sayfası ve alanları iki sürümde de aynıdır.

Kurulumdan sonra, açıp kaydedene kadar yöntem kapalı kalır. Uzantıyı kaldırdıktan sonra yeniden kurarsanız, sakladığınız ayarlar yeniden kullanılır.

Yapılandırma

Tüm ayarlar uzantı sayfasındadır: Extensions > Extensions > Shipping > VibeFox bpost Cubee > Edit. Bölümler solda listelenir. Tek bir Save düğmesi, tüm sayfayı yeniden yüklemeden kaydeder. Her kayıt, saklanan API jetonunu ve önbelleğe alınmış teslim alma noktası listelerini de temizler. Ayarları yalnızca bu uzantı için değiştirme yetkisi olan yönetici kullanıcılar kaydedebilir.

Bazı hatalar kaydetmeyi durdurur ve hiçbir şey kaydedilmez: 64 karakterden uzun bir Name, tam sayı olmayan bir Sort Order veya bilinmeyen bir vergi sınıfı ya da coğrafi bölge. Diğer sorunlar uyarı olarak bildirilir ve kalan kısım kaydedilir: sayı olmayan veya negatif bir ağırlık ya da tutar kaydedilmez ve önceki değer korunur; Min weight (kg) değeri Max weight (kg) değerinden büyükse ağırlıklar kaydedilmez; okunamayan Country prices satırları listelenir ve yok sayılır; hiçbir boyut tanınmayan bir Size prices değeri bildirilir.

Sayfanın üst kısmında, bir şey yöntemi ya da seçiciyi sessizce gizlediğinde uyarı çıkar: teslim alma noktası seçici açıktır ama API anahtarları eksiktir, Belçika (BE) için fiyat yoktur ve varsayılan fiyat da (*=FİYAT) yoktur, bpost API'sine son bağlantı başarısız olmuştur ya da mağazada "kg" birimine sahip bir ağırlık sınıfı yoktur (System > Localisation > Weight Classes). Son durumda ürün ağırlıkları birim adlarına göre okunur (kg, g, lb veya oz).

Genel

Enable/Disable: bpost paket dolabı kargosunu ödeme sayfasında açar veya kapatır. Varsayılan: kapalı.

Name: ödeme sayfasında müşteriye gösterilen kargo yönteminin adı. Varsayılan: bpost parcel locker. Boş bırakırsanız varsayılan kullanılır. En fazla 64 karakter.

Tax Class: bu sınıfın vergisi fiyatlarınıza eklenir. --- None --- (varsayılan), fiyatların kesin olduğu anlamına gelir.

Sort Order: yöntemin kargo yöntemleri listesindeki konumu.

bpost API (teslim alma noktası araması) (yalnızca teslim alma noktası seçici için gereklidir)

Account ID (public key): bpost Shipping Platform hesabınızın genel anahtarı; plugins.bpost.be üzerinde Key management bölümünde bulunur. Bu alanı temizlemek kayıtlı passphrase'i de siler.

Passphrase (private key): her isteği imzalamak için kullanılan özel anahtar (HMAC-SHA256). Asla bpost'a gönderilmez ve günlüğe yazılmaz. Kaydettikten sonra alan boş kalır ve Saved - leave empty to keep it. ifadesini gösterir. Yalnızca değiştirmek istediğinizde yeni bir değer girin.

App ID (X-APPID): bpost'un entegrasyonunuz için verdiği uygulama tanımlayıcısı. X-APPID başlığında gönderilir.

Carrier ID: teslim alma noktalarının ve paket dolaplarının listeleneceği bpost Shipping Platform sözleşmenizdeki taşıyıcı. Varsayılan: 68 (bpost). Sözleşmenizde etkin olan diğer taşıyıcıların kendi kimlikleri vardır.

Teslim alma noktası seçici

Pickup points: ödeme sayfasında teslim alma noktası ve paket dolabı seçicisini gösterir. Varsayılan olarak açıktır. Seçici yalnızca Account ID, Passphrase ve App ID alanlarının hepsi doldurulduğunda görünür ve bir noktanın seçilmesi zorunlu olur.

Search field width: posta kodu / şehir alanının CSS genişliği, örneğin 100% veya 300px. Varsayılan: 100%.

Pickup point list width: teslim alma noktası listesinin CSS genişliği, örneğin 100% veya 400px. Varsayılan: 100%.

Fiyatlar (mağazanızın varsayılan para biriminde, vergi hariç; bpost bu API üzerinden kargo fiyatı döndürmez)

Price by: fiyatın nasıl seçileceği.

Country prices: ülke başına bir satır, CC=FİYAT biçiminde, örneğin BE=4.95. *=FİYAT satırı diğer tüm ülkeler için fiyatı belirler, örneğin *=9.95. Ondalık ayırıcı olarak hem nokta hem virgül kabul edilir. Geçersiz satırlar yok sayılır. Fiyatı olmayan ülkelere (bir * satırı yoksa) yöntem sunulmaz.

Size prices: Price by paket boyutu olduğunda kullanılır, S=3.50, M=4.50, L=6.00, XL=8.00 biçiminde. Boyut sepet ağırlığından belirlenir: S 2 kg'a kadar, M 5 kg'a kadar, L 10 kg'a kadar, XL üstü.

Calculation: Per order (varsayılan) fiyatı bir kez alır. Per item (price x number of items) ise sepetteki ürün sayısıyla çarpar.

Fiyatlar mağazanızın varsayılan para biriminin ondalık basamaklarına yuvarlanır ve ardından müşterinin para biriminde gösterilir.

Koşullar

Min weight (kg): yöntemin görünmesi için gereken minimum sepet ağırlığı. Ürün ağırlıkları kg'a çevrilir. 0, sınır olmadığı anlamına gelir (varsayılan).

Max weight (kg): yöntem bu sepet ağırlığının üzerinde gizlenir. Varsayılan: 30, çünkü bpost paket dolapları 30 kg'a kadar paketleri kabul eder. 0, sınır olmadığı anlamına gelir.

Minimum order amount: yöntemi yalnızca sepet ara toplamı bu tutara ulaştığında gösterir. Ara toplam, kargo gerektiren ürünleri, kuponlardan sonra ve vergi hariç olarak sayar. Yöntemi her zaman göstermek için boş bırakın.

Ücretsiz kargo

Free shipping: aşağıdaki tutardan itibaren ücretsiz teslimatı açar.

Free shipping from: ücretsiz kargonun başladığı sepet ara toplamı (kargo gerektiren ürünler, kuponlardan sonra, vergi hariç). Yalnızca Free shipping açıkken kullanılır. Ülkenin yine de bir fiyatı olmalıdır; aksi halde yöntem sunulmaz.

Kullanılabilirlik

Normalde yöntem aşağıda seçilen coğrafi bölgede sunulur. Ignore geo zone açıkken bunun yerine listedeki ülkelerde sunulur.

Geo Zone: yöntemi yalnızca bu coğrafi bölgedeki adresler için sunar. All Zones (varsayılan) her yer anlamına gelir. Coğrafi bölgeler System > Localisation > Geo Zones bölümünde yönetilir.

Ignore geo zone: coğrafi bölgeden bağımsız olarak yöntemi aşağıdaki ülkelerde sunar.

Countries: bu mod için hedef ülkeler. Varsayılan: Belgium. Tüm ülkelere izin vermek için boş bırakın. Yalnızca Ignore geo zone açıkken kullanılır.

Gelişmiş

Debug log: API isteklerini ve fiyat hesaplamalarını storage/logs/vfd_bpst_debug.log.php dosyasına yazar. Dosya web üzerinden okunamaz. API hataları, bu seçenek kapalı olsa bile her zaman kaydedilir. Anahtarlar ve jetonlar hiçbir zaman günlüğe yazılmaz.

Log: hata ayıklama günlüğünün boyutunu ve en son kayıtlarını gösterir. Temizlemek için Clear log düğmesine tıklayın.

Remove data on uninstall: açıkken uzantıyı kaldırmak ayarları, günlüğü ve tamamlanmamış ödemelerin teslim alma noktası seçimlerini siler. Siparişlerde kaydedilmiş teslim alma noktaları her zaman korunur. Varsayılan: kapalı.

İçe / dışa aktarma

Export: ayarları bir JSON dosyası olarak kaydetmek için Download JSON düğmesine tıklayın. Passphrase dışa aktarılmaz.

Import: daha önce dışa aktarılmış JSON'u yapıştırın ve ayarları geri yüklemek için Import düğmesine tıklayın; örneğin başka bir mağazada. Değerler normal bir kayıtta olduğu gibi kontrol edilir. Kayıtlı passphrase korunur.

Ödeme sayfasında nasıl çalışır

OpenCart kargo yöntemlerini gösterdiğinde, uzantıdan bpost fiyatını ister. Bir Geo Zone ayarlıysa (ve Ignore geo zone kapalıysa) ve adres bu bölgenin dışındaysa, yöntem sunulmaz. Yalnızca Requires Shipping değeri Yes olarak ayarlanmış ürünler dikkate alınır: diğer ürünler ağırlık eklemez ve sipariş tutarına dahil edilmez. Uzantı koşulları kontrol eder: Ignore geo zone ülkeleri (açıksa), sepet ağırlığı ve minimum sipariş tutarı. Ardından fiyatı ülke listesinden veya paket boyutundan alır, ürün başına modunda ürün sayısıyla çarpar ve ücretsiz kargo uygulanıyorsa sıfırlar. Fiyat için bpost'a hiçbir istek gönderilmez.

bpost seçeneğinin altında müşteri bir Postal code or city alanı, bir Search düğmesi ve bir teslim alma noktası listesi görür. Müşteri bpost'u seçtiğinde ve liste henüz yüklenmediğinde, teslimat adresinin posta kodu (ya da müşterinin son araması) otomatik olarak aranır. Müşteri başka bir posta kodu veya şehir adı girebilir. Her nokta adı ve adresiyle gösterilir. En fazla 50 nokta listelenir. Mağaza dili Hollandaca ise liste Hollandaca, değilse Fransızca istenir.

Müşterinin bir teslim alma noktası seçmesi gerekir. Seçim yapılmazsa kargo yöntemi adımındaki Continue düğmesi Please select a bpost pickup point. uyarısını gösterir. Arama için yalnızca bpost listesindeki bir nokta kabul edilir. Aksi halde müşteri The selected bpost pickup point is not in the list of your search. Please choose another one. uyarısını görür. Arama ve seçim ödeme için saklanır, bu nedenle sayfayı yenilemek bunları kaybettirmez. Yeni bir arama önceki seçimi siler.

OpenCart 4'te müşteri, ödeme sayfasındaki teslimat yöntemi bloğunda Choose düğmesine tıklar ve Shipping method options penceresinde bpost'u seçer. Teslim alma noktası araması ve listesi bu pencerede bpost seçeneğinin altında görünür. Teslim alma noktası seçilmeden pencerede Continue düğmesine basılırsa Please select a bpost pickup point. uyarısı gösterilir. Geri kalanı OpenCart 3'teki gibi çalışır.

Teslim alma noktalarını listelemek için uzantı, bpost'a yalnızca aranan posta kodunu veya şehri, ülkeyi ve taşıyıcı kimliğini gönderir; bunlar anahtarlarınızla imzalanır. API jetonu otomatik olarak istenir ve yenilenir. bpost bir jetonu reddederse yeni bir jeton bir kez istenir ve arama tekrarlanır. Arama sonuçları en fazla 6 saat önbelleğe alınır, ancak OpenCart önbellek süresini (varsayılan 1 saat) aşmaz. bpost yanıt vermezse müşteri Pickup points cannot be loaded right now. Please try again in a few minutes or choose another shipping method. mesajını görür ve uzantı 5 dakika sonra yeniden dener. API zaman aşımı 15 saniyedir.

Uzantı yalnızca sabit fiyatları kullanır. bpost'tan anlık tarife almaz, gönderi oluşturmaz, etiket basmaz ve paketleri izlemez. Teslim alma noktaları harita üzerinde değil, liste olarak gösterilir. Gönderileri bpost Shipping Platform veya Shipping Manager hesabınızda oluşturun; teslim alma noktası kimliği yönetici sipariş sayfasındadır.

Teslim alma noktaları

Sipariş verildiğinde, seçilen teslim alma noktası siparişin kargo yöntemine bpost pickup point: olarak, noktanın adı ve adresiyle birlikte eklenir; örneğin "bpost parcel locker - bpost pickup point: …". Bu nedenle müşteri bunu sipariş onayında, hesabındaki sipariş geçmişinde, sipariş e-postalarında ve faturada görür. Kimliğiyle birlikte tam nokta, uzantının ayrı bir tablosunda da saklanır. OpenCart 4'te ödeme sayfası tek bir sipariş tutar: müşteri siparişi yeniden onayladığında, örneğin başka bir teslim alma noktası seçtikten sonra, siparişin noktası güncellenir.

Yönetici panelinde Sales > Orders altındaki sipariş sayfası, noktayı ve kimliğini içeren bpost pickup point panelini ya da No pickup point was selected for this order. mesajını gösterir. Change düğmesine tıklayın, bir posta kodu veya şehir arayın, listeden başka bir nokta seçin ve Save düğmesine tıklayın. Sipariş ve kargo yönteminin metni hemen güncellenir ve sayfa Pickup point updated. mesajını gösterir. Nokta aramanın bpost listesinde yoksa sayfa Pickup point not found in the bpost list of this search. mesajını gösterir. Debug log açıksa değişiklik hata ayıklama günlüğüne yazılır. Change yalnızca API anahtarları doldurulmuşsa ve yönetici kullanıcı siparişleri değiştirebiliyorsa kullanılabilir; uzantı ayarlarına erişim gerekmez.

Paket dolabı ve evine teslimatı birlikte sunmak için evine teslimat için başka bir kargo yöntemi kullanın. Teslim alma noktası seçici yalnızca bpost seçeneğinin altında görünür.

Lisans anahtarı

Uzantı, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. License — VibeFox bpost Cubee lisans bloğu, Extensions > Extensions > Shipping > VibeFox bpost Cubee > Edit sayfasında ayarların üstündeki ilk bloktur. Anahtarı License key alanına girin ve Activate düğmesine tıklayın. Bundan sonra blok, anahtarı maskelenmiş olarak, durumu (örneğin lisansın geçerli olduğu tarih ve alan adınızı) ve durumu yeniden kontrol etmek için Check now, başka bir anahtar girmek için Change key ve anahtarı bu mağazadan kaldırmak için Remove key düğmelerini gösterir. Bunların altında Product: opencart-shipping-bpost-cubee satırı ve Manage licenses and domains in your account bağlantısı bulunur; bu bağlantı vibefox.net hesabınızı açar. Anahtarı yalnızca bu uzantı için Modify yetkisine sahip yönetici kullanıcılar değiştirebilir. Bloğun metinleri yönetici dilini izler (İngilizce ve Rusça dahildir).

Anahtar kabul edilmezse blok nedenini gösterir; örneğin Key not found, This key belongs to another product, Domain limit reached veya tarihle birlikte License expired on. Mağaza adresi değiştikten sonra veya hesabınızda bir alan adı yuvasını serbest bıraktıktan sonra Check now düğmesine tıklayın. Lisans sunucusuna ulaşılamazsa uzantı son bilinen durumla çalışmaya devam eder.

Bir anahtar tek bir alan adında çalışır: OpenCart yapılandırmasındaki mağaza adresi. Anahtarı mağazadan kaldırmak alan adı yuvasını serbest bırakmaz. Yuvayı vibefox.net hesabınızda serbest bırakın.

Etkin bir anahtar olmadan bpost ödeme sayfasında müşterilere gösterilmez ve hiçbir fiyat hesaplanmaz. Yönetici paneline aynı tarayıcıda giriş yapmış bir yönetici kullanıcı, yöntemi yine de mağazada (unlicensed — visible to admins only) işaretiyle görür; böylece bir anahtar satın almadan önce uzantıyı kurup test edebilirsiniz. OpenCart 4'te bu önizleme yoktur: mağaza yönetici girişini görmez, bu nedenle etkin anahtar yoksa yöntem herkesten gizlenir. Edit sayfasını bir kez açtıktan sonra yönetici Dashboard sayfasında bir hatırlatma görünür. Bunu × ile kapatarak 7 gün gizleyebilirsiniz. Mevcut siparişler etkilenmez.

Bir lisansın süresi dolduğunda uzantı çalışmaya devam eder, ancak güncellemeler ve destek için yenileme gerekir. Yönetici Dashboard sayfasını veya Edit sayfasını açtığınızda durum otomatik olarak yeniden kontrol edilir: anahtar girildikten sonraki ilk 14 gün boyunca günde bir kez, sonra haftada bir kez. Cron işi gerekmez. Uzantıyı kaldırmak her zaman lisans anahtarını ve lisans durumunu siler.

Sorun giderme

bpost ödeme sayfasında görünmüyor: lisansın etkin olduğunu ve Enable/Disable seçeneğinin açık olduğunu kontrol edin. Geo Zone ayarını kontrol edin veya Ignore geo zone açık olup ülkenin Countries listesinde olduğunu doğrulayın. Ülkenin bir fiyatı olduğunu veya bir *=FİYAT satırı bulunduğunu, ayrıca ağırlık sınırlarını ve Minimum order amount değerini kontrol edin. Ürünlerde Requires Shipping değerinin Yes olduğunu doğrulayın. Belçika'nın fiyatı yoksa ayarlar sayfası bir uyarı gösterir.

Ödeme sayfasında teslim alma noktası seçici yok: Pickup points seçeneğinin açık olduğunu ve Account ID (public key), Passphrase (private key) ve App ID (X-APPID) alanlarının hepsinin dolu olduğunu kontrol edin. Anahtarlar eksikse ayarlar sayfası bir uyarı gösterir.

Müşteriler "Pickup points cannot be loaded right now" mesajını görüyor: bpost yanıt vermedi ya da anahtarları reddetti. Neden, ayarlar sayfasının üst kısmında ve hata ayıklama günlüğünde gösterilir (uzantı sayfasındaki Log alanı). Uzantı 5 dakika sonra otomatik olarak yeniden dener. Ayarları kaydetmek hemen yeniden dener.

Bu posta kodu veya şehir için teslim alma noktası bulunamadı: bpost bu arama için nokta döndürmedi. Müşteriden yakın bir posta kodu veya şehir adı denemesini isteyin ve Carrier ID değerini kontrol edin.

Virgüllü fiyatlar kullanılmıyor: hem 5,50 hem de 5.50 kabul edilir. CC=FİYAT biçimine uymayan Country prices satırları yok sayılır; kaydettikten sonraki uyarı bunları listeler.

Fiyatlara vergi dahil mi? Tax Class --- None --- olarak ayarlıysa fiyatlar kesindir. Bir vergi sınıfıyla OpenCart bu vergiyi fiyatlarınızın üzerine ekler.

Sayfa "Warning: You do not have permission to modify VibeFox bpost Cubee!" diyor: yönetici kullanıcı grubunuz ayarları yalnızca görüntüleyebilir. Gruba, System > Users > User Groups bölümünde extension/shipping/vfd_bpost_cubee (OpenCart 3) veya extension/vfd_bpost_cubee/shipping/vfd_bpost_cubee (OpenCart 4) için değiştirme yetkisi verin.

Geliştiriciler için: bpost API adresi, vfd_bpst_api_url ayarıyla (testler için) değiştirilebilir; ayarlar sayfasında bunun bir alanı yoktur.

Kaldırma

Extensions > Extensions sayfasına gidin, Shipping türünü seçin ve VibeFox bpost Cubee yanındaki Uninstall düğmesine (kırmızı − düğmesi) tıklayın. Bu uzantının lisans anahtarı ve lisans durumu her zaman kaldırılır. OpenCart her zaman Enable/Disable, Sort Order, Tax Class ve Geo Zone ayarlarını sıfırlar. Saklanan API jetonu ve önbelleğe alınmış teslim alma noktası listeleri her zaman silinir. Remove data on uninstall açıksa ayarlar, günlük ve tamamlanmamış ödemelerin teslim alma noktaları da silinir. Kapalıysa diğer ayarlar korunur ve uzantıyı yeniden kurduğunuzda tekrar kullanılır. Siparişlerde kaydedilmiş teslim alma noktaları sipariş geçmişinin parçasıdır ve asla silinmez. Mevcut siparişler kargo yöntemini ve maliyetini korur.

OpenCart 4'te dosyaları da kaldırmak için, kaldırma işleminden sonra Extensions > Installer sayfasına gidin, yüklü uzantılar listesinde VibeFox bpost Cubee yanındaki Uninstall düğmesine (turuncu − düğmesi) ve ardından yüklenen paketi silmek için Delete düğmesine (kırmızı çöp kutusu düğmesi) tıklayın.

bpost, ilgili sahibinin tescilli markasıdır. Bu uzantı bpost ile bağlantılı değildir ve bpost tarafından onaylanmamıştır.