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

आवश्यकताएँ

PrestaShop: 8.0 से 9.x।

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

SF Express खाता (केवल लाइव मूल्यों के लिए): लाइव मूल्य SF Express FengQiao ओपन प्लेटफ़ॉर्म (open.sf-express.com) का उपयोग करते हैं। आपको SF Express मासिक खाता और FengQiao पर एक डेवलपर खाता चाहिए। वहाँ रजिस्टर करें, एक एप्लिकेशन बनाएँ, उसमें API "Delivery time standard and price query" (EXP_RECE_QUERY_DELIVERTM) जोड़ें और ग्राहक कोड तथा checkword कॉपी करें। सैंडबॉक्स और प्रोडक्शन के checkword अलग होते हैं। यदि आप केवल मूल्य तालिका उपयोग करते हैं, तो आपको SF Express खाते की आवश्यकता नहीं है।

चीनी प्रांत (केवल लाइव मूल्यों के लिए): लाइव मूल्य के लिए डिलीवरी पते का प्रांत चाहिए। PrestaShop में डिफ़ॉल्ट रूप से चीन के प्रांत नहीं होते। मॉड्यूल इन्हें आपके लिए जोड़ सकता है (नीचे Chinese provinces देखें)।

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

इंस्टॉलेशन

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

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

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

4. मूल्य तालिका और/या बैकअप लागत भरें और Save पर क्लिक करें।

5. मेनलैंड चीन में लाइव मूल्यों के लिए, ग्राहक कोड और checkword, प्रेषक प्रांत और शहर (या चीन में स्टोर का पता सेट करें) और, यदि आपकी स्टोर मुद्रा CNY नहीं है, तो मुद्रा रूपांतरण दर दर्ज करें। यदि पेज माँगे तो Add Chinese provinces पर क्लिक करें। पहले Sandbox और सैंडबॉक्स क्रेडेंशियल्स से परीक्षण करें।

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

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

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

सेव करते समय मॉड्यूल संख्याओं की जाँच करता है। जो मान संख्या नहीं है, ऋणात्मक राशि या वज़न, 0 की मुद्रा रूपांतरण दर, Max weight से बड़ा Min weight, या मूल्य तालिका में गलत मूल्य एक संदेश के साथ अस्वीकार हो जाते हैं, और आपके सुधारने तक कुछ भी सेव नहीं होता। सेटिंग्स के ऊपर की चेतावनियाँ बताती हैं कि लाइव मूल्य आंशिक रूप से सेट हैं (छूटी हुई सेटिंग्स की सूची दी जाती है), मुद्रा रूपांतरण दर नहीं है, चीनी पतों में प्रांत फ़ील्ड नहीं है, या आपके स्टोर की वज़न या आयाम इकाई मॉड्यूल को ज्ञात नहीं है। इकाइयाँ International > Localization (Local units) में सेट होती हैं।

सामान्य

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

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

Tax: कैरियर का टैक्स नियम, या No tax। टैक्स नियम के साथ, आपके स्टोर का शिपिंग टैक्स लागत के ऊपर जुड़ता है। यदि SF Express का मूल्य पहले से वह सब शामिल करता है जो आप वसूलना चाहते हैं, तो No tax चुनें।

SF Express FengQiao API (लाइव मूल्य) (वैकल्पिक, मेनलैंड चीन के डिलीवरी पतों के लिए)

Customer code (partnerID): आपके FengQiao एप्लिकेशन का ग्राहक कोड (顾客编码)। इसे साफ़ करने पर सहेजा गया checkword भी साफ़ हो जाता है, ताकि आप क्रेडेंशियल्स हटा सकें।

Checkword: उसी वातावरण का checkword (校验码)। इसका उपयोग केवल अनुरोधों पर हस्ताक्षर करने के लिए होता है और यह कभी भेजा या लॉग नहीं किया जाता। सेव करने के बाद यह फ़ील्ड खाली रहता है और Saved — leave empty to keep it. दिखाता है। केवल बदलने के लिए नया मान दर्ज करें।

Sandbox: सैंडबॉक्स क्रेडेंशियल्स के साथ परीक्षण के लिए FengQiao सैंडबॉक्स (sfapi-sbox.sf-express.com) का उपयोग करता है। सैंडबॉक्स मूल्य असली नहीं होते। लाइव स्टोर में इसे बंद करें। डिफ़ॉल्ट: बंद।

SF Express product: कौन सा SF Express उत्पाद का मूल्य दिखाया जाए।

Cheapest product offered by SF Express: डिफ़ॉल्ट। SF Express द्वारा लौटाया गया सबसे कम मूल्य उपयोग होता है।

SF Express Priority (顺丰特快, code 1): केवल इस उत्पाद का मूल्य।

SF Standard Express (顺丰标快, code 2): केवल इस उत्पाद का मूल्य।

Sender province: वह प्रांत जहाँ से पार्सल भेजे जाते हैं। यदि स्टोर चीन में है, तो Shop Parameters > Contact > Stores में स्टोर पते के प्रांत का उपयोग करने के लिए खाली छोड़ें।

Sender city: मानक चीनी शहर का नाम, जैसे 深圳市। यदि स्टोर चीन में है, तो स्टोर के शहर का उपयोग करने के लिए खाली छोड़ें।

Currency conversion rate: SF Express के मूल्य CNY (युआन) में होते हैं। यदि आपके स्टोर की डिफ़ॉल्ट मुद्रा CNY नहीं है, तो बताएँ कि एक CNY आपकी मुद्रा की कितनी इकाइयों के बराबर है (1 CNY = ? इकाइयाँ)। इसके बिना लाइव मूल्य उपयोग नहीं होते। यदि आपके स्टोर की मुद्रा CNY है, तो मूल्य जैसे हैं वैसे ही उपयोग होते हैं। दशमलव विभाजक के रूप में बिंदु और अल्पविराम दोनों स्वीकार्य हैं।

Chinese provinces: दिखाता है कि चीनी पतों में प्रांत हो सकता है या नहीं। नहीं हो, तो Add Chinese provinces पर क्लिक करें। यह बटन 32 प्रांत, स्वायत्त क्षेत्र और नगरपालिकाएँ चीन के states के रूप में जोड़ता है (GD और BJ जैसे ISO कोड, "Guangdong / 广东" जैसे नाम), चीन के लिए "Contains states" चालू करता है और चीनी पते के फ़ॉर्म में state फ़ील्ड जोड़ता है। जो प्रांत पहले से मौजूद हैं, उन्हें दोबारा नहीं जोड़ा जाता। इस क्लिक के बिना कुछ नहीं बदलता।

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

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

Fallback cost: तब उपयोग होती है जब न SF Express और न तालिका कोई मूल्य देती हैं। उस स्थिति में कैरियर छिपाने के लिए खाली छोड़ें।

Table / fallback price is: तालिका और बैकअप मूल्य कैसे वसूले जाते हैं।

Per order (tier by the total cart weight): कार्ट के कुल वज़न से मेल खाने वाली श्रेणी का मूल्य, एक बार वसूला जाता है।

Per item (every item is priced by its own weight): हर आइटम का मूल्य उसकी अपनी वज़न श्रेणी से तय होता है और उसकी मात्रा से गुणा किया जाता है। बैकअप लागत आइटमों की संख्या से गुणा होती है।

SF Express के लाइव मूल्य हमेशा पूरे ऑर्डर के लिए होते हैं।

शर्तें

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

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

Min weight: कार्ट का न्यूनतम वज़न kg में। उत्पादों के वज़न आपकी स्टोर वज़न इकाई से बदले जाते हैं। 0 का अर्थ कोई सीमा नहीं।

Max weight: कार्ट का अधिकतम वज़न kg में। डिफ़ॉल्ट: 50। 0 या खाली का अर्थ कोई सीमा नहीं।

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

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

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

उन्नत

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

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

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

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

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

ग्राहक कोड और checkword सेट होने पर, मेनलैंड चीन के डिलीवरी पते के लिए मॉड्यूल SF Express को आपका प्रेषक प्रांत और शहर, ग्राहक का प्रांत और शहर, कार्ट का वज़न और कार्ट का आयतन (उन उत्पादों से जिनके तीनों आयाम हैं) भेजता है। अनुरोध आपके checkword से हस्ताक्षरित होता है। SF Express CNY में मूल्य लौटाता है, और मॉड्यूल चुने गए मूल्य को आपकी स्टोर की डिफ़ॉल्ट मुद्रा में बदलता है। फिर मूल्य ग्राहक की कार्ट मुद्रा में दिखाया जाता है।

SF Express मानक चीनी नामों से पते पहचानता है। ग्राहक का प्रांत पते के state फ़ील्ड से आता है। शहर चीनी में लिखा होना चाहिए, जैसे 广州市। बीजिंग, शंघाई, तियानजिन और चोंगकिंग के लिए शहर अपने-आप भर जाता है। "Guangzhou" जैसे लैटिन अक्षरों में लिखे शहर को तालिका का मूल्य मिलता है।

हर मूल्य एक घंटे के लिए कैश होता है, इसलिए वही कार्ट नया अनुरोध नहीं भेजता। विफल अनुरोध 10 मिनट के लिए कैश होता है, ताकि चेकआउट हर रीफ़्रेश पर SF Express का इंतज़ार न करे। HTTP टाइमआउट 10 सेकंड है।

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

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

मॉड्यूल केवल मूल्यों की गणना करता है। यह वेबिल या लेबल नहीं बनाता, SF Express में ऑर्डर नहीं बनाता, पिकअप बुक नहीं करता, शिपमेंट रद्द या ट्रैक नहीं करता। शिपमेंट हमेशा की तरह अपने SF Express खाते में बनाएँ और ट्रैक करें। ग्राहक SF सर्विस पॉइंट या लॉकर नहीं चुन सकते। SF Express का उपयोग डोर-टू-डोर कूरियर के रूप में होता है। लाइव मूल्य केवल मेनलैंड चीन के डिलीवरी पतों के लिए मौजूद हैं। यह मॉड्यूल FengQiao दस्तावेज़ और नकली (mocked) प्रतिक्रियाओं के आधार पर बना है, इसलिए लाइव जाने से पहले (पहले सैंडबॉक्स में) मूल्यों की पुष्टि अपने SF Express खाते से करें।

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

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

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

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

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

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

मूल्य तालिका से आ रहा है, SF Express से नहीं: लाइव मूल्यों के लिए ग्राहक कोड और checkword, प्रेषक प्रांत और शहर, प्रांत और चीनी शहर के नाम वाला मेनलैंड चीन का डिलीवरी पता, और (गैर-CNY स्टोर के लिए) मुद्रा रूपांतरण दर चाहिए। मॉड्यूल पेज के शीर्ष की चेतावनियाँ पढ़ें, फिर Debug log चालू करें, चेकआउट रीलोड करें और कारण देखने के लिए Log फ़ील्ड देखें। विफल अनुरोध 10 मिनट बाद फिर से किया जाता है।

चीन के पते के फ़ॉर्म में प्रांत नहीं है: मॉड्यूल पेज के API सेक्शन में Add Chinese provinces पर क्लिक करें।

लॉग में त्रुटि A1006: अमान्य हस्ताक्षर। checkword गलत है या दूसरे वातावरण का है। Sandbox सेटिंग जाँचें।

लॉग में त्रुटि A1004: मूल्य पूछताछ API आपके FengQiao एप्लिकेशन में नहीं जोड़ा गया है।

हॉन्गकॉन्ग: मूल्य तालिका और बैकअप लागत के साथ काम करता है। FengQiao मूल्य पूछताछ केवल मेनलैंड चीन के पतों के लिए है।

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

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

डेवलपर्स के लिए: हुक actionVfdSfExpressQuoteRequest मूल्य अनुरोध बदलता है, उदाहरण के लिए किसी दूसरे उत्पाद कोड पर। actionVfdSfExpressApiUrl गेटवे URL बदलता है।

अनइंस्टॉल

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

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