VibeFox SMSA Express for PrestaShop — सहायता

आवश्यकताएँ

PrestaShop: 8.0 से 9.x।

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

SMSA Express दर सूची: मूल्य तालिका के मूल्य आपके SMSA खाते या SMSA की बिक्री टीम से आते हैं। इन्हें अपने स्टोर की डिफ़ॉल्ट मुद्रा में दर्ज करें। यदि आपकी दर सूची SAR, AED या किसी अन्य मुद्रा में है, तो पहले उसे परिवर्तित करें।

SMSA passKey (केवल लाइव शुल्कों के लिए): लाइव शुल्क SMSA वेब सेवा (SECOM, operation getShipCharges) का उपयोग करते हैं। SMSA अनुरोध पर passKey जारी करता है: अपने SMSA खाता प्रबंधक से पूछें, या info@smsaexpress.com पर लिखकर अपना खाता नंबर बताते हुए SMSA वेब सेवा तक पहुँच माँगें। passKey, SMSA ई-कॉमर्स पोर्टल की API कुंजी से अलग हो सकती है। इस सेवा के लिए SMSA के पास टेस्ट (sandbox) सर्वर नहीं है।

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

इंस्टॉलेशन

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

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

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

4. मूल्य तालिका में अपने SMSA Express मूल्य दर्ज करें और Save पर क्लिक करें।

5. वैकल्पिक: Live rates (API) के अंतर्गत Live charges चालू करें, अपनी SMSA passKey, भेजने वाला शहर और देश दर्ज करें, और यदि आपके स्टोर की डिफ़ॉल्ट मुद्रा SAR नहीं है तो विनिमय दर भी दर्ज करें।

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

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

सभी सेटिंग्स मॉड्यूल पेज पर हैं: Modules > Module Manager > VibeFox SMSA Express > Configure। हर अनुभाग का अपना Save बटन है, जो पूरा पेज सहेजता है। हर सहेजने पर कैश किए गए SMSA शुल्क भी साफ़ हो जाते हैं। गैर-संख्यात्मक मान, ऋणात्मक संख्या, 0 की विनिमय दर, 3 अक्षरों से भिन्न मुद्रा कोड, या Maximum weight से बड़ा Minimum weight त्रुटि के साथ अस्वीकार कर दिए जाते हैं, और जब तक आप मान ठीक नहीं करते, कुछ भी सहेजा नहीं जाता।

लाइव शुल्क चालू होने पर, सेटिंग्स के ऊपर की चेतावनियाँ बताती हैं कि passKey, भेजने वाला शहर या विनिमय दर गायब है, या मूल्य तालिका खाली है। यदि मॉड्यूल स्टोर की वज़न इकाई नहीं पहचानता (तब उत्पादों का वज़न kg माना जाता है), तो भी चेतावनी दिखती है। International > Localization (Local units) में kg, g, lb या oz सेट करें।

सामान्य

Enable SMSA Express: कैरियर को सभी ज़ोन में एक साथ चालू या बंद करता है। यह Shipping > Carriers में कैरियर की स्थिति वाला ही स्विच है।

Method title: कार्ट और चेकआउट में दिखाया जाने वाला कैरियर का नाम। डिफ़ॉल्ट: SMSA Express। आवश्यक, अधिकतम 64 अक्षर।

Tax: कैरियर का कर नियम, या No tax। यदि आपके मूल्य (तालिका और SMSA शुल्क) पहले से कर शामिल करते हैं, जैसे सऊदी VAT, तो No tax चुनें।

लाइव दरें (API) (वैकल्पिक; यदि SMSA कोई शुल्क नहीं लौटाता, तो मूल्य तालिका उपयोग होती है)

Live charges: SMSA Express से शिपिंग शुल्क प्राप्त करता है। डिफ़ॉल्ट: बंद।

SMSA passKey: SMSA वेब सेवा (SECOM) की कुंजी। सहेजने के बाद यह फ़ील्ड खाली रहता है और Saved — leave empty to keep it दिखाता है। नया मान केवल तभी दर्ज करें जब उसे बदलना हो। सहेजी गई passKey हटाने के लिए Remove the saved passKey पर निशान लगाएँ। यदि लॉग में "Invalid Passkey" दिखे, तो इस सेवा ने यह कुंजी स्वीकार नहीं की। SMSA से वेब सेवा के लिए passKey माँगें।

Ship-from city: वह शहर जहाँ से आपके पार्सल भेजे जाते हैं, SMSA की वर्तनी के अनुसार लिखा हुआ, जैसे Riyadh, Jeddah या Dammam। स्टोर का शहर Shop Parameters > Contact > Stores से उपयोग करने के लिए खाली छोड़ें।

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

Shipment type: SMSA को शिपमेंट प्रकार के रूप में भेजा जाता है। DLV (डिफ़ॉल्ट) मानक डिलीवरी है। इसे तभी बदलें जब SMSA ने आपको कोई अन्य कोड दिया हो।

Currency of SMSA charges: SMSA हर शुल्क उसके मुद्रा कोड के साथ लौटाता है, आमतौर पर SAR (डिफ़ॉल्ट)। इस मुद्रा या आपके स्टोर की डिफ़ॉल्ट मुद्रा के अलावा किसी अन्य मुद्रा का शुल्क उपयोग नहीं होता।

Exchange rate: SMSA मुद्रा की 1 इकाई का आपकी स्टोर की डिफ़ॉल्ट मुद्रा में मूल्य, जैसे 0.27। जब दोनों मुद्राएँ समान हों तो इसकी ज़रूरत नहीं होती। इसके बिना, किसी अन्य मुद्रा के शुल्क उपयोग नहीं होते और मूल्य तालिका लागू होती है। दशमलव विभाजक के रूप में बिंदु और अल्पविराम दोनों स्वीकार्य हैं।

मूल्य (आपके स्टोर की डिफ़ॉल्ट मुद्रा में आपकी SMSA Express दर सूची; लाइव शुल्क बंद होने पर उपयोग होती है, और SMSA कोई शुल्क न लौटाए तो बैकअप के रूप में)

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

Price for countries not in the table: तब उपयोग होता है जब तालिका में गंतव्य देश के लिए कोई पंक्ति नहीं है (और * पंक्ति भी नहीं), या पंक्ति में इस वज़न का मूल्य नहीं है। उस स्थिति में कैरियर छिपाने के लिए इसे खाली छोड़ें।

Price applies: मूल्य की गणना कैसे होती है।

उत्पादों का वज़न आपकी स्टोर इकाई से किलोग्राम में बदला जाता है।

शर्तें

Minimum weight: कार्ट इससे हल्का हो तो कैरियर छिपाता है, kg में। 0 का अर्थ है कोई सीमा नहीं।

Maximum weight: कार्ट इससे भारी हो तो कैरियर छिपाता है, kg में। डिफ़ॉल्ट: 30। 0 या खाली फ़ील्ड का अर्थ है कोई सीमा नहीं।

Minimum order amount: कैरियर केवल तभी दिखाता है जब कार्ट का उप-योग (छूट के बाद, कर से पहले) यह राशि पूरी करता है। हमेशा दिखाने के लिए खाली छोड़ें।

Free shipping from: कार्ट का उप-योग (छूट के बाद, कर से पहले) जिससे SMSA Express शिपिंग मुफ़्त होती है। जब कार्ट यह राशि पहुँचता है, तो मूल्य 0 होता है और SMSA को कोई अनुरोध नहीं भेजा जाता। कभी मुफ़्त शिपिंग न देने के लिए खाली छोड़ें।

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

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

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

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

उन्नत

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

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

Remove data on uninstall: चालू होने पर मॉड्यूल अनइंस्टॉल करने से SMSA Express सेटिंग्स, कैरियर और लॉग हट जाते हैं। बंद होने पर दोबारा इंस्टॉल के लिए सब कुछ रखा जाता है। कैश किए गए शुल्क हमेशा हटाए जाते हैं।

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

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

लाइव शुल्क चालू होने पर, मॉड्यूल SMSA को आपका भेजने वाला शहर और देश, ग्राहक का शहर और देश, शिपमेंट प्रकार, kg में पार्सल का वज़न, और 0 की कैश ऑन डिलीवरी राशि भेजता है। SMSA शुल्क और उसकी मुद्रा लौटाता है। मॉड्यूल उसे आपकी स्टोर की डिफ़ॉल्ट मुद्रा में बदलता है, फिर मूल्य ग्राहक की कार्ट मुद्रा में दिखाया जाता है। लाइव शुल्क केवल तभी माँगा जाता है जब ग्राहक शहर सहित डिलीवरी पता दर्ज कर चुका हो।

हर शुल्क एक घंटे तक कैश होता है, इसलिए वही कार्ट नया अनुरोध नहीं बनाता। विफल अनुरोध 5 मिनट तक कैश होता है। टाइमआउट या सर्वर त्रुटि के बाद 2 मिनट तक SMSA से दोबारा नहीं पूछा जाता। अस्वीकृत कुंजी के बाद 5 मिनट तक नहीं पूछा जाता। इस तरह चेकआउट हर रीफ़्रेश पर खराब सेवा का इंतज़ार नहीं करता। अनुरोध का टाइमआउट 12 सेकंड है।

जब भी SMSA कोई उपयोगी शुल्क नहीं लौटाता (passKey नहीं, शहर अभी दर्ज नहीं, उत्पादों का वज़न गायब, अमान्य कुंजी, टाइमआउट, त्रुटि, शहर के लिए सेवा नहीं, या अज्ञात मुद्रा), तब मूल्य तालिका उपयोग होती है। यदि तालिका और Price for countries not in the table कोई मूल्य नहीं देते, तो कैरियर छिप जाता है। ग्राहक को कभी त्रुटि नहीं दिखती। कारण लॉग में लिखा जाता है।

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

मॉड्यूल केवल शिपिंग मूल्य की गणना करता है। यह SMSA शिपमेंट नहीं बनाता, AWB लेबल प्रिंट नहीं करता, रिटर्न नहीं संभालता और पार्सल ट्रैक नहीं करता। कैश ऑन डिलीवरी और उसका शुल्क लाइव शुल्क में शामिल नहीं हैं। SMSA खुदरा बिंदु चुनने की कोई सुविधा नहीं है: कैरियर घर-घर डिलीवरी है।

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

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

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

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

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

चेकआउट पर SMSA Express दिखाई नहीं देता: जाँचें कि लाइसेंस सक्रिय है और Enable SMSA Express चालू है। Shipping > Carriers में जाँचें कि कैरियर ग्राहक के देश के ज़ोन और ग्राहक के समूह को कवर करता है (या यह कि Ignore shipping zones चालू है और देश की अनुमति है)। वज़न सीमाएँ और Minimum order amount जाँचें। जाँचें कि देश या * का मूल्य है, या Price for countries not in the table सेट है। इसके अलावा, उत्पाद पेज पर उत्पाद कुछ कैरियर तक सीमित हो सकते हैं।

ग्राहकों को SMSA शुल्क की जगह तालिका मूल्य दिखता है: SMSA को ग्राहक का शहर चाहिए, इसलिए उसके दर्ज होने तक तालिका मूल्य दिखता है। तालिका तब भी उपयोग होती है जब SMSA जवाब नहीं देता, कुंजी या शहर अस्वीकार करता है, या विनिमय दर के बिना मुद्रा में शुल्क लौटाता है। कारण के लिए मॉड्यूल पेज पर Log फ़ील्ड देखें।

लॉग में "Invalid Passkey": SMSA वेब सेवा इस कुंजी को स्वीकार नहीं करती। SMSA से वेब सेवा के लिए passKey माँगें।

ग्राहक का शहर स्वीकार नहीं होता: SMSA अपनी शहर वर्तनी की अपेक्षा रखता है। डिलीवरी पते में शहर और Ship-from city जाँचें।

सेटिंग्स सहेजी नहीं जातीं और त्रुटि दिखती है: एक संख्या फ़ील्ड में टेक्स्ट या ऋणात्मक मान है, विनिमय दर 0 है, मुद्रा कोड 3 अक्षरों का नहीं है, या Minimum weight, Maximum weight से अधिक है। संदेश में बताया गया मान ठीक करें और फिर Save पर क्लिक करें।

शिपिंग पर कर दो बार लगता है: आपकी दर सूची या SMSA शुल्कों में VAT पहले से शामिल हो सकता है। Tax को No tax पर सेट करें।

बदलाव के बाद दरें पुरानी लगती हैं: मॉड्यूल पेज पर Save पर क्लिक करें। इससे कैश किए गए SMSA शुल्क साफ़ हो जाते हैं।

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

अनइंस्टॉल

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

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