VibeFox NZ Post for WooCommerce — Yardım

Gereksinimler

WordPress: 5.8 veya üzeri.

WooCommerce: 5.0 veya üzeri, kurulu ve etkin. WooCommerce olmadan eklenti etkinleştirilemez.

PHP: 8.0 veya üzeri.

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 bir 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ı ve auth code (veya site code). Yalnızca sabit fiyat kullanıyorsanız API erişimi gerekmez.

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

Kurulum

1. WordPress'te Plugins > Add New > Upload Plugin bölümüne gidin, eklentinin ZIP dosyasını seçin ve Install Now düğmesini tıklayın. vfd_nz_post klasörünü FTP ile /wp-content/plugins/ dizinine de yükleyebilirsiniz.

2. Activate düğmesini tıklayın.

3. Ayarları açın: WooCommerce > Settings > Shipping > VibeFox NZ Post, ya da Plugins sayfasında eklenti adının altındaki Settings bağlantısını tıklayın.

4. Sayfanın üstündeki lisans bloğuna VibeFox lisans anahtarınızı girin ve Activate düğmesini tıklayın.

5. Gerçek zamanlı ücretler için NZ Post API (live rates) bölümünü doldurun. İsteğe bağlı olarak sabit fiyatları girebilirsiniz; bunlar gerçek zamanlı ücretler olmadan ve yedek olarak kullanılır (bkz. Yapılandırma).

6. WooCommerce > Settings > Shipping > Shipping zones bölümünden VibeFox NZ Post seçeneğini bir kargo bölgesine ekleyin ya da Ignore shipping zones seçeneğini açıp ülkeleri seçin.

Yapılandırma

Tüm ayarlar tek bir sayfada bulunur: WooCommerce > Settings > Shipping > VibeFox NZ Post. Bu ayarlar tüm kargo bölgeleri için geçerlidir. Yöntemi bir bölgeye eklediğinizde, bölge penceresinde yalnızca bir alan bulunur:

Title (zone): bu bölge için müşterilerin gördüğü ad. Genel Method title değerini kullanmak için boş bırakın.

Ayarları her kaydettiğinizde, önbelleğe alınmış NZ Post ücretleri ve erişim jetonları silinir. Gerçek zamanlı ücretler kayıtlı değerlerle çalışamıyorsa (Client ID ve Client Secret'ten yalnızca biri doluysa, NZD dönüşüm kuru yoksa, iç hat ücretleri için bilgiler eksikse), ayarların üstünde bir uyarı belirir.

General

Enable/Disable: yöntemi tüm bölgelerde aynı anda açar veya kapatır.

Method title: sepette ve ödeme sayfasında gösterilen kargo yöntemi adı. Bir bölge bunu geçersiz kılabilir. Varsayılan: NZ Post.

Tax status: Taxable WooCommerce vergisini kargo ücretine ekler, None eklemez. Aşağıdaki API prices bölümüne de bakın.

NZ Post API (gerçek zamanlı ücretler) (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 istemci kimliği.

Client Secret: OAuth2 istemci gizli anahtarı. Süresi dolana kadar önbelleğe alınan bir erişim jetonuyla değiştirilir.

Account number: NZ Post iş (fatura) hesap numaranız. Yeni Zelanda içi ücretler için zorunludur. Uluslararası ücretler için isteğe bağlıdır; girildiğinde NZ Post sözleşme ücretlerinizi döndürür.

Auth code: iç hat ücretleri için hesabın auth code değeri. Site code girerseniz gerekmez.

Site code: auth code'a alternatif: NZ Post teslim noktanızın site kodu.

Ship-from suburb: kolilerin gönderildiği adresin semti, ö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 hizmetler fiyatlandırılır. Koli için NZ Post'un 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. Tax status Taxable olduğunda, GST'nin iki kez alınmaması için Excluding GST seçin.

NZD → (store currency) rate: NZ Post fiyatları NZD cinsindendir. Mağaza para biriminiz NZD değilse, bir NZD'nin kaç birim para biriminize denk geldiğini girin, örneğin 0.55. Bu değer olmadan gerçek zamanlı ücretler kullanılmaz. Aynı kur, uluslararası isteklerle gönderilen sipariş tutarını da çevirir. Mağaza para biriminiz NZD ise alanı boş bırakın.

Gerçek zamanlı ücretler için koli

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 uzunluk ve genişliğini alır; yüksekliği, 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.

Sabit fiyatlar (gerçek zamanlı ücretler ayarlanmamışsa ya da NZ Post ücret döndürmezse kullanılır)

Fiyatlar mağaza para birimindedir.

Country prices: hedef ülke başına bir satır. Satır eklemek için + Add country düğmesini, satırı silmek için çarpı işaretini 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ı bulunur: ≤ 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ş ya da 0 olan sütun Any weight değerini kullanır. Any weight fiyatının 0 olması, o ülkeye ücretsiz kargo anlamına gelir. Hem "9.99" hem de "9,99" kabul edilir. Hiçbir fiyatı olmayan satırlar, geçersiz ülke kodları ve negatif fiyatlar kaydederken silinir. Ülke başına yalnızca bir satır tutulur.

Fallback cost: API'den de ülke tablosundan da fiyat gelmediğinde kullanılır. Bu durumda yöntemi gizlemek için boş bırakın.

Fixed price per: Order fiyatı bir kez alır. Item (price × quantity) 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.

Koşullar

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

Max cart weight (kg): sepet bundan ağırsa yöntemi gizler. Varsayılan: 25 (NZ Post kurye kolileri 25 kg'a kadar gelir). 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. Her zaman göstermek için boş bırakın.

Excluded shipping classes: sepette bu WooCommerce kargo sınıflarından birine ait bir ürün varsa yöntemi gizler.

Free shipping from: NZ Post teslimatının ücretsiz olduğu sepet ara toplamı. Yalnızca yöntemin bir fiyatı olduğunda geçerlidir: ülke fiyatı veya yedek ücret (bu durumda NZ Post'a istek gönderilmez) ya da gerçek zamanlı ücret. 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.

Kargo bölgeleri olmadan kullanılabilirlik

Ignore shipping zones: yöntem hiçbir kargo bölgesine eklenmemiş olsa bile, NZ Post'u aşağıdaki ülkeler için sunar.

Countries: bu mod için hedef ülkeler. Gönderim yaptığınız tüm ülkeleri kullanmak için boş bırakın. Bu alan yalnızca Ignore shipping zones açıkken kullanılır.

Gelişmiş

Debug log: ücret hesaplamalarını WooCommerce > Status > Logs sayfasına yazar (kaynak "vfd-nz-post"). 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.

Remove data on uninstall: açık olduğunda eklentiyi silmek, ayarlarını, bölge yöntemlerini ve önbelleğe alınmış ücretlerini kaldırır. Eklentiyi devre dışı bırakmak hiçbir şeyi silmez.

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

Müşteri bir teslimat adresi girdiğinde WooCommerce eklentiden bir ücret ister. Eklenti önce koşulları kontrol eder: teslimat ülkesi, sepet ağırlığı, minimum sipariş tutarı ve hariç tutulan kargo sınıfları. Ardından bir fiyat arar: önce NZ Post gerçek zamanlı ücreti, sonra ülke tablosu ve son olarak yedek ücret. Fiyat yoksa yöntem gizlenir. Ücretsiz kargo geçerliyse müşteri yöntemi ücretsiz görür.

Gerçek zamanlı ücretler ayarlıysa eklenti, Client ID ve Client Secret'inizle 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, ayrıca koli ağırlığını ve boyutunu gönderir. WooCommerce'te semt alanı yoktur: eklenti, Address line 2 alanında bir semt adı varsa onu kullanır, yoksa kasaba veya şehri kullanır. İç hat ücreti yalnızca müşteri bir şehir ve 4 haneli posta kodu girdikten sonra istenir. Diğer ülkeler için hedef ülkeyi, koli ağırlığını ve boyutunu ve sipariş tutarını NZD cinsinden gönderir.

Ek ücretler ve zorunlu ek hizmetler dahil, fiyatı olan ve izin verilen en ucuz hizmet kullanılır. Fiyat NZD'den mağaza para biriminize çevrilir. Fiyatlandırılan hizmet, siparişle birlikte NZ Post service olarak kaydedilir ve sipariş ekranında görünür. 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 dolmuş bir erişim jetonu otomatik olarak yenilenir.

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

Yöntem klasik ödeme sayfasında ve Sepet ve Ödeme bloklarında çalışır. WooCommerce High-Performance Order Storage (HPOS) ile uyumludur.

Eklenti yalnızca ücret hesaplar. Kargo etiketi oluşturmaz, kurye talebi açmaz, manifesto hazırlamaz, 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 hizmet listesi değil, tek bir NZ Post ücreti görür.

Lisans anahtarı

Eklenti, vibefox.net'ten alınmış bir VibeFox lisans anahtarıyla çalışır. Lisans bloğu WooCommerce > Settings > Shipping > VibeFox NZ Post sayfasının üstündedir. Anahtarı License key alanına yapıştırın ve Activate düğmesini tıklayın. Blokta durum görünür; örneğin lisansın hangi tarihe kadar etkin olduğu ve alan adınız. Durumu yeniden kontrol etmek için Check now, başka bir anahtar girmek için Change key, anahtarı bu siteden kaldırmak için Remove key düğmesini kullanın. Manage licenses and domains in your account bağlantısı vibefox.net hesabınızı açar.

Bir anahtar bir alan adında çalışır. Anahtarı bir siteden kaldırmak, o sitenin alan adı hakkını serbest bırakmaz. Bunu vibefox.net hesabınızdan serbest bırakın.

Etkin bir anahtar yoksa NZ Post ödeme sayfasında müşterilere gösterilmez. Oturum açmış mağaza yöneticileri yöntemi yine görür; yanında (unlicensed — visible to admins only) ibaresi bulunur. Böylece bir anahtar satın almadan önce eklentiyi kurup test edebilirsiniz. Plugins sayfasında ve WooCommerce sayfalarında bir hatırlatma belirir. 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 arka planda otomatik olarak yeniden kontrol edilir.

Sorun giderme

NZ Post ödeme sayfasında görünmüyor: lisansın etkin olduğunu, Enable/Disable seçeneğinin açık olduğunu ve yöntemin müşterinin ülkesinin bölgesine eklendiğini kontrol edin (ya da Ignore shipping zones açık ve ülke izinli olmalı). Ağırlık sınırlarını, Minimum order amount değerini ve Excluded shipping classes ayarını kontrol edin. NZ Post ücret döndürmüyorsa yöntem yalnızca bir ülke fiyatıyla veya bir Fallback cost ile gösterilir.

Gerçek zamanlı ücretler görünmüyor: WooCommerce > Status > Logs sayfasını, kaynak "vfd-nz-post" olacak şekilde açın. API hataları her zaman orada bulunur. Ayrıntılar için Debug log seçeneğini açın. Günlük nedeni gösterir: Client ID veya Client Secret eksik, jeton reddedildi, hesap veya gönderici adresi verisi eksik, müşterinin şehri veya posta kodu henüz yok, NZD kuru yok ya da 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.

İç hat ücretleri yok, uluslararası ücretler çalışıyor: Yeni Zelanda içi ücretler için Account number, Auth code veya Site code ile 4 haneli posta kodu içeren tam gönderici adresi gerekir. Müşterinin bir şehir ve 4 haneli posta kodu girmesi gerekir. Geliştiriciler, teslimat adresi için gönderilen semti vfd_nzpt_delivery_suburb filtresiyle değiştirebilir.

Mağazam NZD kullanmıyor: NZD → (store currency) rate değerini girin. Sabit fiyatlar her zaman mağaza para birimindedir.

Kargoda GST iki kez alınıyor: NZ Post iç hat fiyatları %15 GST içerir. Tax status Taxable ise API prices değerini Excluding GST olarak ayarlayın.

Bir değişiklikten sonra ücretler eski görünüyor: ayarlar sayfasını kaydedin. Bu, önbelleğe alınmış NZ Post ücretlerini ve jetonları temizler.

Lisans bloğu hata gösteriyor: bloktaki mesajı izleyin. Örneğin anahtar başka bir alan adında zaten kullanılıyorsa, vibefox.net hesabınızda bir yer açın ve Check now düğmesini tıklayın. Site adresi değiştiyse, anahtarı yeni alan adı için etkinleştirmek üzere Check now düğmesini tıklayın. Lisans sunucusuna ulaşılamıyorsa eklenti son bilinen durumla çalışmaya devam eder.

Kaldırma

Eklentiyi devre dışı bırakmak tüm verileri korur. Kaldırmak için Plugins sayfasında devre dışı bırakın ve silin. Bu eklentinin lisans anahtarı ve lisans durumu her zaman silinir. Ayarlar, bölge yöntemleri, önbelleğe alınmış ücretler ve erişim jetonları yalnızca Remove data on uninstall açıksa silinir. Aksi halde, daha sonraki bir yeniden kurulum için saklanır. Mevcut siparişler kargo satırlarını korur.

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