VibeFox USPS for PrestaShop — सहायता

आवश्यकताएँ

PrestaShop: 8.0 से 9.x।

PHP: 8.0 या उसके बाद का संस्करण। पुराने PHP संस्करणों पर मॉड्यूल इंस्टॉल नहीं होता।

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. बैक ऑफ़िस में Modules > Module Manager पर जाएँ और Upload a module पर क्लिक करें। मॉड्यूल की ZIP फ़ाइल चुनें।

2. अपलोड पूरा होने पर Configure पर क्लिक करें, या बाद में मॉड्यूल सूची में VibeFox USPS ढूँढकर Configure पर क्लिक करें।

3. Configure पेज के सबसे ऊपर लाइसेंस ब्लॉक में License key फ़ील्ड में अपनी VibeFox लाइसेंस कुंजी दर्ज करें और Activate पर क्लिक करें (लाइसेंस कुंजी देखें)।

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

इंस्टॉल होने पर मॉड्यूल डिलीवरी समय के टेक्स्ट Delivery by USPS के साथ USPS कैरियर बनाता है। कैरियर सभी ज़ोन और सभी ग्राहक समूहों को सौंपा जाता है। ज़ोन, ग्राहक समूह, डिलीवरी समय, लोगो और आकार सीमाएँ आप Shipping > Carriers में बदल सकते हैं। वहाँ कीमतें सेट न करें: कीमत हमेशा मॉड्यूल से आती है।

कॉन्फ़िगरेशन

सभी सेटिंग्स मॉड्यूल पेज पर हैं: Modules > Module Manager > VibeFox USPS > Configure। ये कैरियर के हर ज़ोन पर लागू होती हैं। हर सेक्शन का अपना Save बटन है, जो पूरा पेज सहेजता है। हर सेव से कैश किया गया USPS टोकन और रेट भी साफ़ हो जाते हैं।

अमान्य मान सहेजा नहीं जाता: पिछला मान बना रहता है और एक त्रुटि उस फ़ील्ड का नाम बताती है, जबकि बाकी फ़ील्ड सहेजे जाते हैं। पेज के ऊपर की चेतावनियाँ आपको बताती हैं कि कब केवल एक कुंजी भरी है, कब कोई कुंजी और निश्चित कीमत नहीं है (तब कैरियर कभी नहीं दिखाया जाता), कब शिप-फ़्रॉम ZIP कोड नहीं है, कब कोई सेवा चुनी नहीं गई है, कब USD विनिमय दर नहीं है, कब टेस्ट एनवायरनमेंट चालू है, कब शॉप की वज़न या आयाम इकाई अज्ञात है (इसे International > Localization में Local units के तहत सेट करें), या कब USPS कैरियर हटाया गया है।

सामान्य

Enable USPS shipping: कैरियर को चालू या बंद करता है। यह Shipping > Carriers में कैरियर की स्थिति वाला ही स्विच है।

Name: चेकआउट पर ग्राहक को दिखाया जाने वाला कैरियर नाम। डिफ़ॉल्ट: USPS। आवश्यक, अधिकतम 64 अक्षर।

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

USPS API (लाइव रेट)

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

Consumer Secret: उसी ऐप की Consumer Secret (client_secret)। सेव करने के बाद यह फ़ील्ड खाली रहता है और Saved — leave empty to keep it. दिखाता है। केवल बदलना हो तो नया मान दर्ज करें। Consumer Key हटाने से सहेजा गया secret भी हट जाता है।

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

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 है तो इसकी ज़रूरत नहीं। यह 0 से अधिक होना चाहिए।

Cache: Clear cached USPS token and rates बटन कैश तुरंत खाली करता है। रेट 1 घंटे के लिए, विफल रेट 10 मिनट के लिए कैश होते हैं। टाइमआउट, सर्वर त्रुटि, रेट सीमा या अस्वीकृत कुंजियों के बाद 5 मिनट तक USPS को कॉल नहीं किया जाता।

शिपिंग और पार्सल (USPS की कीमतें शिप-फ़्रॉम ZIP कोड, वज़न और पार्सल के आकार पर निर्भर करती हैं; कार्ट को एक पार्सल के रूप में कोट किया जाता है, और 70 lb से भारी पार्सल निश्चित कीमतें लेते हैं)

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 (any other country) पंक्ति किसी भी अन्य देश पर लागू होती है। जिस देश की पंक्ति में कोई कीमत न हो, वह देश Fallback cost पर जाता है। जो मान संख्या नहीं हैं, वे एक संदेश के साथ साफ़ कर दिए जाते हैं।

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 का अर्थ है कोई सीमा नहीं। यदि Min weight, Max weight से अधिक है, तो एक त्रुटि दिखती है और पिछली सीमाएँ बनी रहती हैं।

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

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

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

एडवांस्ड

Debug log: API अनुरोध और रेट गणना को मॉड्यूल फ़ोल्डर में logs/vfd_usps_debug.log.php में लॉग करता है। यह फ़ाइल वेब से नहीं खोली जा सकती। API त्रुटियाँ हमेशा लॉग होती हैं, भले ही यह विकल्प बंद हो। कुंजियाँ, टोकन और ग्राहक के पते कभी लॉग नहीं होते।

Log: लॉग का आकार और ताज़ा प्रविष्टियाँ दिखाता है। खाली करने के लिए Clear log पर क्लिक करें।

Remove data on uninstall: चालू होने पर मॉड्यूल हटाने से USPS सेटिंग्स, कैरियर, सहेजी गई ऑर्डर सेवाएँ, कैश किए गए रेट और लॉग हट जाते हैं। बंद होने पर पुनः इंस्टॉल के लिए सब कुछ सुरक्षित रहता है।

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

शिपिंग चरण में PrestaShop मॉड्यूल से USPS कीमत माँगता है। केवल भौतिक उत्पाद गिने जाते हैं: वर्चुअल उत्पाद वज़न नहीं जोड़ते और सबटोटल में शामिल नहीं होते। मॉड्यूल पहले शर्तें जाँचता है: अनुमत देश (Ignore shipping zones के साथ), कार्ट का वज़न और न्यूनतम सबटोटल। यदि मुफ़्त शिपिंग लागू होती है, तो कीमत 0 होती है और USPS को कोई अनुरोध नहीं भेजा जाता।

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

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

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

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

यदि कैरियर के ऑर्डर होने के बाद आप Shipping > Carriers में उसे संपादित करते हैं, तो PrestaShop उसे कैरियर के नए संस्करण के रूप में सहेजता है। मॉड्यूल नए संस्करण का अपने-आप अनुसरण करता है।

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

ऑर्डर

जब USPS कैरियर से ऑर्डर दिया जाता है, तो मॉड्यूल सहेजता है कि शिपिंग कीमत कैसे मिली थी। एडमिन ऑर्डर पेज पर USPS ब्लॉक दिखता है, जिसमें USPS service (लाइव रेट के लिए, उदाहरण के लिए USPS Ground Advantage) और Price source होते हैं: USPS live rate, Fixed price या Free shipping।

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

मॉड्यूल vibefox.net से मिली VibeFox लाइसेंस कुंजी के साथ काम करता है। लाइसेंस ब्लॉक License — VibeFox USPS, Modules > Module Manager > VibeFox USPS > Configure पेज पर सेटिंग्स के ऊपर पहला ब्लॉक है। कुंजी License key फ़ील्ड में दर्ज करें और Activate पर क्लिक करें। उसके बाद ब्लॉक कुंजी को मास्क करके, स्थिति (जैसे लाइसेंस की वैधता की तारीख और आपका डोमेन) दिखाता है, साथ ही ये बटन: स्थिति दोबारा जाँचने के लिए Check now, कोई दूसरी कुंजी दर्ज करने के लिए Change key, और इस शॉप से कुंजी हटाने के लिए Remove key। इनके नीचे Product: presta-shipping-usps वाली पंक्ति और Manage licenses and domains in your account लिंक है, जो आपका vibefox.net अकाउंट खोलता है। कुंजी केवल वे कर्मचारी बदल सकते हैं जिनके पास इस मॉड्यूल के लिए Configure अनुमति है। ब्लॉक के टेक्स्ट बैक ऑफ़िस की भाषा का पालन करते हैं (अंग्रेज़ी और रूसी शामिल हैं)।

यदि कुंजी स्वीकार नहीं होती, तो ब्लॉक कारण बताता है, जैसे Key not found, This key belongs to another product, Domain limit reached, या तारीख के साथ License expired on। शॉप का पता बदलने के बाद, या अपने अकाउंट में डोमेन स्लॉट खाली करने के बाद, Check now पर क्लिक करें। यदि लाइसेंस सर्वर तक नहीं पहुँचा जा सकता, तो मॉड्यूल आखिरी ज्ञात स्थिति पर काम करता रहता है।

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

सक्रिय कुंजी के बिना USPS कैरियर चेकआउट पर ग्राहकों को नहीं दिखाया जाता और कोई रेट कैलकुलेट नहीं होता। PrestaShop स्टोरफ़्रंट को नहीं पता कि आप बैक ऑफ़िस में लॉग इन हैं, इसलिए कैरियर आपके लिए भी छिपा रहता है: आप कुंजी खरीदने से पहले मॉड्यूल सेट कर सकते हैं, पर चेकआउट पर उसे टेस्ट नहीं कर सकते। Modules > Module Manager में Alerts टैब पर एक याद दिलाने वाला संदेश दिखता है। मौजूदा ऑर्डर प्रभावित नहीं होते।

जब लाइसेंस की अवधि समाप्त होती है, तो मॉड्यूल काम करता रहता है, पर अपडेट और सपोर्ट के लिए नवीनीकरण चाहिए। जब आप बैक ऑफ़िस में काम करते हैं, तब स्थिति अपने-आप दोबारा जाँची जाती है: कुंजी दर्ज करने के बाद पहले 14 दिनों तक रोज़ एक बार, फिर हफ़्ते में एक बार। cron जॉब की ज़रूरत नहीं है। मॉड्यूल अनइंस्टॉल या रीसेट करने पर लाइसेंस कुंजी और लाइसेंस स्थिति हमेशा हट जाती हैं।

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

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

लाइव रेट नहीं दिखते: मॉड्यूल पेज के ऊपर की चेतावनियाँ देखें। Debug log चालू करें, चेकआउट दोबारा लोड करें और Log फ़ील्ड देखें। गलत कुंजियाँ, गलत एनवायरनमेंट और 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 पर भी क्लिक कर सकते हैं।

पेज कहता है कि USPS कैरियर नहीं मिला: कैरियर Shipping > Carriers में हटाया गया था। उसे दोबारा बनाने के लिए Modules > Module Manager में मॉड्यूल रीसेट करें।

अनइंस्टॉल

Modules > Module Manager पर जाएँ, VibeFox USPS के बगल वाला मेनू खोलें और Uninstall चुनें। लाइसेंस कुंजी और लाइसेंस स्थिति हमेशा हटाई जाती हैं। कैश किया गया टोकन और रेट भी हमेशा हटाए जाते हैं। यदि Remove data on uninstall चालू है, तो कैरियर हटा दिया जाता है (ऑर्डर अपना इतिहास रखते हैं) और सेटिंग्स, सहेजी गई ऑर्डर सेवाएँ और लॉग भी हटा दिए जाते हैं। यदि यह बंद है, तो कैरियर केवल निष्क्रिय होता है और सभी सेटिंग्स रहती हैं। मॉड्यूल फिर से इंस्टॉल करने पर, या Reset से, सहेजे गए कैरियर को उसकी पिछली स्थिति मिल जाती है: जो कैरियर चालू था वह फिर चालू होता है, और जो निष्क्रिय था वह निष्क्रिय ही रहता है।

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