VibeFox USPS for PrestaShop — Yardım

Gereksinimler

PrestaShop: 8.0 ila 9.x.

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

USPS Developer Portal uygulaması (yalnızca canlı ücretler 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. Modül, OAuth 2.0 ile güncel USPS API'lerini kullanır. USPS, eski Web Tools API'sini (User ID ve XML) 25 Ocak 2026'da kapattı; bu nedenle bir Web Tools User ID artık çalışmaz. Anahtarlar olmadan yalnızca sabit fiyatlar kullanılır.

Ship-from ZIP code: canlı ücretler için, kolilerin gönderildiği 5 haneli ABD ZIP kodu gerekir.

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

Kurulum

1. Back office'te 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 USPS öğesini bulup Configure düğmesine tıklayın.

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

4. Consumer Key ve Consumer Secret değerlerini, 5 haneli Ship from ZIP code değerini girin ve hizmetleri seçin. Mağazanızın varsayılan para birimi USD değilse USD exchange rate değerini girin. İsterseniz yedek olarak sabit fiyatları girin. Save düğmesine tıklayın.

Kurulum sırasında modül, Delivery by USPS teslimat süresi metniyle birlikte USPS 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 USPS > Configure. Kargo firmasının tüm bölgelerinde geçerlidirler. Her bölümün kendi Save düğmesi vardır ve bu düğme tüm sayfayı kaydeder. Her kayıt, önbelleğe alınmış USPS belirtecini ve ücretleri de temizler.

Geçersiz bir değer kaydedilmez: önceki değer kalır ve bir hata alanı belirtir, diğer alanlar ise kaydedilir. Sayfanın üst kısmındaki uyarılar şu durumlarda size bilgi verir: anahtarlardan yalnızca biri girilmişse, hiç anahtar ve sabit fiyat yoksa (kargo firması bu durumda hiç gösterilmez), gönderim ZIP kodu eksikse, hiç hizmet seçilmemişse, USD döviz kuru eksikse, test ortamı açıksa, mağazanın ağırlık ya da boyut birimi bilinmiyorsa (International > Localization bölümünden, Local units ayarında belirleyin) veya USPS kargo firması silinmişse.

Genel

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

Name: ödeme sırasında müşteriye gösterilen kargo firması adı. Varsayılan: USPS. Zorunlu, en fazla 64 karakter.

Tax status: kargo firmasının vergi kuralı. USPS fiyatlarına vergi dahil değildir. Kargo vergisi eklemek için bir vergi kuralı seçin veya kargo vergilendirilmiyorsa None seçin.

USPS API (canlı ücretler)

Consumer Key: USPS geliştirici uygulamanızın Consumer Key (client_id) değeri.

Consumer Secret: aynı uygulamanın Consumer Secret (client_secret) değeri. 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. Consumer Key alanını temizlemek, kayıtlı gizli anahtarı da siler.

Test environment: USPS Testing Environment for Mailers (apis-tem.usps.com) ortamını kullanır. Yalnızca bu ortama erişimi olan uygulamalar içindir. Gerçek fiyatlar için kapalı bırakın (apis.usps.com). Varsayılan: kapalı.

Prices: hangi USPS fiyatlarının kullanılacağı.

Services: sunulabilecek USPS hizmetleri. USPS'in koli için sunduğu seçili hizmetlerin en ucuzu gösterilir. Flat Rate, Cubic, Hold for Pickup ve Sunday fiyatları hiçbir zaman kullanılmaz. Varsayılan: USPS Ground Advantage, Priority Mail ve First-Class Package International Service. Hiçbir hizmet seçilmezse canlı ücretler kullanılmaz.

USD exchange rate: USPS fiyatları USD cinsindendir. Mağazanızın varsayılan para birimi USD değilse, o para birimindeki 1 USD fiyatını girin, örneğin 0.92. Bu olmadan canlı ücretler kullanılmaz ve sabit fiyatlar geçerli olur. Varsayılan para birimi USD ise gerekmez. 0'dan büyük olmalıdır.

Cache: Clear cached USPS token and rates düğmesi önbelleği hemen boşaltır. Ücretler 1 saat, başarısız bir ücret 10 dakika önbelleğe alınır. Zaman aşımı, sunucu hatası, istek sınırı veya reddedilen anahtarlardan sonra 5 dakika boyunca USPS'e istek gönderilmez.

Gönderim ve koli (USPS fiyatları gönderim ZIP kodu, ağırlık ve koli boyutuna bağlıdır; sepet tek bir koli olarak hesaplanır ve 70 lb'yi aşan kolilerde sabit fiyatlar kullanılır)

Ship from ZIP code: kolilerin gönderildiği 5 haneli ABD ZIP kodu. ZIP+4 kodu 5 haneye kısaltılır. Diğer değerler bir mesajla reddedilir.

Box size: mağazanızın boyut biriminde, isteğe bağlı kutu ölçüleri, örneğin 30x20x15. Boyutu ürün ölçülerinden oluşturmak için boş bırakın: en uzun uzunluk, en geniş genişlik ve üst üste konan yükseklikler. Bir ürünün ölçüsü yoksa 10 x 8 x 4 inç'lik bir kutu kullanılır.

Default product weight: ağırlığı olmayan ürünler için kullanılan kg cinsinden ağırlık; USPS ücretlerinde, ağırlık sınırlarında ve ağırlık kademelerinde kullanılır. Varsayılan: 0.5.

Sabit fiyatlar (mağazanızın varsayılan para biriminde, vergi hariç fiyatlar; API anahtarı girilmediğinde ve USPS ücret döndürmediğinde yedek olarak kullanılır: API kullanılamıyor, yanlış anahtarlar, hizmet yok ya da ABD ZIP kodu olmayan bir hedef; bu durumda kargo firmasını gizlemek için iki alanı da boş bırakın)

Country prices: hedef ülkeye ve sepet ağırlığına göre fiyatlar. Satır eklemek için Add country, silmek için çöp kutusu simgesine tıklayın. Sütunlar Price ile ağırlık kademeleri 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 kademe Price değerini kullanır. * Default (any other country) satırı diğer tüm ülkeler için geçerlidir. Hiçbir fiyatı olmayan bir ülke satırı, o ülkeyi Fallback cost'a yönlendirir. Sayı olmayan değerler bir mesajla temizlenir.

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

Fixed price is: Per order fiyatı bir kez, tüm sepetin ağırlığına göre alır. Per item (each item priced by its own weight x quantity) her ürünü tek birimin ağırlığına göre (ağırlığı yoksa varsayılan ağırlık) fiyatlandırır ve adetle çarpar. USPS canlı ücretleri her zaman tüm koli için hesaplanır.

Koşullar

Free shipping from: bu kargo firmasının ücretsiz olduğu sepet ara toplamı (indirimlerden sonra, vergilerden önce). Bu durumda USPS'e istek gönderilmez. Ücretsiz kargo asla sunulmasın istiyorsanız boş bırakın.

Minimum subtotal: kargo firmasını yalnızca sepet ara toplamı bu tutarın en az olduğunda gösterir. Her zaman göstermek için boş bırakın.

Min weight: bu kargo firmasının görünmesi için sepetin kg cinsinden en düşük ağırlığı. 0 sınır olmadığı anlamına gelir.

Max weight: kargo firması, sepet ağırlığı kg cinsinden bu değerin üzerindeyse gizlenir. Varsayılan: 30. USPS 70 lb'ye (31,7 kg) kadar kabul eder. 0 sınır olmadığı anlamına gelir. Min weight, Max weight değerinden büyükse bir hata gösterilir ve önceki sınırlar korunur.

Kargo bölgesi olmadan kullanılabilirlik

Ignore shipping zones: kargo firmasını aşağıdaki ülkeler için tüm bölgelerde sunar. Kaydetmek, kargo firmasını mağazanın tüm bölgelerine bağlar; sonradan oluşturulanlara da. Kapatmak, kargo firmasına önceki bölgelerini geri verir.

Countries: bu mod için hedef ülkeler. Mağazanın gönderim yaptığı tüm ülkelere izin vermek için boş bırakın. Bu alan yalnızca Ignore shipping zones açıkken kullanılır.

Gelişmiş

Debug log: API isteklerini ve ücret hesaplamasını modül klasöründeki logs/vfd_usps_debug.log.php dosyasına kaydeder. Dosya web üzerinden açılamaz. API hataları, bu seçenek kapalı olsa bile her zaman kaydedilir. Anahtarlar, belirteçler ve müşteri adresleri hiçbir zaman kaydedilmez.

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

Remove data on uninstall: açıksa modülü kaldırmak USPS ayarlarını, kargo firmasını, kayıtlı sipariş hizmetlerini, önbelleğe alınmış ücretleri ve günlükleri siler. Kapalıysa yeniden kurulum için her şey korunur.

Ödemede nasıl çalışır

Gönderim adımında PrestaShop modülden USPS fiyatını ister. Yalnızca fiziksel ürünler sayılır: sanal ürünler ağırlık eklemez ve ara toplama dahil edilmez. Modül önce koşulları kontrol eder: izin verilen ülkeler (Ignore shipping zones ile), sepet ağırlığı ve minimum ara toplam. Ücretsiz kargo uygulanırsa fiyat 0 olur ve USPS'e istek gönderilmez.

Modül USPS'ten bir OAuth belirteci alır ve süresi dolmadan kısa bir süre öncesine kadar saklar. USPS'in reddettiği bir belirteç yenilenir ve ücret sorgusu tekrarlanır. ABD ve bölgeleri (Porto Riko, ABD Virgin Adaları, Guam, Amerikan Samoası, Kuzey Mariana Adaları, Mikronezya Federal Devletleri, Marshall Adaları ve Palau) için Domestic Prices API'sine sorgu gönderir ve müşterinin 5 haneli ZIP kodunu ister. Diğer ülkeler için International Prices API'sine ülke ve posta kodu ile sorgu gönderir.

İstek; gönderim ZIP kodunu, sepet ağırlığını pound cinsinden, koli boyutunu inç cinsinden ve fiyat türünü içerir. 70 lb'yi aşan koliler sabit fiyatları alır. Müşteri, seçili en ucuz hizmeti içeren tek bir seçenek görür; bu fiyat USD'den mağazanızın varsayılan para birimine çevrilir ve ardından müşterinin sepet para biriminde gösterilir.

Her ücret 1 saat önbelleğe alınır. Başarısız bir ücret 10 dakika hatırlanır. Zaman aşımı, sunucu hatası, istek sınırı veya reddedilen anahtarlardan sonra 5 dakika boyunca USPS'e istek gönderilmez. HTTP zaman aşımı 10 saniyedir.

USPS ücret döndürmezse fiyat önce Country prices'tan, sonra Fallback cost'tan alınır. Hiçbiri uygulanmazsa kargo firması gizlenir. Müşteri hiçbir zaman USPS hata metinlerini görmez. Nedeni günlüğe yazılır.

Kargo firmasını siparişleri olduktan sonra Shipping > Carriers bölümünde düzenlerseniz, 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 ücret hesaplar. Posta pulu veya kargo etiketi satın almaz, kurye randevusu ayarlamaz, kolileri izlemez ve müşterinin bir Postane veya teslim noktası seçmesine izin vermez. Birden fazla USPS hizmeti değil, tek bir seçenek gösterir. Kutulara paketleme yoktur: sepet tek bir koli olarak hesaplanır. Sigorta ve diğer ek hizmetler dahil değildir.

Siparişler

Sipariş USPS kargo firmasıyla verildiğinde modül, kargo fiyatının nasıl bulunduğunu kaydeder. Yönetici sipariş sayfasında, USPS service (canlı ücret için örneğin USPS Ground Advantage) ve Price source alanlarıyla birlikte bir USPS bloğu gösterilir: USPS live rate, Fixed price veya Free shipping.

Lisans anahtarı

Modül, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. License — VibeFox USPS lisans bloğu, Modules > Module Manager > VibeFox USPS > Configure 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 hangi tarihe kadar geçerli olduğunu 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: presta-shipping-usps satırı ile hesabınızdaki vibefox.net sayfasını açan Manage licenses and domains in your account bağlantısı bulunur. Anahtarı yalnızca modül için Configure izni olan personel değiştirebilir. Bloktaki metinler back office 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ı boşalttıktan sonra Check now düğmesine tıklayın. Lisans sunucusuna ulaşılamazsa modül son bilinen durumla çalışmaya devam eder.

Bir anahtar 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ı boşaltmaz. Yuvayı vibefox.net hesabınızdan boşaltın.

Etkin bir anahtar olmadan USPS kargo firması müşterilere ödeme sırasında gösterilmez ve hiçbir ücret hesaplanmaz. PrestaShop vitrini, back office'e giriş yaptığınızı bilmez; bu nedenle kargo firması sizin için de gizlenir: modülü bir anahtar satın almadan önce kurabilirsiniz, ancak ödeme sırasında test edemezsiniz. Modules > Module Manager bölümünde, Alerts sekmesinde bir hatırlatma görünür. Mevcut siparişler etkilenmez.

Bir lisansın süresi dolduğunda modül çalışmaya devam eder, ancak güncellemeler ve destek için yenileme gerekir. Anahtar girildikten sonraki ilk 14 gün boyunca günde bir kez, sonrasında haftada bir kez, back office'te çalışırken durum otomatik olarak yeniden kontrol edilir. Cron işi gerekmez. Modülü kaldırmak veya sıfırlamak her zaman lisans anahtarını ve lisans durumunu siler.

Sorun giderme

USPS ödeme sırasında görünmüyor: lisansın etkin olduğunu ve Enable USPS shipping 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üşteri grubunu kapsadığını kontrol edin ya da 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 kargo firmasının sabit bir fiyata ihtiyacı vardır (Country prices veya Fallback cost). Ürün sayfasında ürünler belirli kargo firmalarıyla da sınırlandırılmış olabilir.

Canlı ücretler görünmüyor: modül sayfasının üst kısmındaki uyarıları kontrol edin. Debug log seçeneğini açın, ödeme sayfasını yeniden yükleyin ve Log alanına bakın. Yanlış anahtarlar, yanlış ortam ve USPS hata mesajları orada kaydedilir. Yurt içi ücretler müşterinin 5 haneli ZIP kodunu gerektirir.

Mağazam USD değil: USPS yalnızca USD cinsinden teklif verir. USD exchange rate değerini girin. Bu olmadan canlı ücret kullanılmaz ve bunun yerine sabit fiyat gösterilir.

Web Tools User ID çalışmıyor: eski Web Tools API kapatılmıştır. USPS Developer Portal'da bir uygulama oluşturun ve onun Consumer Key ve Consumer Secret değerlerini kullanın.

Bir değişiklikten sonra ücretler eski görünüyor: ayarları kaydettiğinizde önbellek temizlenir. Clear cached USPS token and rates düğmesine de tıklayabilirsiniz.

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

Kaldırma

Modules > Module Manager bölümüne gidin, VibeFox USPS 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ış belirteç ve ücretler de her zaman kaldırılır. Remove data on uninstall açıksa kargo firması silinir (siparişler geçmişlerini korur) ve ayarlar, kayıtlı sipariş hizmetleri ile 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 kurarsanız veya Reset kullanırsanız kayıtlı kargo firması önceki durumunu geri alır: açık olan tekrar açılır, devre dışı olan devre dışı kalır.

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