VibeFox USPS for WooCommerce — सहायता

आवश्यकताएँ

WordPress: 5.8 या उसके बाद का संस्करण।

WooCommerce: 7.0 या उसके बाद का संस्करण, इंस्टॉल और सक्रिय। इसके बिना प्लगइन सक्रिय नहीं होता।

PHP: 8.0 या उसके बाद का संस्करण।

USPS Developer Portal ऐप (केवल लाइव रेट के लिए): एक मुफ़्त USPS बिज़नेस खाते से USPS Developer Portal (developers.usps.com) में साइन इन करें, एक ऐप बनाएँ और उसकी Consumer Key और Consumer Secret कॉपी करें। प्लगइन OAuth 2.0 के साथ वर्तमान USPS APIs का उपयोग करता है। USPS ने पुरानी Web Tools API (User ID और XML) 25 जनवरी 2026 को बंद कर दी थी, इसलिए Web Tools User ID अब काम नहीं करती। कुंजियों के बिना केवल निश्चित कीमतें उपयोग होती हैं।

Ship-from ZIP code: लाइव रेट के लिए वह 5 अंकों का US ZIP कोड चाहिए जहाँ से पार्सल भेजे जाते हैं।

VibeFox लाइसेंस कुंजी: vibefox.net पर खरीदी जाती है। एक कुंजी एक डोमेन पर काम करती है।

इंस्टॉलेशन

1. WordPress में Plugins > Add New > Upload Plugin पर जाएँ, प्लगइन की ZIP फ़ाइल चुनें और Install Now पर क्लिक करें। आप FTP से vfd_usps फ़ोल्डर को /wp-content/plugins/ में भी अपलोड कर सकते हैं।

2. Activate पर क्लिक करें।

3. सेटिंग्स खोलें: WooCommerce > Settings > Shipping > VibeFox USPS, या Plugins पेज पर प्लगइन के नाम के नीचे Settings पर क्लिक करें।

4. पेज के ऊपर के लाइसेंस ब्लॉक में अपनी VibeFox लाइसेंस कुंजी डालें और Activate पर क्लिक करें।

5. Consumer Key और Consumer Secret, 5 अंकों का Ship from ZIP code डालें और सेवाएँ चुनें। यदि आपके स्टोर की मुद्रा USD नहीं है, तो USD exchange rate डालें।

6. WooCommerce > Settings > Shipping > Shipping zones में VibeFox USPS को किसी शिपिंग ज़ोन में जोड़ें, या Ignore shipping zones चालू करके देश चुनें।

7. वैकल्पिक: फ़ॉलबैक के रूप में निश्चित कीमतें डालें।

सेटिंग्स

सभी सेटिंग्स एक ही पेज पर हैं: WooCommerce > Settings > Shipping > VibeFox USPS। ये हर शिपिंग ज़ोन पर लागू होती हैं। जब आप इस विधि को किसी ज़ोन में जोड़ते हैं, तो ज़ोन विंडो में केवल एक फ़ील्ड होता है:

Title (zone): चेकआउट पर इस विकल्प का नाम। वैश्विक Name का उपयोग करने के लिए इसे खाली छोड़ें।

हर बार जब आप सेटिंग्स सहेजते हैं, कैश किया गया USPS टोकन और रेट साफ़ हो जाते हैं। आप USPS API सेक्शन में Clear cached USPS token and rates पर भी क्लिक कर सकते हैं। सेटिंग्स के ऊपर की चेतावनियाँ बताती हैं कि जब केवल एक कुंजी भरी है, कोई कुंजी और निश्चित कीमतें नहीं हैं, Ship from ZIP code नहीं है, कोई सेवा नहीं चुनी गई है, USD exchange rate नहीं है, या टेस्ट वातावरण चालू है।

सामान्य

Enable/Disable: सभी ज़ोन में एक साथ इस विधि को चालू या बंद करता है।

Name: चेकआउट पर दिखने वाला शिपिंग विधि का नाम। डिफ़ॉल्ट: USPS।

Tax status: USPS की कीमतों में टैक्स शामिल नहीं होते। Taxable चुनने पर WooCommerce शिपिंग की लागत में शिपिंग टैक्स जोड़ता है, None पर नहीं जोड़ता।

USPS API (लाइव रेट)

Consumer Key: आपके USPS डेवलपर ऐप की Consumer Key (client_id)।

Consumer Secret: उसी ऐप की Consumer Secret (client_secret)।

Test environment: USPS Testing Environment for Mailers का उपयोग करता है। केवल उन ऐप्स के लिए जिनके पास इसकी पहुँच है। असली कीमतों के लिए इसे बंद रखें। डिफ़ॉल्ट: बंद।

Prices: कौन-सी USPS कीमतें उपयोग होंगी।

Services: वे USPS सेवाएँ जो दी जा सकती हैं। पार्सल के लिए USPS द्वारा दी जाने वाली चुनी हुई सेवाओं में सबसे सस्ती सेवा दिखाई जाती है। Flat Rate, Cubic, Hold for Pickup और Sunday की कीमतें कभी उपयोग नहीं होतीं। डिफ़ॉल्ट: USPS Ground Advantage, Priority Mail और First-Class Package International Service।

USD exchange rate: USPS की कीमतें USD में होती हैं। यदि आपके स्टोर की मुद्रा USD नहीं है, तो अपनी स्टोर मुद्रा में 1 USD की कीमत डालें, जैसे 0.92। इसके बिना लाइव रेट उपयोग नहीं होते और निश्चित कीमतें लागू होती हैं। यदि स्टोर की मुद्रा USD है, तो इसकी ज़रूरत नहीं है।

भेजने का स्थान और पार्सल (USPS की कीमतें origin ZIP कोड, वज़न और पार्सल के आकार पर निर्भर करती हैं)

Ship from ZIP code: वह 5 अंकों का US ZIP कोड जहाँ से पार्सल भेजे जाते हैं। ZIP+4 को 5 अंकों तक काटा जाता है। अन्य मान एक संदेश के साथ अस्वीकार होते हैं।

Box size: आपकी स्टोर की आयाम इकाई में वैकल्पिक बॉक्स आयाम, जैसे 30x20x15। उत्पाद के आयामों से आकार बनाने के लिए इसे खाली छोड़ें: सबसे लंबी लंबाई, सबसे चौड़ी चौड़ाई और एक-दूसरे पर रखी ऊँचाइयाँ। यदि किसी उत्पाद के आयाम नहीं हैं, तो 10 x 8 x 4 इंच का बॉक्स उपयोग होता है।

Default product weight (kg): बिना वज़न वाले उत्पादों के लिए उपयोग होने वाला वज़न, USPS रेट, वज़न सीमाओं और वज़न-श्रेणियों में। डिफ़ॉल्ट: 0.5।

निश्चित कीमतें (कीमतें आपकी स्टोर मुद्रा में; जब कोई API कुंजी नहीं डाली गई हो तब उपयोग होती हैं, और जब USPS कोई रेट नहीं देता तब फ़ॉलबैक के रूप में: API उपलब्ध न होना, गलत कुंजियाँ, कोई सेवा न होना या बिना US ZIP कोड वाला गंतव्य; इस स्थिति में विधि छिपाने के लिए दोनों खाली छोड़ें)

Country prices: गंतव्य देश और कार्ट के वज़न के अनुसार कीमतें। पंक्ति जोड़ने के लिए + Add country पर क्लिक करें, और हटाने के लिए क्रॉस पर। कॉलम Price हैं और वज़न-श्रेणियाँ XS (1 kg तक), S (1–2 kg), M (2–3 kg), L (3–5 kg) और XL (5 kg से अधिक) हैं। खाली या 0 वाली श्रेणी Price उपयोग करती है। * Default पंक्ति किसी भी अन्य देश पर लागू होती है। जो मान संख्या नहीं हैं, उन्हें संदेश के साथ हटा दिया जाता है।

Fallback cost: एक निश्चित कीमत, जब कोई देश-कीमत मेल नहीं खाती। इस स्थिति में विधि छिपाने के लिए इसे खाली छोड़ें।

Fixed price is: Per order कीमत एक बार लेता है। Per item (each item priced by its own weight x quantity) हर आइटम की कीमत उसके अपने वज़न (वज़न न हो तो डिफ़ॉल्ट वज़न) से तय करता है और उसे मात्रा से गुणा करता है। USPS के लाइव रेट हमेशा पूरे पार्सल के लिए माँगे जाते हैं।

शर्तें

Free shipping from: कार्ट का सबटोटल, जिससे यह विधि मुफ़्त होती है। तब USPS को कोई अनुरोध नहीं भेजा जाता। कभी भी मुफ़्त शिपिंग न देने के लिए खाली छोड़ें।

Minimum subtotal: विधि केवल तभी दिखाएँ जब कार्ट का सबटोटल कम से कम इतनी राशि हो। हमेशा दिखाने के लिए खाली छोड़ें।

Min weight (kg): इस विधि के दिखने के लिए न्यूनतम कार्ट वज़न। 0 का अर्थ है कोई सीमा नहीं।

Max weight (kg): इस कार्ट वज़न से ऊपर विधि छिप जाती है। डिफ़ॉल्ट: 30। USPS 70 lb (31.7 kg) तक स्वीकार करता है। 0 का अर्थ है कोई सीमा नहीं।

Excluded shipping classes: यदि कार्ट में इन WooCommerce शिपिंग क्लास में से किसी का उत्पाद हो, तो विधि छिपा दी जाती है।

शिपिंग ज़ोन के बिना उपलब्धता

Ignore shipping zones: विधि को किसी शिपिंग ज़ोन में जोड़े बिना भी नीचे दिए गए देशों के लिए विधि उपलब्ध कराता है।

Countries: इस मोड के लिए गंतव्य देश। स्टोर के सभी शिपिंग देश उपयोग करने के लिए खाली छोड़ें। यह फ़ील्ड केवल तभी उपयोग होता है जब Ignore shipping zones चालू हो।

उन्नत

Debug log: API अनुरोधों और रेट की गणना को WooCommerce > Status > Logs में, स्रोत vfd-usps के साथ लॉग करता है। यह विकल्प बंद होने पर भी API त्रुटियाँ हमेशा लॉग होती हैं। कुंजियाँ, टोकन और ग्राहक के पते कभी लॉग नहीं होते।

Remove data on uninstall: चालू होने पर प्लगइन हटाने से सभी प्लगइन सेटिंग्स और ज़ोन की विधियाँ हट जाती हैं। निष्क्रिय करने पर सेटिंग्स कभी नहीं हटतीं।

चेकआउट पर यह कैसे काम करता है

जब ग्राहक डिलीवरी पता डालता है, तो WooCommerce प्लगइन से रेट माँगता है। प्लगइन पहले शर्तें जाँचता है: कार्ट का वज़न, न्यूनतम सबटोटल और बाहर रखी गई शिपिंग क्लास। यदि मुफ़्त शिपिंग लागू होती है, तो विधि 0 की कीमत के साथ दिखाई जाती है और USPS को कोई अनुरोध नहीं जाता।

प्लगइन USPS से OAuth टोकन लेता है और उसकी समाप्ति तक रखता है। USPS द्वारा अस्वीकार किया गया टोकन नवीनीकृत होता है और कोटेशन दोहराया जाता है। अमेरिका और उसके क्षेत्रों (प्यूर्टो रिको, US Virgin Islands और गुआम सहित) के गंतव्यों के लिए यह Domestic Prices API से पूछता है और ग्राहक का 5 अंकों का ZIP कोड चाहिए। अन्य देशों के लिए यह देश और पोस्टल कोड के साथ International Prices API से पूछता है।

अनुरोध में ship-from ZIP कोड, पाउंड में कार्ट का वज़न, इंच में पार्सल का आकार और कीमत का प्रकार होता है। 70 lb से भारी पार्सलों को निश्चित कीमतें मिलती हैं। ग्राहक को चुनी हुई सबसे सस्ती सेवा वाला एक विकल्प दिखता है, जो आपकी स्टोर मुद्रा में बदला जाता है।

हर कोटेशन 1 घंटे के लिए कैश होता है। विफल कोटेशन 10 मिनट तक याद रखा जाता है। टाइमआउट, सर्वर त्रुटि, रेट लिमिट या अस्वीकृत कुंजियों के बाद 5 मिनट तक USPS को नहीं बुलाया जाता। HTTP टाइमआउट 10 सेकंड है। प्लगइन निष्क्रिय करने पर कैश किया गया टोकन और रेट साफ़ हो जाते हैं।

यदि USPS कोई रेट नहीं देता, तो कीमत पहले Country prices से और फिर Fallback cost से ली जाती है। यदि दोनों लागू न हों, तो विधि छिप जाती है। ग्राहक को USPS की त्रुटि के संदेश कभी नहीं दिखते।

यह विधि क्लासिक चेकआउट और Cart व Checkout ब्लॉक पर काम करती है। यह WooCommerce High-Performance Order Storage (HPOS) के साथ संगत है।

प्लगइन केवल रेट की गणना करता है। यह पोस्टेज या शिपिंग लेबल नहीं खरीदता, पिकअप बुक नहीं करता, पार्सल ट्रैक नहीं करता, और ग्राहक को पोस्ट ऑफ़िस या पिकअप लोकेशन चुनने नहीं देता। यह एक ही विकल्प दिखाता है, कई USPS सेवाएँ नहीं। बॉक्स में पैकिंग नहीं होती: कार्ट को एक ही पार्सल के रूप में कोट किया जाता है। बीमा और अन्य अतिरिक्त सेवाएँ शामिल नहीं हैं।

ऑर्डर

लाइव रेट के लिए, ऑर्डर की शिपिंग लाइन USPS service सहेजती है, जैसे USPS Ground Advantage। स्टोर मैनेजर इसे एडमिन ऑर्डर स्क्रीन पर देखता है।

लाइसेंस कुंजी

प्लगइन vibefox.net से ली गई VibeFox लाइसेंस कुंजी के साथ काम करता है। लाइसेंस ब्लॉक WooCommerce > Settings > Shipping > VibeFox USPS पेज के ऊपर होता है। कुंजी को License key में चिपकाएँ और Activate पर क्लिक करें। ब्लॉक स्थिति दिखाता है, जैसे लाइसेंस किस तारीख तक सक्रिय है और आपका डोमेन। स्थिति दोबारा जाँचने के लिए Check now का उपयोग करें, दूसरी कुंजी डालने के लिए Change key, और इस साइट से कुंजी हटाने के लिए Remove key। Manage licenses and domains in your account लिंक आपका vibefox.net खाता खोलता है।

एक कुंजी एक डोमेन पर काम करती है। साइट से कुंजी हटाने से उसका डोमेन स्लॉट खाली नहीं होता। अपने vibefox.net खाते में स्लॉट खाली करें।

सक्रिय कुंजी के बिना चेकआउट पर ग्राहकों को USPS नहीं दिखता। लॉग इन किए स्टोर मैनेजरों को यह अब भी दिखता है, (unlicensed — visible to admins only) चिह्न के साथ, ताकि आप कुंजी खरीदने से पहले प्लगइन सेट अप और टेस्ट कर सकें। प्लगइन पेज और WooCommerce पेजों पर एक अनुस्मारक दिखता है। मौजूदा ऑर्डर प्रभावित नहीं होते।

लाइसेंस समाप्त होने पर भी प्लगइन काम करता रहता है, लेकिन अपडेट और सहायता के लिए नवीनीकरण चाहिए। स्थिति बैकग्राउंड में अपने-आप दोबारा जाँची जाती है।

समस्या निवारण

चेकआउट पर USPS नहीं दिख रहा: जाँचें कि लाइसेंस सक्रिय है, Enable/Disable चालू है, और विधि ग्राहक के देश के ज़ोन में जुड़ी है (या Ignore shipping zones चालू है और देश की अनुमति है)। वज़न सीमाएँ, Minimum subtotal और Excluded shipping classes देखें। कार्यशील USPS कुंजियों के बिना विधि को निश्चित कीमत (Country prices या Fallback cost) चाहिए।

लाइव रेट नहीं दिख रहे: सेटिंग्स पेज के ऊपर की चेतावनियाँ देखें। Debug log चालू करें और WooCommerce > Status > Logs खोलें, स्रोत vfd-usps। गलत कुंजियाँ, गलत वातावरण और USPS की त्रुटि के संदेश वहाँ लॉग होते हैं। घरेलू रेट के लिए ग्राहक का 5 अंकों का ZIP कोड चाहिए।

मेरा स्टोर USD में नहीं है: USPS केवल USD में कोट करता है। USD exchange rate डालें। इसके बिना लाइव रेट उपयोग नहीं होता और उसकी जगह निश्चित कीमत दिखती है।

Web Tools User ID काम नहीं करता: पुरानी Web Tools API बंद हो चुकी है। USPS Developer Portal में एक ऐप बनाएँ और उसकी Consumer Key और Consumer Secret उपयोग करें।

बदलाव के बाद रेट पुराने लगते हैं: सेटिंग्स सहेजने पर कैश साफ़ हो जाता है। आप Clear cached USPS token and rates पर भी क्लिक कर सकते हैं।

लाइसेंस ब्लॉक में त्रुटि दिखती है: ब्लॉक में दिए संदेश के अनुसार चलें। उदाहरण के लिए, यदि कुंजी किसी दूसरे डोमेन पर पहले से उपयोग हो रही है, तो अपने vibefox.net खाते में स्लॉट खाली करें और Check now पर क्लिक करें। यदि साइट का पता बदल गया है, तो नए डोमेन के लिए कुंजी सक्रिय करने हेतु Check now पर क्लिक करें। यदि लाइसेंस सर्वर तक पहुँच नहीं है, तो प्लगइन आखिरी ज्ञात स्थिति के साथ काम करता रहता है।

अनइंस्टॉल

प्लगइन निष्क्रिय करने पर सेटिंग्स रहती हैं और केवल कैश किया गया टोकन और रेट साफ़ होते हैं। हटाने के लिए, प्लगइन निष्क्रिय करें और Plugins पेज पर उसे हटाएँ। इस प्लगइन की लाइसेंस कुंजी और लाइसेंस स्थिति, तथा कैश किए गए टोकन और रेट हमेशा हटा दिए जाते हैं। सेटिंग्स और ज़ोन की विधियाँ केवल तभी हटती हैं जब Remove data on uninstall चालू था। अन्यथा वे बाद में दोबारा इंस्टॉल करने के लिए रहती हैं। मौजूदा ऑर्डर अपनी शिपिंग लाइनें रखते हैं।

USPS उसके संबंधित स्वामी का ट्रेडमार्क है। यह प्लगइन USPS से संबद्ध नहीं है और USPS द्वारा अनुमोदित नहीं है।