VibeFox NZ Post for WooCommerce — सहायता

आवश्यकताएँ

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

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

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

NZ Post API एक्सेस (केवल रीयल-टाइम दरों के लिए): रीयल-टाइम दरें NZ Post ShippingOptions API इस्तेमाल करती हैं। NZ Post की वेबसाइट पर Developer Resource Centre में API एक्सेस का अनुरोध करें। NZ Post पहले टेस्टिंग एनवायरनमेंट (UAT) के लिए Client ID और Client Secret देता है, और फिर अपनी go-live चेकलिस्ट पूरी होने के बाद प्रोडक्शन के लिए। न्यूज़ीलैंड के भीतर की दरों के लिए आपको NZ Post बिज़नेस खाता भी चाहिए: खाता नंबर और उसका auth code (या site code)। अगर आप केवल फ़िक्स्ड कीमतें इस्तेमाल करते हैं, तो API एक्सेस की ज़रूरत नहीं है।

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

इंस्टॉलेशन

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

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

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

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

5. रीयल-टाइम दरों के लिए NZ Post API (live rates) सेक्शन भरें। वैकल्पिक रूप से फ़िक्स्ड कीमतें डाल सकते हैं, जो रीयल-टाइम दरों के बिना और फ़ॉलबैक के रूप में इस्तेमाल होती हैं (कॉन्फ़िगरेशन देखें)।

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

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

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

Title (zone): इस ज़ोन के लिए ग्राहकों को दिखने वाला नाम। ग्लोबल Method title इस्तेमाल करने के लिए इसे खाली छोड़ें।

सेटिंग्स सेव करते ही कैश की गई NZ Post दरें और एक्सेस टोकन साफ़ हो जाते हैं। अगर सेव की गई वैल्यू से रीयल-टाइम दरें काम नहीं कर सकतीं (Client ID और Client Secret में से केवल एक भरा है, NZD कन्वर्ज़न दर नहीं है, घरेलू दरों के लिए डेटा अधूरा है), तो सेटिंग्स के ऊपर चेतावनी दिखती है।

General

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

Method title: कार्ट और चेकआउट में दिखने वाले शिपिंग विधि का नाम। कोई ज़ोन इसे बदल सकता है। डिफ़ॉल्ट: NZ Post.

Tax status: Taxable शिपिंग लागत में WooCommerce टैक्स जोड़ता है, None नहीं जोड़ता। नीचे API prices भी देखें।

NZ Post API (रीयल-टाइम दरें) (केवल फ़िक्स्ड कीमतें इस्तेमाल करने के लिए Client ID खाली छोड़ें)

Environment: Production (api.nzpost.co.nz) (डिफ़ॉल्ट) या Testing / UAT (api.uat.nzpost.co.nz)। वही एनवायरनमेंट चुनें जिसके लिए आपका Client ID जारी हुआ था।

Client ID: आपके NZ Post API एप्लिकेशन का OAuth2 क्लाइंट ID।

Client Secret: OAuth2 क्लाइंट सीक्रेट। इसे एक्सेस टोकन से बदला जाता है, जो समाप्त होने तक कैश रहता है।

Account number: आपका NZ Post बिज़नेस (बिलिंग) खाता नंबर। न्यूज़ीलैंड के भीतर की दरों के लिए ज़रूरी है। अंतरराष्ट्रीय दरों के लिए वैकल्पिक है; इसके साथ NZ Post आपकी अनुबंध दरें लौटाता है।

Auth code: घरेलू दरों के लिए खाते का auth code। अगर आप site code डालते हैं तो इसकी ज़रूरत नहीं।

Site code: auth code का विकल्प: आपका NZ Post पिकअप साइट कोड।

Ship-from suburb: उस पते का उपनगर जहाँ से पार्सल भेजे जाते हैं, जैसे Petone। घरेलू दरों के लिए ज़रूरी है।

Ship-from city: वह कस्बा या शहर जहाँ से पार्सल भेजे जाते हैं, जैसे Lower Hutt। घरेलू दरों के लिए ज़रूरी है।

Ship-from postcode: वह 4 अंकों का न्यूज़ीलैंड पिन कोड जहाँ से पार्सल भेजे जाते हैं, जैसे 5012। घरेलू दरों के लिए ज़रूरी है।

Services: वैकल्पिक NZ Post सेवा कोड, कॉमा से अलग किए हुए, जैसे CPOLP, ICOU। केवल ये सेवाएँ मूल्यांकित होती हैं। पार्सल के लिए NZ Post द्वारा लौटाई गई सबसे सस्ती सेवा इस्तेमाल करने के लिए खाली छोड़ें।

API prices: Including GST (डिफ़ॉल्ट) या Excluding GST। NZ Post की घरेलू कीमतों में 15% GST शामिल होता है; अंतरराष्ट्रीय डाक शून्य-दर पर है। जब Tax status Taxable हो, तब Excluding GST चुनें, ताकि GST दो बार न लगे।

NZD → (store currency) rate: NZ Post की कीमतें NZD में हैं। अगर आपकी स्टोर मुद्रा NZD नहीं है, तो बताएँ कि 1 NZD आपकी मुद्रा की कितनी इकाइयों के बराबर है, जैसे 0.55। इसके बिना रीयल-टाइम दरें इस्तेमाल नहीं होतीं। वही दर अंतरराष्ट्रीय अनुरोधों के साथ भेजी जाने वाली ऑर्डर राशि को भी बदलती है। अगर आपकी स्टोर मुद्रा NZD है, तो इसे खाली छोड़ें।

रीयल-टाइम दरों के लिए पार्सल

कार्ट NZ Post को एक ही पार्सल के रूप में भेजा जाता है। उत्पादों के वज़न और आयाम आपकी स्टोर इकाइयों से kg और cm में बदले जाते हैं। पार्सल उत्पादों की सबसे बड़ी लंबाई और चौड़ाई लेता है, और इसकी ऊँचाई तब तक बढ़ती है जब तक उसमें सभी आइटम का आयतन न समा जाए। नीचे दिए मान उन उत्पादों के लिए इस्तेमाल होते हैं जिनमें वज़न या आयाम नहीं हैं।

Default product weight (kg): हर उस उत्पाद के लिए इस्तेमाल होता है जिसका वज़न नहीं है। डिफ़ॉल्ट: 0.5.

Default parcel length (cm): तब इस्तेमाल होता है जब कार्ट के किसी उत्पाद में आयाम नहीं हैं। डिफ़ॉल्ट: 30.

Default parcel width (cm): तब इस्तेमाल होता है जब कार्ट के किसी उत्पाद में आयाम नहीं हैं। डिफ़ॉल्ट: 20.

Default parcel height (cm): तब इस्तेमाल होता है जब कार्ट के किसी उत्पाद में आयाम नहीं हैं। डिफ़ॉल्ट: 10.

फ़िक्स्ड कीमतें (तब इस्तेमाल होती हैं जब रीयल-टाइम दरें सेट नहीं होतीं या NZ Post दर नहीं देता)

कीमतें स्टोर मुद्रा में हैं।

Country prices: हर गंतव्य देश के लिए एक पंक्ति। पंक्ति जोड़ने के लिए + Add country पर क्लिक करें, और हटाने के लिए क्रॉस पर। बाकी सभी देशों को कवर करने वाली पंक्ति के लिए * Default चुनें। हर पंक्ति में एक Any weight कीमत और वैकल्पिक वज़न स्तंभ होते हैं: ≤ 1 kg, 1–2 kg, 2–3 kg, 3–5 kg और > 5 kg (कार्ट का वज़न)। भरा हुआ वज़न स्तंभ Any weight को ओवरराइड करता है; खाली या 0 वाला स्तंभ Any weight इस्तेमाल करता है। Any weight कीमत 0 हो तो उस देश के लिए मुफ़्त शिपिंग होती है। "9.99" और "9,99" दोनों स्वीकार होते हैं। बिना किसी कीमत वाली पंक्तियाँ, गलत देश कोड और ऋणात्मक कीमतें सेव करते समय हटा दी जाती हैं। हर देश के लिए केवल एक पंक्ति रखी जाती है।

Fallback cost: तब इस्तेमाल होती है जब न API से और न देश तालिका से कीमत मिलती है। इस स्थिति में विधि छिपाने के लिए इसे खाली छोड़ें।

Fixed price per: Order कीमत एक बार लेता है। Item (price × quantity) इसे कार्ट के आइटमों की संख्या से गुणा करता है। यह केवल फ़िक्स्ड कीमतों और फ़ॉलबैक लागत पर लागू होता है। रीयल-टाइम दरें हमेशा पूरे पार्सल के लिए गिनी जाती हैं।

शर्तें

Min cart weight (kg): कार्ट इससे हल्का हो तो विधि छिपाता है। 0 का मतलब कोई सीमा नहीं।

Max cart weight (kg): कार्ट इससे भारी हो तो विधि छिपाता है। डिफ़ॉल्ट: 25 (NZ Post कूरियर पार्सल 25 kg तक के होते हैं)। 0 का मतलब कोई सीमा नहीं।

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

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

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

इन शर्तों के लिए कार्ट के वज़न में बिना वज़न वाले उत्पादों को 0 गिना जाता है।

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

Ignore shipping zones: नीचे दिए देशों के लिए NZ Post देता है, भले ही विधि किसी शिपिंग ज़ोन में न जोड़ी गई हो।

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

एडवांस्ड

Debug log: दर गणनाएँ WooCommerce > Status > Logs में लिखता है (स्रोत "vfd-nz-post")। API त्रुटियाँ डीबग लॉग बंद होने पर भी हमेशा दर्ज होती हैं। क्रेडेंशियल, टोकन और ग्राहक के पते दर्ज नहीं होते। काम पूरा होने पर लॉग बंद कर दें।

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

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

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

रीयल-टाइम दरें सेट होने पर प्लगइन आपके Client ID और Client Secret से एक्सेस टोकन लेता है और NZ Post से कीमत माँगता है। न्यूज़ीलैंड के पते के लिए वह आपके खाते का विवरण, भेजने का पता, ग्राहक का उपनगर, शहर और पिन कोड, तथा पार्सल का वज़न और आकार भेजता है। WooCommerce में उपनगर का फ़ील्ड नहीं है: अगर Address line 2 में उपनगर का नाम है तो प्लगइन उसे लेता है, नहीं तो कस्बा या शहर। घरेलू दर तभी माँगी जाती है जब ग्राहक शहर और 4 अंकों का पिन कोड डाल दे। दूसरे देशों के लिए वह गंतव्य देश, पार्सल का वज़न और आकार, और NZD में ऑर्डर राशि भेजता है।

अधिभार और अनिवार्य अतिरिक्त सेवाओं सहित, कीमत वाली सबसे सस्ती अनुमत सेवा इस्तेमाल होती है। कीमत NZD से आपकी स्टोर मुद्रा में बदली जाती है। कीमत वाली सेवा ऑर्डर के साथ NZ Post service के रूप में सेव होती है और ऑर्डर स्क्रीन पर दिखती है। हर उत्तर 1 घंटे तक कैश होता है। असफल अनुरोध 10 मिनट तक कैश होता है, ताकि हर रिफ़्रेश पर चेकआउट NZ Post का इंतज़ार न करे। API का टाइमआउट 10 सेकंड है। समाप्त हो चुका एक्सेस टोकन अपने-आप नवीनीकृत होता है।

अगर NZ Post दर नहीं देता (API सेट नहीं है, त्रुटि, अधूरा पता, सेवा उपलब्ध नहीं, NZD दर नहीं), तो ग्राहक को कोई त्रुटि नहीं दिखती। देश तालिका की कीमत इस्तेमाल होती है, फिर फ़ॉलबैक लागत। कोई फ़िक्स्ड कीमत न हो तो विधि छिप जाती है। कारण लॉग में लिखा जाता है।

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

प्लगइन केवल दरें गिनता है। यह शिपिंग लेबल नहीं बनाता, पिकअप बुक नहीं करता, मैनिफ़ेस्ट नहीं बनाता, पार्सल ट्रैक नहीं करता, पते सत्यापित नहीं करता, और ग्राहकों को पिक-अप पॉइंट, PO Box या पार्सल लॉकर चुनने नहीं देता। कार्ट को एक पार्सल के रूप में मूल्यांकित किया जाता है, और ग्राहक को सेवाओं की सूची नहीं, बल्कि एक NZ Post दर दिखती है।

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

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

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

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

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

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

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

रीयल-टाइम दरें नहीं दिख रहीं: WooCommerce > Status > Logs खोलें, स्रोत "vfd-nz-post" वाला। API त्रुटियाँ वहाँ हमेशा होती हैं। विवरण के लिए Debug log चालू करें। लॉग कारण दिखाता है: Client ID या Client Secret गायब, टोकन अस्वीकृत, खाता या भेजने के पते का डेटा गायब, ग्राहक का शहर या पिन कोड अभी नहीं मिला, NZD दर नहीं, या कीमत वाली सेवा नहीं। समस्या ठीक करने तक फ़िक्स्ड कीमतें इस्तेमाल होती हैं।

टोकन अनुरोध विफल: Client ID, Client Secret और Environment जाँचें। UAT क्रेडेंशियल प्रोडक्शन में काम नहीं करते, और इसका उल्टा भी।

घरेलू दरें नहीं हैं, अंतरराष्ट्रीय दरें काम करती हैं: न्यूज़ीलैंड के भीतर की दरों के लिए Account number, Auth code या Site code, और 4 अंकों के पिन कोड वाला पूरा भेजने का पता चाहिए। ग्राहक को शहर और 4 अंकों का पिन कोड डालना होगा। डेवलपर vfd_nzpt_delivery_suburb फ़िल्टर से डिलीवरी पते के लिए भेजा जाने वाला उपनगर बदल सकते हैं।

मेरा स्टोर NZD में नहीं है: NZD → (store currency) rate डालें। फ़िक्स्ड कीमतें हमेशा स्टोर मुद्रा में होती हैं।

शिपिंग पर GST दो बार लग रहा है: NZ Post की घरेलू कीमतों में 15% GST शामिल है। अगर Tax status Taxable है, तो API prices को Excluding GST पर सेट करें।

बदलाव के बाद दरें पुरानी लग रही हैं: सेटिंग्स पेज सेव करें। इससे कैश की गई NZ Post दरें और टोकन साफ़ हो जाते हैं।

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

अनइंस्टॉल

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

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