VibeFox NZ Post for PrestaShop — Yardım

Gereksinimler

PrestaShop: 8.0 ila 9.x.

PHP: 8.0 veya üzeri. Modül, eski PHP sürümlerinde kurulmayı reddeder.

NZ Post API erişimi (yalnızca gerçek zamanlı ücretler için): gerçek zamanlı ücretler NZ Post ShippingOptions API'sini kullanır. API erişimini NZ Post web sitesindeki Developer Resource Centre üzerinden talep edin. NZ Post, önce test ortamı (UAT) için, ardından go-live kontrol listesinden sonra canlı ortam için bir Client ID ve Client Secret verir. Yeni Zelanda içi ücretler için ayrıca bir NZ Post iş hesabına ihtiyacınız vardır: hesap numarası ile auth code veya site code. Yalnızca sabit fiyat kullanıyorsanız API erişimine ihtiyacınız yoktur.

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

Kurulum

1. Yönetim panelinde Modules > Module Manager bölümüne gidin ve Upload a module düğmesine tıklayın. Modülün ZIP dosyasını seçin.

2. Yükleme bittiğinde Configure düğmesine tıklayın veya daha sonra modül listesinde VibeFox NZ Post öğesini bulup Configure düğmesine tıklayın.

3. Configure sayfasının üstündeki lisans bloğunda License key alanına VibeFox lisans anahtarınızı girin ve Activate düğmesine tıklayın (bkz. Lisans anahtarı).

4. Gerçek zamanlı ücretler için NZ Post API (live rates) bölümünü doldurun. İsterseniz sabit fiyatları da girin; bunlar gerçek zamanlı ücretler olmadan ve yedek olarak kullanılır (bkz. Yapılandırma). Save düğmesine tıklayın.

Kurulumda modül, NZ Post parcel delivery teslimat süresi metniyle birlikte NZ Post kargo firmasını oluşturur. Kargo firması tüm bölgelere ve tüm müşteri gruplarına atanır. Bölgeleri, müşteri gruplarını, teslimat süresini, logoyu ve boyut sınırlarını Shipping > Carriers bölümünden değiştirebilirsiniz. Fiyatları orada ayarlamayın: fiyat her zaman modülden gelir.

Yapılandırma

Tüm ayarlar modül sayfasındadır: Modules > Module Manager > VibeFox NZ Post > Configure. Ayarlar kargo firmasının her bölgesi için geçerlidir. Her bölümün kendi Save düğmesi vardır ve bu düğme sayfanın tamamını kaydeder. Her kayıt ayrıca önbelleğe alınmış NZ Post ücretlerini ve erişim jetonlarını temizler.

Kaydedilmiş değerlerle gerçek zamanlı ücretler çalışamadığında ayarların üstünde uyarılar görünür: Client ID ve Client Secret alanlarından yalnızca birinin dolu olması, NZD dönüşüm kurunun olmaması veya iç hat ücretleri için eksik veriler. Mağazanın ağırlık veya boyut birimini modül tanımıyorsa da uyarı görünür (bu durumda ağırlıklar kg, boyutlar cm kabul edilir). Birimleri International > Localization bölümünde (Local units) ayarlayın. Sayısal alanlar 0 veya pozitif bir sayı içermelidir; aksi halde sayfa bir hata gösterir ve hiçbir şey kaydedilmez.

General

Enable NZ Post: kargo firmasını açar veya kapatır. Bu, Shipping > Carriers bölümündeki kargo firması durumuyla aynı anahtardır.

Method title: sepette ve ödeme sürecinde gösterilen kargo firması adı. Varsayılan: NZ Post. Zorunlu, en fazla 64 karakter.

Tax: kargo firmasının vergi kuralı veya No tax (kargo ücreti vergilendirilmez). Mağaza kargoya GST ekliyorsa, GST'nin iki kez alınmaması için aşağıdaki API prices ayarını Excluding GST olarak belirleyin.

NZ Post API (live rates) (yalnızca sabit fiyat kullanmak için Client ID alanını boş bırakın)

Environment: Production (api.nzpost.co.nz) (varsayılan) veya Testing / UAT (api.uat.nzpost.co.nz). Client ID'nizin verildiği ortamı kullanın.

Client ID: NZ Post API uygulamanızın OAuth2 client ID değeri. Bunu temizlemek, kayıtlı Client Secret değerini de siler.

Client Secret: OAuth2 client secret. Süresi dolana kadar önbelleğe alınan bir erişim jetonuna dönüştürülür. Kaydettikten sonra alan boş kalır ve Saved — leave empty to keep it yazısını gösterir. Yalnızca değiştirmek istediğinizde yeni bir değer girin.

Account number: NZ Post iş (fatura) hesabı numaranız. Yeni Zelanda içi ücretler için zorunludur. Uluslararası ücretler için isteğe bağlıdır; bu numara ile NZ Post sözleşme ücretlerinizi döndürür. Bunu temizlemek, kayıtlı auth code değerini de siler.

Auth code: iç hat ücretleri için hesabın yetkilendirme kodu. Site code girerseniz gerekmez. Client Secret gibi, kaydettikten sonra tekrar gösterilmez.

Site code: auth code'a alternatif: NZ Post teslim alma site kodunuz.

Ship-from suburb: kolilerin gönderildiği adresin semti (suburb), örneğin Petone. İç hat ücretleri için gereklidir.

Ship-from city: kolilerin gönderildiği kasaba veya şehir, örneğin Lower Hutt. İç hat ücretleri için gereklidir.

Ship-from postcode: kolilerin gönderildiği 4 haneli Yeni Zelanda posta kodu, örneğin 5012. İç hat ücretleri için gereklidir.

Services: virgülle ayrılmış, isteğe bağlı NZ Post hizmet kodları, örneğin CPOLP, ICOU. Yalnızca bu hizmetlere ücret hesaplanır. NZ Post'un koli için döndürdüğü en ucuz hizmeti kullanmak için boş bırakın.

API prices: Including GST (varsayılan) veya Excluding GST. NZ Post iç hat fiyatları %15 GST içerir; uluslararası posta ücreti sıfır oranlıdır. Kargo firmasında bir vergi kuralı (yukarıdaki Tax) varsa, GST'nin iki kez alınmaması için Excluding GST seçin.

NZD → (shop currency) rate: NZ Post fiyatları NZD cinsindendir. Mağazanızın varsayılan para birimi NZD değilse, bir NZD'nin kaç birim sizin para biriminize eşit olduğunu girin, örneğin 0.55. Bu olmadan gerçek zamanlı ücretler kullanılmaz. Aynı kur, uluslararası isteklerde gönderilen sipariş tutarını da çevirir. Kur 0'dan büyük olmalıdır. Mağaza para biriminiz NZD ise alanı boş bırakın.

Parcel for live rates

Sepet NZ Post'a tek bir koli olarak gönderilir. Ürün ağırlıkları ve boyutları mağaza biriminizden kg ve cm'ye çevrilir. Koli, ürünlerin en büyük uzunluğunu ve genişliğini alır; yüksekliği ise tüm ürünlerin hacmini içerecek kadar artar. Aşağıdaki değerler ağırlığı veya boyutu olmayan ürünler için kullanılır.

Default product weight (kg): ağırlığı olmayan her ürün için kullanılır. Varsayılan: 0.5.

Default parcel length (cm): sepetteki hiçbir ürünün boyutu yoksa kullanılır. Varsayılan: 30.

Default parcel width (cm): sepetteki hiçbir ürünün boyutu yoksa kullanılır. Varsayılan: 20.

Default parcel height (cm): sepetteki hiçbir ürünün boyutu yoksa kullanılır. Varsayılan: 10.

Fixed prices (gerçek zamanlı ücretler ayarlanmamışsa veya NZ Post ücret döndürmezse kullanılır)

Fiyatlar, vergi hariç olmak üzere mağazanın varsayılan para birimindedir.

Country prices: hedef ülke başına bir satır. Satır eklemek için Add country düğmesine, satırı silmek için çöp kutusu simgesine tıklayın. Diğer tüm ülkeleri kapsayan bir satır için * Default seçin. Her satırda bir Any weight fiyatı ve isteğe bağlı ağırlık sütunları vardır: ≤ 1 kg, 1–2 kg, 2–3 kg, 3–5 kg ve > 5 kg (sepet ağırlığı). Dolu bir ağırlık sütunu Any weight değerinin yerine geçer; boş veya 0 olan sütun Any weight değerini kullanır. Any weight fiyatı 0 ise o ülkeye ücretsiz kargo anlamına gelir. «9.99» ve «9,99» biçimleri de kabul edilir. Hiçbir fiyatı olmayan satırlar ve negatif fiyatlar kaydederken silinir. Her ülke için yalnızca bir satır tutulur.

Fallback cost: ne API ne de ülke tablosu bir fiyat verdiğinde kullanılır. Bu durumda kargo firmasını gizlemek için boş bırakın.

Fixed price per: Order fiyatı bir kez alır. Item (price × quantity) ise fiyatı sepetteki ürün adediyle çarpar. Bu yalnızca sabit fiyatlar ve yedek ücret için geçerlidir. Gerçek zamanlı ücretler her zaman tüm koli için hesaplanır.

Conditions

Min cart weight (kg): sepet bundan hafifse kargo firmasını gizler. 0 sınır olmadığı anlamına gelir.

Max cart weight (kg): sepet bundan ağırsa kargo firmasını gizler. Varsayılan: 25 (NZ Post kurye kolileri 25 kg'a kadardır); boş alan da 25 anlamına gelir. 0 sınır olmadığı anlamına gelir. Ignore shipping zones açıkken boş alan, kargo firmasının kendi bölgeleri dışında sınır olmadığı anlamına gelir. Min cart weight değeri Max cart weight değerinden büyükse sayfa bir hata gösterir ve hiçbir şey kaydedilmez, çünkü kargo firması hiç gösterilmez.

Minimum order amount: kargo firmasını yalnızca sepet ara toplamı (kargo gerektiren ürünler, indirimlerden sonra, vergilerden önce) bu tutara ulaştığında gösterir. Her zaman göstermek için boş bırakın.

Free shipping from: NZ Post teslimatının ücretsiz olduğu sepet ara toplamı (indirimlerden sonra, vergilerden önce). Bu durumda NZ Post'a istek gönderilmez. Hiçbir zaman ücretsiz kargo sunmamak için boş bırakın.

Bu koşullar için sepet ağırlığında ağırlığı olmayan ürünler 0 sayılır.

Availability without shipping zones

Normalde kargo firması, Shipping > Carriers bölümünde atandığı bölgelerde gösterilir.

Ignore shipping zones: hangi bölgenin eşleştiğine bakılmaksızın, NZ Post'u aşağıda belirtilen ülkeler için sunar. Kaydederken kargo firması tüm bölgelere eklenir (sonradan oluşturulan bölgelere de). Seçeneği kapatmak, eklenen bölgeleri tekrar kaldırır.

Countries: bu mod için hedef ülkeler. Mağazanın tüm aktif ülkelerini kullanmak için boş bırakın. Bu alan yalnızca Ignore shipping zones açıkken kullanılır.

Advanced

Debug log: ücret hesaplamalarını modül klasöründeki logs/vfd_nzpt_debug.log.php dosyasına yazar. Dosya web üzerinden açılamaz. API hataları, hata ayıklama günlüğü kapalı olsa bile her zaman kaydedilir. Kimlik bilgileri, jetonlar ve müşteri adresleri kaydedilmez. İşiniz bittiğinde günlüğü kapatın.

Log: günlüğün boyutunu ve son kayıtlarını gösterir. Boşaltmak için Clear log düğmesine tıklayın.

Remove data on uninstall: açıkken modülü kaldırmak ayarları, kargo firmasını, önbelleğe alınmış ücretleri, kayıtlı sipariş ayrıntılarını ve günlükleri siler. Kapalıyken her şey yeniden kurulum için saklanır.

Ödeme sürecinde nasıl çalışır

Kargo adımında PrestaShop, modülden NZ Post ücretini ister. Yalnızca fiziksel ürünler dikkate alınır: sanal ürünler ağırlık eklemez ve sipariş tutarına dahil edilmez. Modül önce koşulları kontrol eder: izin verilen ülkeler (Ignore shipping zones ile), sepet ağırlığı ve minimum sipariş tutarı. Ücretsiz kargo geçerliyse fiyat 0 olur ve NZ Post'a istek gönderilmez. Aksi halde bir fiyat arar: önce NZ Post gerçek zamanlı ücreti, sonra ülke tablosu ve son olarak yedek ücret. Hiçbir fiyat yoksa kargo firması gizlenir.

Gerçek zamanlı ücretler ayarlandığında modül, Client ID ve Client Secret bilgilerinizle bir erişim jetonu alır ve NZ Post'tan bir fiyat ister. Yeni Zelanda'daki bir adres için hesap bilgilerinizi, gönderici adresini, müşterinin semtini, şehrini ve posta kodunu ve koli ağırlığı ile boyutunu gönderir. PrestaShop'ta semt alanı yoktur: modül, Address line 2 alanında bir semt adı varsa (rakam içermeyen) onu kullanır, yoksa şehri kullanır. İç hat ücreti, müşteri bir şehir ve 4 haneli posta kodu girdikten sonra istenir. Diğer ülkeler için hedef ülke, koli ağırlığı ve boyutu ile sipariş tutarını NZD cinsinden gönderir.

Ek ücretler ve zorunlu ek hizmetler dahil, fiyatı olan en ucuz izin verilen hizmet kullanılır. Fiyat, NZD'den mağazanın varsayılan para birimine çevrilir ve ardından müşterinin sepet para biriminde gösterilir. Her yanıt 1 saat önbelleğe alınır. Başarısız bir istek 10 dakika önbelleğe alınır, böylece ödeme sayfası her yenilemede NZ Post'u beklemez. API zaman aşımı 10 saniyedir. Süresi dolan erişim jetonu otomatik olarak yenilenir.

NZ Post bir ücret döndürmezse (API ayarlanmamış, hata, eksik adres, hizmet kullanılamıyor, NZD kuru yok), müşteri bir hata görmez. Ülke tablosundaki fiyat, ardından yedek ücret kullanılır. Sabit fiyat yoksa kargo firması gizlenir. Nedeni günlüğe yazılır.

Shipping > Carriers bölümünde kargo firmasında sipariş olduktan sonra düzenleme yaparsanız PrestaShop bunu kargo firmasının yeni bir sürümü olarak kaydeder. Modül yeni sürümü otomatik olarak izler.

Modül yalnızca ücretleri hesaplar. Kargo etiketi oluşturmaz, kurye talebi açmaz, manifesto üretmez, kolileri takip etmez, adresleri doğrulamaz ve müşterilerin bir teslim noktası, PO Box veya parsel dolabı seçmesine izin vermez. Sepet tek bir koli olarak fiyatlandırılır ve müşteri bir hizmet listesi değil, tek bir NZ Post ücreti görür.

Siparişler

NZ Post kargo firmasıyla bir sipariş verildiğinde modül, kargo ücretinin neye dayandığını kaydeder. Yönetim panelindeki sipariş sayfasında, NZ Post service (gerçek zamanlı bir ücretin fiyatlandırılmış NZ Post hizmeti) ve Price source alanlarını içeren bir NZ Post bloğu görünür: Live rate (NZ Post ShippingOptions API), Fixed price veya Free shipping. Blok, ücretler veya ayarlar daha sonra değişse bile siparişin verildiği andaki değerleri gösterir.

Lisans anahtarı

Modül, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. License — VibeFox NZ Post lisans bloğu, Modules > Module Manager > VibeFox NZ Post > Configure sayfasındaki ilk bloktur ve ayarların üstündedir. 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 tarihi 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. Altında Product: presta-shipping-nz-post satırı ve vibefox.net hesabınızı açan Manage licenses and domains in your account bağlantısı bulunur. Anahtarı yalnızca modül için Configure yetkisi olan çalışanlar değiştirebilir. Bloğun metinleri yönetim paneli 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 modül son bilinen durumla çalışmaya devam eder.

Bir anahtar tek bir alan adında çalışır: ana mağazanın alan adında, çoklu mağaza kurulumunda da. 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 NZ Post kargo firması ödeme sürecinde müşterilere gösterilmez ve hiçbir ücret hesaplanmaz. PrestaShop vitrini yönetim paneline giriş yaptığınızı bilmez, bu yüzden kargo firması sizden de gizlenir: modülü anahtarı satın almadan önce ayarlayabilirsiniz, ancak ödeme sürecinde test edemezsiniz. Modules > Module Manager bölümünde Alerts sekmesinde bir hatırlatma görünür. Mevcut siparişler etkilenmez.

Bir lisans sona erdiğinde modül çalışmaya devam eder, ancak güncellemeler ve destek için yenileme gerekir. Durum, yönetim panelinde çalışırken otomatik olarak yeniden kontrol edilir: anahtar girildikten sonraki ilk 14 gün boyunca günde bir kez, sonrasında haftada bir kez. Cron işi gerekmez. Modülü kaldırmak veya sıfırlamak her zaman lisans anahtarını ve lisans durumunu siler.

Sorun giderme

NZ Post ödeme sürecinde görünmüyor: lisansın etkin olduğunu ve Enable NZ Post seçeneğinin açık olduğunu kontrol edin. Shipping > Carriers bölümünde kargo firmasının müşterinin ülkesinin bölgesini ve müşterinin grubunu kapsadığını kontrol edin (veya Ignore shipping zones açık ve ülke izinliyse). Ağırlık sınırlarını ve Minimum order amount değerini kontrol edin. NZ Post ücret döndürmezse kargo firması yalnızca ülke fiyatı veya Fallback cost ile gösterilir. Ürünler, ürün sayfasında belirli kargo firmalarıyla da sınırlanmış olabilir.

Gerçek zamanlı ücretler görünmüyor: modül sayfasının üstündeki uyarılara bakın. Sonra Debug log seçeneğini açın, ödeme sayfasını yeniden yükleyin ve Log alanına bakın. API hataları orada her zaman bulunur. Günlük nedeni gösterir: eksik Client ID veya Client Secret, reddedilen jeton, eksik hesap veya gönderici verisi, henüz müşteri şehri veya posta kodu yok, NZD kuru yok veya fiyatlandırılmış hizmet yok. Sorunu düzeltene kadar sabit fiyatlar kullanılır.

Jeton isteği başarısız oluyor: Client ID, Client Secret ve Environment değerlerini kontrol edin. UAT kimlik bilgileri canlı ortamda çalışmaz, tersi de geçerlidir.

Yurt içi ücretler eksik, yurt dışı ücretler çalışıyor: Yeni Zelanda içi ücretler için Account number, Auth code veya Site code ve 4 haneli posta koduyla birlikte tam gönderici adresi gerekir. Müşteri bir şehir ve 4 haneli posta kodu girmelidir. Geliştiriciler, teslimat adresi için gönderilen semti actionVfdNzptDeliverySuburb kancasıyla değiştirebilir.

Mağazam NZD kullanmıyor: NZD → (shop currency) rate alanını girin. Sabit fiyatlar her zaman mağazanın varsayılan para biriminde olur.

Kargoda GST iki kez alınıyor: NZ Post iç hat fiyatları %15 GST içerir. Kargo firmasının Tax bölümünde bir vergi kuralı varsa API prices değerini Excluding GST olarak ayarlayın.

Bir değişiklikten sonra ücretler eski görünüyor: modül sayfasında Save düğmesine tıklayın. Bu, önbelleğe alınmış NZ Post ücretlerini ve jetonları temizler.

Sayfa NZ Post kargo firmasının bulunamadığını söylüyor: kargo firması Shipping > Carriers bölümünde silinmiş. Yeniden oluşturmak için Modules > Module Manager bölümünde modülü sıfırlayın.

Kaldırma

Modules > Module Manager bölümüne gidin, VibeFox NZ Post yanındaki menüyü açın ve Uninstall seçeneğini seçin. Lisans anahtarı ve lisans durumu her zaman kaldırılır. Önbelleğe alınmış ücretler ve jetonlar her zaman kaldırılır. Remove data on uninstall açıksa kargo firması silinir (siparişler geçmişini korur) ve ayarlar, kayıtlı sipariş ayrıntıları ve günlük kaldırılır. Kapalıysa kargo firması yalnızca devre dışı bırakılır ve tüm ayarlar korunur. Modülü yeniden kurmak veya bir Reset işlemi, kayıtlı kargo firmasına daha önceki durumunu (açık veya kapalı) geri verir.

NZ Post, sahibinin tescilli ticari markasıdır. Bu modül NZ Post ile bağlantılı değildir ve NZ Post tarafından onaylanmamıştır.