VibeFox UPS for PrestaShop — सहायता

आवश्यकताएँ

PrestaShop: 8.0 से 9.x.

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

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

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

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

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

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

6. वैकल्पिक रूप से बैकअप के रूप में निश्चित मूल्य दर्ज करें और Save पर क्लिक करें।

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

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

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

सेटिंग्स के ऊपर की चेतावनियाँ बताती हैं कि जब Client ID और Client Secret में से केवल एक सेट है, कोई क्रेडेंशियल्स और निश्चित मूल्य नहीं हैं (तब कैरियर कभी नहीं दिखता), ship-from का पोस्टल कोड या राज्य गायब है, बिना खाता नंबर के खाता दरें चुनी गई हैं, विनिमय दर गायब है, या स्टोर की वज़न या आयाम इकाई मॉड्यूल के लिए अज्ञात है। अमान्य संख्याएँ, गलत बॉक्स आकार और Max weight से ज़्यादा Min weight सेव करते समय बताए जाते हैं, और पुराना मूल्य रखा जाता है।

सामान्य

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

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

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

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

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

Client ID: UPS Developer Portal में आपके ऐप का Client ID। इसे खाली करने से सहेजा गया Client Secret भी हट जाता है।

Client Secret: उसी ऐप का Client Secret। सेव करने के बाद यह फ़ील्ड खाली रहता है और Saved — leave empty to keep it. दिखाता है। बदलने के लिए ही नया मूल्य दर्ज करें।

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

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

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

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

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

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

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

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

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

State / province code: 2-अक्षरों वाला कोड, अमेरिका और कनाडा के लिए आवश्यक, जैसे NY, CA या ON।

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

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

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

Country prices: आपके स्टोर की डिफ़ॉल्ट मुद्रा में, टैक्स रहित मूल्य, गंतव्य देश के अनुसार। पंक्ति जोड़ने के लिए Add country पर और पंक्ति हटाने के लिए हटाने वाले बटन पर क्लिक करें। देश * अन्य सभी देशों पर लागू होता है। एक वज़न कॉलम (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: कार्ट का सबटोटल (शिप होने वाले उत्पाद, छूट के बाद, टैक्स से पहले) जिससे यह कैरियर मुफ़्त है। तब UPS को कोई अनुरोध नहीं भेजा जाता। कभी भी मुफ़्त शिपिंग न देने के लिए इसे खाली छोड़ें।

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

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

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

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

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

आमतौर पर कैरियर उन ज़ोन में दिया जाता है जिनमें वह Shipping > Carriers में सौंपा गया है।

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

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

एडवांस्ड

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

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

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

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

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

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

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

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

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

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

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

ऑर्डर

जब लाइव UPS दर पर ऑर्डर दिया जाता है, तो UPS सेवा ऑर्डर के साथ सहेजी जाती है। बैक ऑफिस के ऑर्डर पेज पर UPS service (उदाहरण के लिए UPS Ground) और Live rate (excl. tax) के साथ एक UPS ब्लॉक दिखता है। बैक ऑफिस में बाद में कार्ट में किए गए बदलाव इसे नहीं बदलते। निश्चित मूल्य या मुफ़्त शिपिंग वाले ऑर्डर में ऐसा ब्लॉक नहीं होता।

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

यह मॉड्यूल vibefox.net से प्राप्त VibeFox लाइसेंस कुंजी के साथ काम करता है। लाइसेंस ब्लॉक License — VibeFox UPS, Modules > Module Manager > VibeFox UPS > Configure पेज पर पहला ब्लॉक है, जो सेटिंग्स के ऊपर होता है। कुंजी License key में दर्ज करें और Activate पर क्लिक करें। इसके बाद ब्लॉक में मास्क की गई कुंजी, स्थिति (जैसे वह तारीख जिस तक लाइसेंस सक्रिय है, और आपका डोमेन) और ये बटन दिखते हैं: स्थिति फिर से जाँचने के लिए Check now, दूसरी कुंजी दर्ज करने के लिए Change key, और इस स्टोर से कुंजी हटाने के लिए Remove key। इनके नीचे Product: presta-shipping-ups वाली पंक्ति और 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 खाते में स्लॉट खाली करें।

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

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

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

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

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

पेज चेतावनी देता है कि स्टोर का वज़न या आयाम इकाई अज्ञात है: तब वज़न kg और बॉक्स आकार cm माना जाता है। International > Localization में, Local units सेक्शन में एक मानक इकाई (kg, g, lb या oz; cm, mm, m या in) सेट करें।

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

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

डेवलपर्स के लिए: हुक actionVfdUpsxAllowedServices और actionVfdUpsxExcludedServices दिखाई जा सकने वाली UPS सेवाओं को सीमित करते हैं। actionVfdUpsxRateRequest दर अनुरोध बदलता है, actionVfdUpsxApiBaseUrl API पता, और actionVfdUpsxCurrencyCodes UPS द्वारा लौटाए गए मुद्रा कोड को मैप करता है।

अनइंस्टॉल

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

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