VibeFox USPS for WooCommerce — Yardım

Gereksinimler

WordPress: 5.8 veya üzeri.

WooCommerce: 7.0 veya üzeri, kurulu ve etkin. Eklenti WooCommerce olmadan etkinleştirilmez.

PHP: 8.0 veya üzeri.

USPS Developer Portal uygulaması (yalnızca canlı ücretler için): ücretsiz bir USPS iş 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. 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 tek 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üğmesine tıklayın. vfd_usps klasörünü FTP ile /wp-content/plugins/ dizinine de yükleyebilirsiniz.

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

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

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

5. Consumer Key ve Consumer Secret değerlerini, 5 haneli Ship from ZIP code değerini girin ve hizmetleri seçin. Mağaza para biriminiz USD değilse USD exchange rate değerini girin.

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

7. İsteğe bağlı olarak yedek sabit fiyatları girin.

Yapılandırma

Tüm ayarlar tek bir sayfada bulunur: WooCommerce > Settings > Shipping > VibeFox USPS. 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 seçeneğin ödeme sayfasındaki adı. Genel Name değerini kullanmak için boş bırakın.

Ayarları her kaydettiğinizde önbelleğe alınmış USPS jetonu ve ücretler silinir. USPS API bölümündeki Clear cached USPS token and rates düğmesine de tıklayabilirsiniz. Ayarların üstündeki uyarılar; anahtarlardan yalnızca birinin girildiğini, hiç anahtar ve sabit fiyat olmadığını, Ship from ZIP code değerinin eksik olduğunu, hiç hizmet seçilmediğini, USD exchange rate değerinin eksik olduğunu veya test ortamının açık olduğunu bildirir.

Genel

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

Name: ödeme sayfasında gösterilen kargo yöntemi adı. Varsayılan: USPS.

Tax status: USPS fiyatları vergi içermez. Taxable seçeneğinde WooCommerce, kargo vergisini ücrete ekler; None seçeneğinde eklemez.

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.

Test environment: USPS Testing Environment for Mailers kullanılır. Yalnızca bu ortama erişimi olan uygulamalar için. Gerçek fiyatlar için kapalı bırakın. Varsayılan: kapalı.

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

Services: sunulabilecek USPS hizmetleri. Koli için USPS'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.

USD exchange rate: USPS fiyatları USD cinsindendir. Mağaza para biriminiz USD değilse, mağaza para biriminizle 1 USD'nin fiyatını girin, örneğin 0.92. Bu değer olmadan canlı ücretler kullanılmaz ve sabit fiyatlar uygulanır. Mağaza para birimi USD ise gerekli değildir.

Gönderim yeri ve koli (USPS fiyatları gönderim ZIP kodu, ağırlık ve koli boyutuna bağlıdır)

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

Box size: mağaza ölçü biriminizde 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 (kg): ağırlığı olmayan ürünler için USPS fiyatlarında, ağırlık sınırlarında ve ağırlık kademelerinde kullanılan ağırlık. Varsayılan: 0.5.

Sabit fiyatlar (fiyatlar mağaza para biriminizde; API anahtarı girilmediğinde kullanılır ve USPS ücret döndürmediğinde yedek olarak kullanılır: API'ye ulaşılamaması, yanlış anahtarlar, hizmet yokluğu veya ABD ZIP kodu olmayan bir hedef; 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, satır silmek için çarpı işaretine tıklayın. Sütunlar Price ve 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'dan fazla). Boş veya 0 olan kademe Price değerini kullanır. * Default satırı diğer tüm ülkeler için geçerlidir. Sayı olmayan değerler bir mesajla silinir.

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 fiyatı bir kez alır. Per item (each item priced by its own weight x quantity) her ürünü kendi ağırlığına göre fiyatlandırır (ağırlığı yoksa varsayılan ağırlık) ve adetle çarpar. USPS canlı ücretleri her zaman tüm koli için istenir.

Koşullar

Free shipping from: bu yöntemin ücretsiz olduğu sepet ara toplamı. Bu durumda USPS'e istek gönderilmez. Ücretsiz kargoyu hiçbir zaman sunmamak için boş bırakın.

Minimum subtotal: yöntemi 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 (kg): bu yöntemin görünmesi için gereken minimum sepet ağırlığı. 0 sınır olmadığı anlamına gelir.

Max weight (kg): bu sepet ağırlığının üzerinde yöntem gizlenir. Varsayılan: 30. USPS 70 lb'a (31,7 kg) kadar kabul eder. 0 sınır olmadığı anlamına gelir.

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

Kargo bölgeleri olmadan kullanılabilirlik

Ignore shipping zones: yöntemi bir kargo bölgesine eklemeseniz bile aşağıdaki ülkeler için sunar.

Countries: bu mod için hedef ülkeler. Mağazanın tüm kargo ülkelerini kullanmak 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ı WooCommerce > Status > Logs altında, kaynak vfd-usps ile günlüğe kaydeder. API hataları bu seçenek kapalı olsa bile her zaman kaydedilir. Anahtarlar, jetonlar ve müşteri adresleri hiçbir zaman kaydedilmez.

Remove data on uninstall: açıksa eklentiyi silmek tüm eklenti ayarlarını ve bölge yöntemlerini kaldırır. Devre dışı bırakmak ayarları hiçbir zaman 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: sepet ağırlığı, minimum ara toplam ve hariç tutulan kargo sınıfları. Ücretsiz kargo uygulanıyorsa yöntem 0 fiyatla gösterilir ve USPS'e istek gönderilmez.

Eklenti USPS'ten bir OAuth jetonu alır ve süresi dolana kadar saklar. USPS'in reddettiği bir jeton yenilenir ve ücret isteği tekrarlanır. ABD ve bölgeleri (Porto Riko, ABD Virgin Adaları ve Guam dahil) için Domestic Prices API'yi sorgular ve müşterinin 5 haneli ZIP kodunu gerektirir. Diğer ülkeler için International Prices API'yi ülke ve posta koduyla sorgular.

İstek; gönderim ZIP kodunu, sepet ağırlığını pound cinsinden, koli boyutunu inç cinsinden ve fiyat türünü içerir. 70 lb'dan ağır koliler sabit fiyatları alır. Müşteri, seçili en ucuz hizmetle birlikte tek bir seçenek görür ve bu fiyat mağaza para birimine çevrilir.

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. Eklentiyi devre dışı bırakmak önbelleğe alınmış jetonu ve ücretleri siler.

USPS ücret döndürmezse fiyat önce Country prices, sonra Fallback cost alanından alınır. İkisi de uygulanmazsa yöntem gizlenir. Müşteri hiçbir zaman USPS hata metinlerini görmez.

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

Eklenti yalnızca ücret hesaplar. Posta pulu veya kargo etiketi satın almaz, kurye randevusu ayarlamaz, kolileri izlemez ve müşterinin bir Postane ya da teslim noktası seçmesine izin vermez. Birden fazla USPS hizmeti değil, tek bir seçenek gösterir. Koliye paketleme yoktur: sepet tek bir koli olarak fiyatlandırılır. Sigorta ve diğer ek hizmetler dahil değildir.

Siparişler

Canlı bir ücret için siparişin kargo satırı USPS service değerini saklar, örneğin USPS Ground Advantage. Mağaza yöneticisi bunu siparişin yönetici ekranında görür.

Lisans anahtarı

Eklenti, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. Lisans bloğu WooCommerce > Settings > Shipping > VibeFox USPS sayfasının üstündedir. Anahtarı License key alanına yapıştırın ve Activate düğmesine tıklayın. Blokta durum gösterilir; ö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 ve 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 tek bir alan adında çalışır. Anahtarı bir siteden kaldırmak, o sitenin alan adı yuvasını serbest bırakmaz. Yuvayı vibefox.net hesabınızdan serbest bırakın.

Etkin bir anahtar olmadan USPS, ödeme sayfasında müşterilere gösterilmez. Oturum açmış mağaza yöneticileri yine de bunu (unlicensed — visible to admins only) etiketiyle görür. Böylece bir anahtar satın almadan önce eklentiyi kurup test edebilirsiniz. Eklentiler sayfasında ve WooCommerce sayfalarında bir hatırlatma görünür. 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

USPS ö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 izinliyse). Ağırlık sınırlarını, Minimum subtotal ve Excluded shipping classes ayarlarını inceleyin. Çalışan USPS anahtarları yoksa yöntemin bir sabit fiyata (Country prices veya Fallback cost) ihtiyacı vardır.

Canlı ücretler görünmüyor: ayarlar sayfasının üstündeki uyarıları kontrol edin. Debug log seçeneğini açın ve WooCommerce > Status > Logs sayfasını, kaynak vfd-usps olarak açın. Yanlış anahtarlar, yanlış ortam ve USPS hata mesajları burada günlüğe 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 değer olmadan canlı ücret kullanılmaz ve bunun yerine sabit fiyat gösterilir.

Web Tools User ID çalışmıyor: eski Web Tools API kapatıldı. USPS Developer Portal'da bir uygulama oluşturun ve onun Consumer Key ile 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.

Lisans bloğu bir 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 yuva serbest bırakın ve Check now düğmesine tıklayın. Site adresi değiştiyse yeni alan adı için anahtarı etkinleştirmek üzere Check now düğmesine tıklayın. Lisans sunucusuna ulaşılamıyorsa eklenti son bilinen durumla çalışmaya devam eder.

Kaldırma

Eklentiyi devre dışı bırakmak ayarları korur ve yalnızca önbelleğe alınmış jetonu ve ücretleri siler. Kaldırmak için devre dışı bırakın ve Plugins sayfasından silin. Bu eklentinin lisans anahtarı ve lisans durumu ile önbelleğe alınmış jeton ve ücretler her zaman kaldırılır. Ayarlar ve bölge yöntemleri yalnızca Remove data on uninstall açıksa kaldırılır. Aksi halde sonraki bir yeniden kurulum için saklanır. Mevcut siparişler kargo satırlarını korur.

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