VibeFox PostNL for OpenCart — Yardım

Gereksinimler

OpenCart: 3.0.x (3.0.5.0 üzerinde test edildi) veya 4.0.2 ve üzeri (4.1.0.3 üzerinde test edildi).

PHP: 8.0 veya üzeri.

PostNL API anahtarı (yalnızca teslim alma noktaları için): teslim alma noktaları PostNL Checkout API'sinden yüklenir. PostNL işletme müşterileri API anahtarını Mijn PostNL içinde My account > API beheren altında bulur. PostNL test ortamı (sandbox) ayrı bir test anahtarı gerektirir. Ev teslimatı seçeneği anahtar gerektirmez.

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

Kurulum

İndirme dosyası, 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_postnl-oc3-(version).ocmod.zip ve OpenCart 4 paketi vfd_postnl.ocmod.zip bulunur. Yalnızca kullandığınız OpenCart sürümünün paketini kurun. Lisans anahtarı iki sürüm için de aynıdır.

OpenCart 3

1. Yönetici panelinde Extensions > Installer bölümüne gidin, Upload düğmesine tıklayın ve vfd_postnl-oc3-(version).ocmod.zip dosyasını seçin. Eklenti OCMOD değişiklikleri eklemez, bu nedenle Extensions > Modifications bölümü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 bölümüne gidin ve eklenti türü olarak Shipping seçin. VibeFox PostNL eklentisini 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. VibeFox lisans anahtarınızı License key alanına, Edit sayfasının en üstündeki lisans bloğuna girin ve Activate düğmesine tıklayın (bkz. Lisans anahtarı).

5. PostNL pickup point ve/veya PostNL home address seçeneğini açın ve fiyatları girin. Teslim alma noktaları için ayrıca PostNL API key değerini ve Ship from (postcode) alanını girin (bkz. Yapılandırma). Save düğmesine tıklayın.

OpenCart 4

1. Yönetici panelinde Extensions > Installer bölümüne gidin, Upload düğmesine tıklayın ve vfd_postnl.ocmod.zip dosyasını seçin. Dosya adını değiştirmeyin: OpenCart 4 eklenti kodunu dosya adından alır, adı değiştirilmiş paket çalışmaz.

2. Paket, aynı sayfadaki kurulu eklentiler listesinde görünür. Yanındaki Install düğmesine (yeşil +) tıklayın.

3. Extensions > Extensions sayfasına gidin ve eklenti türü olarak Shipping seçin. VibeFox PostNL eklentisini bulun, Install düğmesine (yeşil +) ve sonra Edit düğmesine (kalem düğmesi) tıklayın.

4. Lisans anahtarını ve ayarları OpenCart 3'teki 4. ve 5. adımlarda olduğu gibi girin. Ayar sayfası ve alanları iki sürümde de aynıdır.

Kurulumdan sonra, bunlardan birini açıp kaydedene kadar iki seçenek de kapalı kalır. Eklentiyi kaldırdıktan sonra yeniden kurarsanız, sakladığınız PostNL ayarları yeniden kullanılır.

Yapılandırma

Tüm ayarlar eklenti sayfasındadır: Extensions > Extensions > Shipping > VibeFox PostNL > Edit. Bölümler solda listelenir. Sayfanın altındaki tek bir Save düğmesi, tüm sayfayı yeniden yüklemeden kaydeder. Ayarları yalnızca bu eklenti için değiştirme yetkisi olan yönetici kullanıcılar kaydedebilir.

Bir değer yanlışsa hiçbir şey kaydedilmez ve sayfa nedenini gösterir: boş bir seçenek adı, 64 karakterden uzun veya < > ; = # { } içeren bir ad, tam sayı olmayan bir sıralama, maksimum ağırlıktan büyük bir minimum ağırlık veya geçersiz bir vergi sınıfı ya da coğrafi bölge. Daha küçük sorunlar bir notla kaydedilir: geçersiz veya negatif bir sayı alanını boş bırakır, geçersiz bir gönderen posta kodu boş kaydedilir ve tablodaki geçersiz bir fiyat yok sayılır.

Ayarların üstünde sayfa uyarılar gösterir: teslim alma noktaları için eksik bir API anahtarı veya gönderen posta kodu, açık test ortamı (sandbox), ayarlanmış bir fiyat olmaması, tarih ve hatasıyla birlikte son başarısız PostNL isteği veya "kg" ağırlık sınıfı olmayan bir mağaza.

Genel

Her teslimat türü ödeme sayfasında ayrı bir seçenektir. Bu sayfadaki ayarlar ikisi için de geçerlidir.

PostNL pickup point: teslim alma noktası seçeneğini açar veya kapatır. Müşteri ödeme sayfasında bir PostNL noktası seçmelidir. Yalnızca Hollanda ve Belçika adresleri için ve yalnızca API anahtarıyla sunulur. Varsayılan: kapalı.

Pickup point option name: müşterinin ödeme sayfasında gördüğü ad. Varsayılan: PostNL pickup point. Zorunlu, en fazla 64 karakter, < > ; = # { } içermeden.

PostNL home address: ev teslimatı seçeneğini açar veya kapatır. Nokta seçilmez. Fiyatı olan her ülkede çalışır. Varsayılan: kapalı.

Home delivery option name: müşterinin ödeme sayfasında gördüğü ad. Varsayılan: PostNL. Teslim alma noktası adıyla aynı kurallar geçerlidir.

Sort order: ödeme sayfasındaki kargo yöntemleri arasında PostNL'in konumu. Tam sayı.

Tax class: iki seçeneğin vergi sınıfı. Bir vergi sınıfı seçildiğinde OpenCart fiyatların üzerine kendi vergisini ekler. No tax fiyatların kesin olduğu anlamına gelir.

PostNL API (teslim alma noktaları) (ev teslimatı için gerekli değildir)

API key: Mijn PostNL içindeki (My account > API beheren) PostNL API anahtarınız. "apikey" başlığıyla PostNL'e gönderilir ve müşterilere asla gösterilmez ya da 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 için yeni bir değer girin.

Remove the saved API key: kutuyu işaretleyip Save düğmesine tıklayarak kayıtlı anahtarı silin. Bundan sonra teslim alma noktası seçeneği sunulmaz.

Sandbox: bir sandbox API anahtarıyla PostNL test ortamını (api-sandbox.postnl.nl) kullanır. Bu durumda müşteriler test teslim alma noktaları görür. Canlı bir mağazada kapalı tutun.

Ship from (country): paketlerinizi PostNL'e teslim ettiğiniz ülke: Hollanda veya Belçika. PostNL, teslim alma tarihi için gönderen adresini kullanır. Kurulumda, mağaza ülkesi Hollanda veya Belçika ise o ülke seçilir, aksi halde Hollanda seçilir.

Ship from (postcode): gönderen posta kodu, örneğin Hollanda'da 1234AB veya Belçika'da 1000. Teslim alma noktaları için zorunludur: OpenCart'ta mağaza posta kodu olmadığı için mağaza adresinden alınmaz. Geçersiz bir posta kodu bir uyarıyla boş kaydedilir.

API anahtarını, sandbox ayarını veya gönderen adresini değiştirdiğinizde, önbelleğe alınmış teslim alma noktası listeleri ve son API hatası temizlenir.

Fiyatlar (mağazanın varsayılan para biriminde, vergi hariç)

Fiyatlar iki seçenek için de geçerlidir. PostNL herkese açık bir ücret API'si sunmadığı için eklenti canlı ücret sorgulamaz. Başka bir para birimiyle ödeme yapan bir müşteri için OpenCart, fiyatı mağazanızın kur oranıyla dönüştürür.

Price per country: hedef ülke başına bir satır. Satır eklemek için Add country düğmesine, satır silmek için × düğmesine tıklayın. Kendi satırı olmayan tüm ülkeleri kapsayan bir satır için * All other countries seçin. Her satırda bir Price ve sepet ağırlığına göre isteğe bağlı ağırlık sınıfları bulunur: XS 1 kg'a kadar, S 2 kg'a kadar, M 3 kg'a kadar, L 5 kg'a kadar ve XL 5 kg'ın üzeri. Bir ağırlık sınıfının fiyatı Price yerine geçer; Price kullanmak için boş bırakın. 0 olan bir Price ücretsiz kargo anlamına gelir. "6.95" ve "6,95" kabul edilir. Fiyatı olmayan satırlar kaydedilirken silinir. Bir ülke iki kez geçiyorsa yalnızca ilk satır tutulur. Geçersiz fiyatlar bir uyarıyla yok sayılır.

Calculation: Per order fiyatı bir kez alır. Per item (price x quantity) ise kargo gerektiren ürün adediyle çarpar.

Price for other countries: tabloda ne ülke ne de * satırı varsa kullanılır. Seçeneklerin orada gizlenmesi için boş bırakın.

Koşullar

Free shipping from: teslimatın ücretsiz olduğu sepet ara toplamı (kargo gerektiren ürünler, vergi hariç, kupon sonrası). Yalnızca bir fiyatın bulunduğu yerlerde geçerlidir. Hiçbir zaman ücretsiz kargo sunulmaması için boş bırakın.

Minimum subtotal: seçenekleri yalnızca sepet ara toplamı bu tutara ulaştığında gösterir. Her zaman göstermek için boş bırakın.

Minimum weight (kg): sepet daha hafif olduğunda seçenekleri gizler. Ürün ağırlıkları ağırlık sınıflarından dönüştürülür. Sınır olmaması için boş bırakın.

Maximum weight (kg): daha ağır sepetler için seçenekleri gizler. PostNL paketleri Benelüks'te 30 kg'a kadar gider. 0 sınır olmadığı anlamına gelir. Boş bırakırsanız 30 kg geçerli olur; Ignore shipping zones açıksa sınır olmaz.

Tüm tutarlar ve ağırlıklar ondalık virgül kabul eder.

Erişilebilirlik

Geo zone: PostNL'i yalnızca bu coğrafi bölgedeki adresler için sunar. All zones (varsayılan) sınır olmadığı anlamına gelir. Ignore shipping zones açıkken coğrafi bölge kontrol edilmez. Coğrafi bölgeler System > Localisation > Geo Zones bölümünde yönetilir.

Ignore shipping zones: açıkken coğrafi bölge kontrol edilmez ve PostNL aşağıda seçilen ülkeler için sunulur (liste boşsa tüm ülkeler için). Kapalıyken yalnızca coğrafi bölge geçerlidir.

Countries: bu mod için hedef ülkeler. Tüm ülkelere izin vermek için boş bırakın. Bu alan yalnızca Ignore shipping zones açıkken kullanılır. Teslim alma noktası seçeneği yine yalnızca Hollanda ve Belçika için sunulur.

Gelişmiş

Debug log: hata ayıklama mesajlarını storage/logs/vfd_ptnl_debug.log.php dosyasına yazar (OpenCart 4'te system/storage/logs/vfd_ptnl_debug.log.php). Dosya web üzerinden okunamaz. API hataları ve geçerli bir teslim alma noktası olmayan siparişler her zaman günlüğe yazılır. API anahtarı veya müşteri verisi yazılmaz. İşiniz bittiğinde günlüğü kapatın. Dosya 5 MB'a ulaştığında yeni bir günlük başlatılır.

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

Remove data on uninstall: açıkken eklentiyi kaldırmak PostNL ayarlarını ve günlüğü siler. Önbelleğe alınmış nokta listeleri her zaman kaldırılır. Siparişlerde kaydedilen teslim alma noktaları her zaman korunur.

İçe / Dışa Aktarma

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

İçe aktarma: 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 kaydetmedeki gibi kontrol edilir. Kayıtlı API anahtarı korunur.

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

OpenCart kargo yöntemlerini gösterdiğinde, her PostNL seçeneğinin fiyatını eklentiden ister. Ignore shipping zones açıksa PostNL, coğrafi bölgeden bağımsız olarak yalnızca izin verilen bir ülke için sunulur. Aksi halde bir Geo zone ayarlıysa adresin bu bölgede olması gerekir. Yalnızca Requires Shipping değeri Yes olan ürünler sayılır: diğer ürünler ağırlık eklemez ve ara toplama dahil edilmez. Eklenti sepet ağırlığını ve minimum ara toplamı kontrol eder. Ardından fiyatı, ülke ve ağırlık sınıfı için tablodan ya da diğer ülkeler için fiyattan alır. Fiyat yoksa seçenek gizlenir. Sepet ara toplamı Free shipping from değerine ulaşırsa fiyat 0 olur. Fiyat, müşteriye seçili Tax class vergisiyle birlikte kendi para biriminde gösterilir.

Teslim alma noktası seçeneği yalnızca Hollanda ve Belçika adresleri için ve yalnızca API anahtarıyla sunulur. Teslimat adresinde tam bir posta kodu olduğunda eklenti, PostNL Checkout API'sinden en yakın üç teslim alma noktasını ister. Müşterinin posta kodunu, sokağını ve kapı numarasını, şehrini ve ülkesini ile sizin gönderen adresinizi gönderir. Ev teslimatı seçeneği için hiçbir şey gönderilmez. PostNL'e ulaşılamazsa ya da adres için nokta yoksa teslim alma noktası seçeneği gizlenir ve ev teslimatı kullanılabilir kalır. API zaman aşımı 12 saniyedir.

Nokta listeleri adres başına 6 saat, "nokta yok" yanıtları 1 saat önbelleğe alınır. Başarısız istekler 10 dakika önbelleğe alınır; böylece bir kesinti her ödeme sayfası yenilemesini yavaşlatmaz. Önbellek eklentinin kendi veritabanı tablosunda tutulur. Son hata, bir sonraki başarılı isteğe kadar eklenti sayfasında gösterilir.

Eklenti canlı PostNL ücretlerini sorgulamaz ve gönderi etiketi, barkod, takip, iade ya da ön bildirim oluşturmaz. Teslimat günü, akşam veya sabah teslimat seçeneği yoktur. Gönderiyi, kayıtlı teslim alma noktasını kullanarak Mijn PostNL'de ya da başka bir PostNL aracında oluşturun.

OpenCart 4'te müşteri, ödeme sayfasındaki kargo yöntemi bloğunda Choose düğmesine tıklar ve Shipping method options penceresinde bir PostNL seçeneği seçer. Fiyatlar OpenCart 3'tekiyle aynıdır.

Teslim alma noktaları

Teslimat adresi Hollanda veya Belçika'daysa, teslim alma noktası seçeneğinin altında en yakın üç nokta ile birlikte bir PostNL pickup point listesi görünür: firma adı, adres ve mesafe, en yakın olan önce. Sayfa asla PostNL'i beklemez: liste henüz önbellekte değilse, seçenek seçilir seçilmez yüklenir. Tam bir posta kodu girilmeden önce müşteri "Enter your postcode (for example 1234 AB) to see PostNL pickup points." mesajını görür (Belçika için 4 rakam). Seçilen nokta, ödeme için hemen kaydedilir.

Nokta zorunludur. Müşteri kargo yöntemi adımında Continue düğmesine tıkladığında sunucu, noktayı teslimat adresi için PostNL listesiyle karşılaştırır. Nokta yoksa müşteri "Please choose a PostNL pickup point." mesajını görür. Nokta listede yoksa "The chosen PostNL pickup point is not available for this address. Please choose it again." mesajını görür. PostNL'e ulaşılamazsa "PostNL pickup points cannot be loaded right now. Please try again in a few minutes or choose another shipping method." mesajını görür. Başka bir adres için seçilen bir nokta siparişte asla kullanılmaz. Siparişle kaydedilen ad ve adres tarayıcıdan değil, PostNL'den gelir.

Sipariş sayfaları, e-postalar ve fatura: nokta, siparişin kargo yöntemine eklenir; örneğin "PostNL pickup point: ad, adres" (teslim alma noktası seçeneğinin adı, ardından nokta) (128 karakterye kadar, OpenCart 4'te 255'e kadar). OpenCart'ın kargo yöntemini gösterdiği her yerde görünür: müşterinin sipariş geçmişi, sipariş e-postaları, fatura ve Sales > Orders.

Yönetici sipariş sayfası: Sales > Orders bölümünde sipariş sayfası geçmişin üstünde noktayı, Location code değerini ve Partner ID değerini gösteren bir PostNL pickup point paneli gösterir. Yalnızca kayıtlı bir noktası olan siparişler için görünür; eklenti devre dışı bırakıldıktan sonra da görünmeye devam eder.

OpenCart 4'te liste, Shipping method options penceresinde PostNL pickup point seçeneğinin altında görünür ve pencere her açıldığında yeniden yüklenir; çünkü tek sayfalık ödemede adres değişebilir. Pencerenin Continue düğmesi, geçerli bir nokta olmadan ilerlemez; mesajlar aynıdır. OpenCart 4 ödeme için tek bir sipariş tutar ve müşteri her onaylamada onu günceller; siparişin noktası onunla birlikte güncellenir.

Lisans anahtarı

Eklenti, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. License — VibeFox PostNL lisans bloğu, Extensions > Extensions > Shipping > VibeFox PostNL > 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ı maskeli olarak, durumu (örneğin lisansın geçerli olduğu tarih ve alan adınız) ve şu düğmeleri gösterir: 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. Bunların altında Product: opencart-shipping-postnl satırı ile vibefox.net hesabınızı açan Manage licenses and domains in your account bağlantısı bulunur. Anahtarı yalnızca eklenti için Modify yetkisi olan 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 tarihiyle birlikte License expired on. Mağaza adresi değiştikten sonra ya da hesabınızda bir alan adı yuvasını boşalttıktan sonra Check now düğmesine tıklayın. Lisans sunucusuna ulaşılamazsa eklenti 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ızdan serbest bırakın.

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

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

Sorun giderme

PostNL ödeme sayfasında görünmüyor: lisansın etkin olduğunu ve PostNL pickup point ya da PostNL home address seçeneğinin açık olduğunu kontrol edin. Geo zone ayarını (ya da Ignore shipping zones açık ve ülkenin izinli olduğunu), ülke için bir fiyat tanımlandığını, ağırlık sınırlarını ve Minimum subtotal değerini kontrol edin. Ürünlerde Requires Shipping değerinin Yes olduğunu kontrol edin.

Teslim alma noktası seçeneği görünmüyor: yalnızca Hollanda ve Belçika adresleri için, yalnızca API anahtarı, gönderen posta kodu ve fiyat varsa, ayrıca PostNL müşterinin posta kodu için nokta döndürdüğünde gösterilir. Eklenti sayfasının üstündeki uyarıları ve Log alanını kontrol edin. Hatalar her zaman günlüğe yazılır; ayrıntılar için Debug log seçeneğini açın.

"PostNL pickup points cannot be loaded right now": PostNL'e ulaşılamadı, API anahtarını reddetti ya da gönderen posta kodu eksik. Eklenti sayfası son hatayı gösterir. Bir sandbox anahtarı yalnızca Sandbox açıkken, canlı bir anahtar ise yalnızca kapalıyken çalışır.

Müşteriler test teslim alma noktaları görüyor: Sandbox seçeneğini kapatın.

Ürün ağırlıkları yanlış görünüyor: eklenti sayfası mağazada "kg" ağırlık sınıfı olmadığını uyarıyorsa, System > Localisation > Weight Classes bölümünü kontrol edin. Ürün ağırlıkları sınıflarının birim adına göre dönüştürülür ve bilinmeyen birimler kilogram olarak okunur.

Sayfa "Warning: You do not have permission to modify VibeFox PostNL!" 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_postnl (OpenCart 3) veya extension/vfd_postnl/shipping/vfd_postnl (OpenCart 4) için değiştirme yetkisi verin.

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

Kaldırma

Extensions > Extensions bölümüne gidin, Shipping türünü seçin ve VibeFox PostNL yanındaki Uninstall düğmesine (kırmızı − düğmesi) tıklayın. Bu eklentinin lisans anahtarı ve lisans durumu her zaman kaldırılır. OpenCart her zaman eklenti durumunu, Sort order, Tax class ve Geo zone ayarlarını sıfırlar. Önbelleğe alınmış nokta listeleri ve son API hatası her zaman kaldırılır. Remove data on uninstall açıksa PostNL ayarları, hata ayıklama günlüğü ve hiçbir zaman siparişe dönüşmemiş ödeme işlemlerinin noktaları da silinir. Kapalıysa diğer ayarlar korunur ve eklentiyi yeniden kurduğunuzda tekrar kullanılır. Mevcut siparişler kargo yöntemini, maliyetini ve kayıtlı teslim alma noktasını korur.

OpenCart 4'te eklenti dosyalarını da silmek için kaldırma işleminden sonra Extensions > Installer bölümüne gidin, kurulu eklentiler listesinde VibeFox PostNL yanındaki Uninstall düğmesine (turuncu −) tıklayın, ardından yüklenen paketi silmek için Delete düğmesine (kırmızı çöp kutusu) tıklayın.

PostNL, ilgili sahibinin ticari markasıdır. Bu eklenti PostNL ile bağlantılı değildir ve PostNL tarafından onaylanmamıştır.