VibeFox UPS for WooCommerce — सहायता

आवश्यकताएँ

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

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

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

UPS Developer Portal ऐप (केवल लाइव दरों के लिए): UPS Developer Portal (developer.ups.com) में लॉग इन करें, "Rating" उत्पाद वाला ऐप बनाएँ, अपना UPS खाता जोड़ें, और Client ID व Client Secret कॉपी करें। प्लगइन OAuth 2.0 का उपयोग करता है। Access Key, यूज़रनेम या पासवर्ड की ज़रूरत नहीं है। नेगोशिएटेड दरों के लिए आपको अपना 6-अक्षर वाला UPS खाता नंबर भी चाहिए। क्रेडेंशियल्स के बिना केवल निश्चित मूल्य इस्तेमाल होते हैं।

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

इंस्टॉलेशन

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

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

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

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

5. Client ID और Client Secret, अपना UPS खाता नंबर (नेगोशिएटेड दरों के लिए) और Ship from पता डालें: पोस्टल कोड और अमेरिका व कनाडा के लिए 2-अक्षर का राज्य कोड।

6. यदि आपके UPS खाते की मुद्रा स्टोर मुद्रा से अलग है, तो UPS account currency और Exchange rate डालें।

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

8. वैकल्पिक रूप से बैकअप के लिए निश्चित मूल्य डालें।

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

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

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

हर बार सेटिंग्स सेव करने पर कैश किया गया UPS टोकन और दरें साफ़ हो जाती हैं। आप UPS API सेक्शन में Clear cached UPS token and rates पर भी क्लिक कर सकते हैं। सेटिंग्स के ऊपर की चेतावनियाँ बताती हैं कि Client ID और Client Secret में से केवल एक भरा है, कोई क्रेडेंशियल्स और निश्चित मूल्य नहीं हैं, शिप-फ़्रॉम पोस्टल कोड या राज्य गायब है, खाता नंबर के बिना खाता दरें चुनी गई हैं, या विनिमय दर नहीं है।

General

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

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

Tax status: Taxable से WooCommerce अपना शिपिंग टैक्स ऊपर जोड़ता है, None से नहीं जोड़ता। UPS दरें बिना टैक्स के दी जाती हैं, इसलिए टैक्स दोबारा नहीं लगता।

UPS API (लाइव दरें)

Test mode: UPS के टेस्ट वातावरण का उपयोग करता है। टेस्ट दरें असली कीमतें नहीं हैं। लाइव दरों के लिए इसे बंद करें। डिफ़ॉल्ट: बंद।

Client ID: UPS Developer Portal में आपके ऐप का Client ID।

Client Secret: उसी ऐप का Client Secret।

UPS account number: आपका 6-अक्षर वाला UPS शिपर नंबर, उदाहरण के लिए A1B2C3। खाता (नेगोशिएटेड) दरों के लिए ज़रूरी है, प्रकाशित दरों के लिए वैकल्पिक।

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

Measurement units: UPS को भेजी जाने वाली इकाइयाँ। स्टोर के वज़न और आकार बदले जाते हैं।

Residential delivery: ग्राहक के पते को UPS के आवासीय अधिभार के साथ आवासीय पते के रूप में आँकता है। यदि आप ज़्यादातर व्यवसायों को भेजते हैं तो इसे बंद करें। डिफ़ॉल्ट: चालू।

Box size: आपकी स्टोर आयाम इकाई में वैकल्पिक बॉक्स आयाम, उदाहरण के लिए 30x20x15। इसे सेट करने पर UPS डायमेंशनल वज़न लागू करता है। केवल वज़न से दर निकालने के लिए इसे खाली छोड़ें।

UPS account currency: UPS शिपर खाते वाले देश की मुद्रा में दर देता है, उदाहरण के लिए अमेरिका के लिए USD, कनाडा के लिए CAD या यूरो क्षेत्र के लिए EUR। डिफ़ॉल्ट: USD।

Exchange rate: केवल तभी ज़रूरी है जब UPS खाते की मुद्रा स्टोर मुद्रा से अलग हो। खाता मुद्रा की 1 इकाई का मूल्य अपनी स्टोर मुद्रा में डालें, उदाहरण के लिए 0.92। इसके बिना ऐसी दरें उपयोग नहीं होतीं और निश्चित मूल्य लागू होते हैं। विनिमय दरें अपने-आप अपडेट नहीं होतीं।

शिप-फ़्रॉम पता (वह पता जहाँ से UPS पार्सल उठाता है या जहाँ आप पार्सल छोड़ते हैं; लाइव दरों के लिए उपयोग होता है)

Country: वह देश जहाँ से आप शिपिंग करते हैं। डिफ़ॉल्ट रूप से आपके स्टोर का देश।

State / province code: 2-अक्षर का कोड, अमेरिका और कनाडा के लिए अनिवार्य, उदाहरण के लिए NY, CA या ON।

City: वह शहर जहाँ से आप शिपिंग करते हैं।

ZIP / postal code: वह पोस्टल कोड जहाँ से आप शिपिंग करते हैं। दरें निकालने के लिए UPS को इसकी ज़रूरत होती है।

निश्चित मूल्य (जब कोई API क्रेडेंशियल्स नहीं डाले गए हों तब उपयोग होते हैं, और UPS दर न दे तब बैकअप के रूप में भी; इस स्थिति में विधि छिपाने के लिए दोनों खाली छोड़ें)

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

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

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

शर्तें

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

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

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

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

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

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

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

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

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

उन्नत

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

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

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

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

प्लगइन UPS से एक OAuth टोकन लेता है और उसकी समाप्ति तक रखता है। UPS द्वारा अस्वीकार किया गया टोकन अपने-आप नवीनीकृत हो जाता है। फिर प्लगइन आपके शिप-फ़्रॉम पते से ग्राहक के पते तक की सभी सेवाओं के लिए, पूरे कार्ट को एक पैकेज मानकर, UPS Rating API से पूछता है। जिन देशों में पोस्टल कोड होता है, वहाँ अनुरोध तब तक रुकता है जब तक ग्राहक कोड न डाले। अमेरिका से कनाडा या पुएर्तो रिको के शिपमेंट के लिए UPS की आवश्यकता के अनुसार सामान का मूल्य भेजा जाता है।

ग्राहक को एक विकल्प दिखता है जिसमें सबसे सस्ती UPS सेवा है, जिसे आपकी स्टोर मुद्रा में बदला गया है। UPS Access Point Economy की दर नहीं दी जाती, क्योंकि प्लगइन Access Point का पता नहीं लेता।

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

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

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

प्लगइन केवल दरें निकालता है। यह UPS Access Point चुनने का विकल्प नहीं देता, शिपिंग लेबल या UPS शिपमेंट नहीं बनाता, पिकअप बुक नहीं करता और पार्सल ट्रैक नहीं करता। यह कई UPS सेवाओं के बजाय एक ही विकल्प दिखाता है। बॉक्स पैकिंग नहीं होती: कार्ट को एक पैकेज के रूप में आँका जाता है। विनिमय दरें स्वचालित नहीं हैं।

ऑर्डर

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

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

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

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

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

लाइसेंस की अवधि समाप्त होने पर प्लगइन काम करता रहता है, लेकिन अपडेट और सहायता के लिए नवीनीकरण ज़रूरी है। स्थिति पृष्ठभूमि में अपने-आप फिर से जाँची जाती है।

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

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

लाइव दरें नहीं दिखतीं: सेटिंग्स पेज के ऊपर की चेतावनियाँ देखें। Debug log चालू करें और WooCommerce > Status > Logs खोलें, स्रोत vfd-ups। इसमें OAuth त्रुटियाँ (Client ID, Client Secret और Test mode जाँचें), UPS की त्रुटि संदेश और मुद्रा की समस्याएँ दिखती हैं।

दर USD में है, लेकिन स्टोर की मुद्रा अलग है: UPS दरें शिपर खाते की मुद्रा में देता है। UPS account currency और Exchange rate सेट करें। विनिमय दर के बिना ऐसी दरें अनदेखी होती हैं और निश्चित कीमत इस्तेमाल होती है।

"This measurement system is not valid for the selected country": Measurement units को Automatic पर रहने दें, या अपने शिप-फ़्रॉम देश के लिए UPS जो इकाइयाँ चाहता है वे चुनें।

बदलाव के बाद दरें पुरानी लगती हैं: सेटिंग्स पेज सेव करें या Clear cached UPS token and rates पर क्लिक करें।

डेवलपर्स के लिए: फ़िल्टर vfd_upsx_allowed_services और vfd_upsx_excluded_services दिखाई जा सकने वाली UPS सेवाओं को सीमित करते हैं। vfd_upsx_rate_request दर अनुरोध बदलता है, vfd_upsx_api_base_url API पता, और vfd_upsx_currency_codes UPS द्वारा लौटाए गए मुद्रा कोड को मैप करता है।

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

अनइंस्टॉल

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

UPS संबंधित स्वामी का ट्रेडमार्क है। यह प्लगइन UPS से संबद्ध नहीं है और UPS द्वारा समर्थित नहीं है।