VibeFox USPS for OpenCart — Yardım

Gereksinimler

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

PHP: cURL uzantısına sahip 8.0 veya üzeri.

USPS Developer Portal uygulaması (yalnızca anlık tarifeler için): ücretsiz bir USPS işletme hesabıyla USPS Developer Portal'a (developers.usps.com) giriş yapın, bir uygulama oluşturun ve Consumer Key ile Consumer Secret değerlerini kopyalayın. Eklenti OAuth 2.0 ile güncel USPS API'lerini kullanır. Eski Web Tools User ID bununla çalışmaz. Anahtarlar olmadan yalnızca sabit fiyatlar kullanılır.

Gönderici posta kodu: anlık tarifeler, kolilerin gönderildiği 5 haneli ABD posta kodunu gerektirir.

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_usps-oc3-(version).ocmod.zip ve OpenCart 4 paketi vfd_usps.ocmod.zip bulunur. Yalnızca OpenCart sürümünüze uygun 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_usps-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, bu 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 eklenti türü olarak Shipping seçin. VibeFox USPS 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 simgesi) tıklayın.

4. VibeFox lisans anahtarınızı License key alanına girin, lisans bloğunda Edit sayfasının en üstünde Activate düğmesine tıklayın (bkz. License key).

5. Consumer Key ve Consumer Secret değerlerini, 5 haneli Ship from ZIP code değerini girin ve Services seçeneklerini belirleyin. Mağaza varsayılan para biriminiz USD değilse USD exchange rate değerini girin.

6. İsterseniz yedek olarak sabit fiyatları girin, Enable USPS shipping 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 vfd_usps.ocmod.zip dosyasını seçin. Dosyanın adını değiştirmeyin: OpenCart 4 eklenti kodunu dosya adından alır ve 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 + düğmesi) tıklayın.

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

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

Kurulumdan sonra, Enable USPS shipping seçeneğini açıp kaydedene kadar yöntem kapalı kalır. Eklentiyi kaldırdıktan sonra yeniden kurarsanız, sakladığınız USPS ayarları yeniden kullanılır.

Yapılandırma

Tüm ayarlar eklenti sayfasındadır: Extensions > Extensions > Shipping > VibeFox USPS > Edit. Bölümler solda listelenir. Sayfanın altındaki tek Save düğmesi tüm sayfayı yeniden yüklemeden kaydeder. Her kayıt, önbelleğe alınmış USPS belirtecini ve tarifeleri temizler. Ayarları kaydetme, önbelleği veya günlüğü temizleme yetkisi yalnızca bu eklenti için değiştirme izni olan yönetici kullanıcılardadır.

Geçersiz bir değer kaydedilmez: sayfa alanı belirtir, önceki değeri geri yükler ve The other settings were saved. mesajını gösterir. Bu; boş, çok uzun veya yasaklı karakter içeren bir ad, negatif veya sayısal olmayan bir değer, 5 haneli olmayan bir posta kodu, yanlış bir kutu boyutu, Max weight (kg) değerinden büyük bir Min weight (kg) (her iki sınır da değerlerini korur), tam sayı olmayan bir sıralama düzeni ve bilinmeyen bir vergi sınıfı veya coğrafi bölge için geçerlidir. Sayı olmayan ülke fiyatları temizlenir ve listelenir. Ayarların üstündeki uyarılar; iki anahtardan yalnızca birinin girildiğini, hiç anahtar ve sabit fiyat olmadığını (bu durumda yöntem hiç gösterilmez), posta kodunun eksik olduğunu, hiçbir hizmetin seçilmediğini, USD döviz kurunun eksik olduğunu, test ortamının açık olduğunu veya mağazanın ağırlık ya da uzunluk biriminin eklenti tarafından bilinmediğini bildirir.

Genel

Ayarlar tüm coğrafi bölgeler için geçerlidir. USPS, ödemede tek bir kargo seçeneği olarak sunulur.

Enable USPS shipping: ödemede USPS kargosunu sunar. Varsayılan: kapalı.

Name: ödemede müşteriye gösterilen kargo yöntemi adı. Varsayılan: USPS. Zorunlu, en fazla 64 karakter, < > ; = # { } karakterleri olmadan.

Tax class: kargo ücretinin vergi sınıfı. USPS fiyatları vergi içermez. No tax (varsayılan), kargonun vergilendirilmediği anlamına gelir.

Sort order: ödemedeki kargo yöntemleri arasında USPS'nin konumu. Tam sayı.

USPS API (anlık tarifeler)

Consumer Key: USPS geliştirici uygulamanızın Consumer Key (client_id) değeri. Bunu temizlemek, kayıtlı Consumer Secret değerini de kaldırır.

Consumer Secret: aynı uygulamanın Consumer Secret (client_secret) değeri. Kaydettikten sonra alan boş kalır ve Saved — leave empty to keep it. Clearing the Consumer Key removes it too. mesajını gösterir. Yalnızca değiştirmek istediğinizde yeni bir değer girin.

Test environment: gönderenler için USPS Testing Environment'ı kullanın. Yalnızca buna erişimi olan uygulamalar için. Gerçek fiyatlar için kapalı bırakın. Varsayılan: kapalı.

Prices: hangi USPS fiyat listesinin kullanılacağı.

Services: teklif verilebilecek USPS hizmetleri. USPS'in koli için sunduğu seçili hizmetlerin en ucuzu gösterilir. USPS Ground Advantage, Priority Mail / Priority Mail International, Priority Mail Express / Priority Mail Express International, First-Class Package International Service, Media Mail (books and media only) ve Library Mail (libraries and schools only) arasından seçin. Varsayılan: Ground Advantage, Priority Mail ve First-Class Package International. Flat Rate, Cubic, Hold for Pickup ve Sunday fiyatları asla kullanılmaz. Hiçbir hizmet seçilmezse anlık tarifeler kullanılmaz.

USD exchange rate: USPS fiyatları USD cinsindendir. Mağaza varsayılan para biriminiz USD değilse, 1 USD'nin sizin para biriminizdeki fiyatını girin, örneğin 0.92. 0'dan büyük olmalıdır. Bu olmadan anlık tarifeler kullanılmaz ve sabit fiyatlar uygulanır. Mağaza para biriminiz USD ise gerekli değildir. Kur otomatik olarak güncellenmez.

Cache: teklifler 1 saat, başarısız bir teklif ise 10 dakika önbellekte tutulur. Zaman aşımı, sunucu hatası, istek sınırı veya reddedilen anahtarlardan sonra USPS 5 dakika boyunca çağrılmaz. Önbelleği hemen temizlemek için Clear cached USPS token and rates düğmesine tıklayın.

Gönderim ve koli (USPS fiyatları gönderici posta koduna, ağırlığa ve koli boyutuna bağlıdır; sepet tek bir koli olarak teklif edilir)

Ship from ZIP code: kolilerin gönderildiği 5 haneli ABD posta kodu. ZIP+4 5 haneye kısaltılır. OpenCart'ta mağaza posta kodu bulunmadığı için buraya girin.

Box size (L x W x H): mağazanızın uzunluk biriminde (alan adında gösterilir) isteğe bağlı kutu boyutları, örneğin 30x20x15. Ürün boyutlarını kullanmak için boş bırakın: en uzun uzunluk, en geniş genişlik ve üst üste yığılmış yükseklikler. Boyutu olmayan ürünler 10 x 8 x 4 inçlik bir kutu olarak teklif edilir.

Default product weight (kg): ağırlığı olmayan ürünler için kullanılan ağırlık; USPS tarifelerinde, ağırlık sınırlarında ve ağırlık aralıklarında kullanılır. Varsayılan: 0.5. Boş bırakmak da 0,5 kg anlamına gelir.

Sabit fiyatlar (mağaza varsayılan para biriminizde, vergi hariç fiyatlar; API anahtarı girilmediğinde ve USPS tarife döndürmediğinde yedek olarak kullanılır; bu durumda yöntemi gizlemek için ikisini de boş bırakın)

Country prices: hedef ülkeye ve sepet ağırlığına göre fiyatlar. Satır eklemek için Add country düğmesine, birini silmek için silme düğmesine tıklayın. Ağırlık aralıkları: XS 1 kg'a kadar, S 1–2 kg, M 2–3 kg, L 3–5 kg ve XL 5 kg'ın üzeri. Boş veya 0 olan aralık Price değerini kullanır. * Default (any other country) diğer tüm ülkeler için geçerlidir.

Fallback cost: hiçbir ülke fiyatı eşleşmediğinde uygulanan sabit fiyat. Bu durumda yöntemi gizlemek için boş bırakın.

Fixed price is: Per order (varsayılan) fiyatı tüm sepetin ağırlığı için bir kez uygular. Per item (each item priced by its own weight x quantity) her ürünü kendi ağırlığı ile miktarının çarpımına göre fiyatlandırır. USPS anlık tarifeleri her zaman tüm koli için teklif edilir.

Koşullar

Free shipping from: bu yöntemin ücretsiz olduğu, kargo gerektiren ürünlerin ara toplamı (kupon sonrası, vergi öncesi). Bu durumda USPS'e istek gönderilmez. Ücretsiz kargoyu asla sunmamak için boş bırakın.

Minimum subtotal: yöntemi yalnızca kargo gerektiren ürünlerin ara toplamı (kupon sonrası, vergi öncesi) en az bu tutar olduğunda gösterir. Her zaman göstermek için boş bırakın.

Min weight (kg): bu yöntemin görünmesi için gereken en düşük sepet ağırlığı. 0 sınır olmadığı anlamına gelir (varsayılan).

Max weight (kg): sepet ağırlığı bu değerin üzerindeyse yöntem gizlenir. Varsayılan: 30. Boş, 30 kg anlamına gelir; 0 ise sınır olmadığı anlamına gelir. USPS 70 lb (31,7 kg) değerine kadar kabul eder: daha ağır kolilere sabit fiyatlar uygulanır.

Geo zone: USPS'i yalnızca bu coğrafi bölgedeki adresler için sunun. All zones (varsayılan) sınır olmadığı anlamına gelir. Coğrafi bölgeler System > Localisation > Geo Zones bölümünde yönetilir. Ignore shipping zones ile birlikte kullanılmaz.

Kargo bölgeleri olmadan kullanılabilirlik

Ignore shipping zones: coğrafi bölgeyi kontrol etmez. Yöntem aşağıdaki ülkeler için sunulur.

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çık olduğunda kullanılır.

Gelişmiş

Debug log: API isteklerini ve tarife hesaplamasını storage/logs/vfd_usps_debug.log.php (OpenCart 4'te system/storage/logs/vfd_usps_debug.log.php) dosyasına kaydeder. Dosya web üzerinden okunamaz. API hataları bu seçenek kapalı olsa bile her zaman kaydedilir. Anahtarlar, belirteçler, posta kodları ve müşteri adresleri asla kaydedilmez. Dosya 5 MB'a ulaştığında vfd_usps_debug.old.log.php dosyasına taşınır ve yeni bir günlük başlatılır.

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

Remove data on uninstall: açıksa, eklentiyi kaldırmak USPS ayarlarını ve günlüğü siler. Önbelleğe alınmış tarifeler her zaman kaldırılır. Verilmiş siparişlerin USPS hizmetleri her zaman saklanır. Kapalıysa, ayarlar yeniden kurulum için saklanır.

İçe / Dışa aktarma

Export: ayarları bir JSON dosyasına kaydetmek için Download JSON düğmesine tıklayın. Consumer Secret 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ı Consumer Secret korunur.

Ödemede nasıl çalışır

OpenCart kargo yöntemlerini gösterirken eklentiden USPS fiyatını ister. Bir Geo zone ayarlanmışsa ve adres bu bölgenin dışındaysa USPS sunulmaz (Ignore shipping zones ile bunun yerine ülke listesi belirleyici olur). 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. Hediye sertifikaları, puanlar ve mağaza kredisi dikkate alınmaz. Eklenti daha sonra koşulları kontrol eder: sepet ağırlığı ve minimum ara toplam. Ücretsiz kargo uygulanıyorsa fiyat 0 olur ve USPS'e istek gönderilmez.

Eklenti USPS'ten bir OAuth belirteci alır ve süresi dolmadan kısa bir süre önce yenileyene kadar tutar. ABD'deki ve bölgelerindeki hedefler için (Porto Riko, ABD Virgin Adaları, Guam, Amerikan Samoası, Kuzey Mariana Adaları, Mikronezya, Marshall Adaları ve Palau) yurt içi fiyatları ister ve müşterinin 5 haneli posta koduna ihtiyaç duyar: bu olmadan istek yapılmaz. Diğer ülkeler için uluslararası fiyatları ister.

İstek; gönderici posta kodunu, sepet ağırlığını, koli boyutunu ve fiyat türünü içerir. 70 lb'yi aşan koliler sabit fiyatları alır. Müşteri, seçili hizmetlerin en ucuzu ile tek bir seçenek görür. USD fiyatı mağaza varsayılan para biriminize çevrilir, ondalık basamaklarına yuvarlanır ve seçili Tax class vergisiyle müşterinin para biriminde gösterilir.

Her teklif 1 saat önbellekte tutulur. Başarısız bir teklif 10 dakika hatırlanır. Zaman aşımı, sunucu hatası, istek sınırı veya reddedilen anahtarlardan sonra USPS 5 dakika boyunca çağrılmaz. HTTP zaman aşımı 10 saniyedir.

USPS tarife döndürmezse fiyat önce Country prices, sonra Fallback cost alanından alınır. Hiçbiri geçerli değilse yöntem gizlenir. Müşteri asla USPS hata metinlerini görmez. Neden hata ayıklama günlüğüne yazılır.

Eklenti yalnızca tarifeleri hesaplar. Posta pulu veya kargo etiketi satın almaz, kurye randevusu oluşturmaz, kolileri takip etmez ve müşterinin bir postane veya teslim noktası seçmesine izin vermez. Birden fazla USPS hizmeti yerine tek bir seçenek gösterir. Koli paketleme yoktur: sepet tek bir koli olarak teklif edilir. Sigorta ve diğer ek hizmetler dahil değildir.

OpenCart 4'te müşteri, ödeme sayfasının kargo yöntemi bölümünde Choose düğmesine tıklar ve Shipping method options penceresinde USPS'i seçer. Yöntem OpenCart 3'teki gibi çalışır.

Siparişler

Bir sipariş USPS ile verildiğinde eklenti, kargo fiyatının nasıl bulunduğunu kaydeder. Sales > Orders altındaki sipariş sayfasında, USPS service (anlık bir tarife için örneğin USPS Ground Advantage), Price source (USPS live rate, Fixed price veya Free shipping) ve Calculated price (excl. tax) bilgilerini gösteren bir USPS paneli görünür. Bu değerler sipariş verildiğinde kaydedilir.

OpenCart 4, ödeme için tek bir sipariş tutar ve müşteri her onayladığında onu günceller. Kayıtlı değerler onunla birlikte güncellenir. Müşteri başka bir kargo yöntemine geçerse, bunlar siparişten kaldırılır. OpenCart 4'te USPS paneli History bölümünün üstünde gösterilir.

Lisans anahtarı

Eklenti, vibefox.net'ten alınan bir VibeFox lisans anahtarıyla çalışır. Lisans bloğu License — VibeFox USPS, Extensions > Extensions > Shipping > VibeFox USPS > Edit 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ı gizli olarak, durumu (örneğin lisansın geçerli olduğu tarihi ve alan adınızı) ve 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-usps satırı ve Manage licenses and domains in your account bağlantısı bulunur; bağlantı vibefox.net hesabınızı açar. Anahtarı yalnızca bu eklenti için Modify izni olan yönetici kullanıcılar değiştirebilir. Bloktaki metinler yönetici dilini izler (İngilizce ve Rusça dahildir).

Anahtar kabul edilmezse blok nedenini belirtir, ö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 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 eklenti son bilinen durumla çalışmaya devam eder.

Bir anahtar tek bir alan adında çalışır: OpenCart yapılandırmasındaki mağaza adresinde. 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 USPS, ödemede müşterilere gösterilmez ve tarife 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 eklentiyi kurup test edebilirsiniz. OpenCart 4'te bu önizleme kullanılamaz: mağaza yönetici girişini görmez, bu yüzden etkin bir anahtar olmadan 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. 7 gün gizlemek için × ile kapatın. 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. 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 her gün bir kez, sonrasında haftada bir kez. Cron işi gerekmez. Eklentiyi kaldırmak her zaman lisans anahtarını ve lisans durumunu siler.

Sorun giderme

USPS ödemede görünmüyor: lisansın etkin olduğunu ve Enable USPS shipping seçeneğinin açık olduğunu kontrol edin. Geo zone ayarını kontrol edin veya Ignore shipping zones seçeneğini açıp Countries alanını kontrol edin. Ağırlık sınırlarını ve Minimum subtotal değerini kontrol edin. Çalışan USPS anahtarları olmadan yöntem sabit bir fiyata ihtiyaç duyar (Country prices veya Fallback cost). Ürünlerin Requires Shipping değerinin Yes olduğunu kontrol edin.

Anlık tarifeler görünmüyor: Edit sayfasının üstündeki uyarıları kontrol edin: iki anahtar, posta kodu, en az bir hizmet ve USD kullanmayan mağazalar için döviz kuru. ABD'deki müşterilerin bir posta kodu girmesi gerekir. Debug log seçeneğini açın, ödemeyi yeniden yükleyin ve eklenti sayfasındaki Log alanına bakın.

Tarifeler gerçek fiyat değil: Test environment seçeneğini kapatın.

Sayfa ağırlık veya uzunluk birimi hakkında uyarıyor: kg birimli bir ağırlık sınıfı yoksa, bilinmeyen ağırlık birimleri kg olarak okunur. System > Localisation > Weight Classes bölümünde kg ağırlık sınıfı ekleyin. Mağazanın bilinmeyen uzunluk birimi cm olarak değerlendirilir. Mağazanızın uzunluk sınıfı olarak cm, mm, m veya in kullanın (System > Settings, Option sekmesi).

Bir değişiklikten sonra tarifeler eskimiş görünüyor: eklenti sayfasındaki Save düğmesine veya Clear cached USPS token and rates düğmesine tıklayın.

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

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

Kaldırma

Extensions > Extensions sayfasına gidin, Shipping türünü seçin ve VibeFox USPS 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 Enable USPS shipping, Sort order, Tax class ve Geo zone ayarlarını sıfırlar. Önbelleğe alınmış USPS belirteci ve tarifeler her zaman kaldırılır. Remove data on uninstall açıksa, USPS ayarları ve hata ayıklama günlüğü de silinir. Kapalıysa diğer ayarlar korunur ve eklentiyi yeniden kurduğunuzda tekrar kullanılır. Verilmiş siparişlerin USPS verileri asla kaldırılmaz; mevcut siparişler kargo yöntemlerini ve maliyetlerini korur.

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

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