URL क्वेरी पैरामीटर कॉन्फ़िगरेशन

प्रत्येक MirApi नियंत्रण (control) हेडर का एक समकक्ष URL क्वेरी पैरामीटर उपनाम (alias) है। यह आपको बिना किसी कस्टम HTTP हेडर सेट किए सीधे URL में गेटवे की पूरी शक्ति — पुनः प्रयास (retries), कैशिंग, कैस्केड, अतुल्यकालिक (async) वेबहुक — कॉन्फ़िगर करने की अनुमति देता है।

यह सुविधा विशेष रूप से तृतीय-पक्ष वेबहुक निर्माताओं (third-party webhook producers) (जैसे Shopify, GitHub, Stripe, CRM प्लेटफ़ॉर्म) के लिए डिज़ाइन की गई है जो केवल एक एकल URL फ़ील्ड स्वीकार करते हैं और कस्टम हेडर इंजेक्शन की अनुमति नहीं देते हैं।

---

क्वेरी पैरामीटर क्यों?

ऐतिहासिक रूप से, MirApi को विशेष रूप से कस्टम X-* HTTP हेडर के माध्यम से कॉन्फ़िगर किया गया था। यह तब पूरी तरह से काम करता है जब आपका स्वयं का कोड अनुरोध (request) करता है। लेकिन कई प्लेटफ़ॉर्म जो वेबहुक ट्रिगर करते हैं — जैसे Shopify Admin, GitHub Actions, Stripe Events, HubSpot, Salesforce — आपको केवल एक गंतव्य URL (destination URL) दर्ज करने की अनुमति देते हैं। वे अपने स्वयं के निश्चित हेडर भेजते हैं और आपको कस्टम हेडर जोड़ने का कोई तरीका नहीं देते हैं।

क्वेरी पैरामीटर फ़ॉलबैक मैपिंग इस समस्या को हल करती है: प्रत्येक रूटिंग, विश्वसनीयता और सुरक्षा हेडर को सीधे आपके MirApi वेबहुक URL में जोड़े गए GET क्वेरी पैरामीटर के रूप में पास किया गया जा सकता है।

---

मुख्य नियम

सावधानी

हेडर प्राथमिकता (Header Precedence): HTTP हेडर हमेशा क्वेरी पैरामीटर पर प्राथमिकता लेते हैं। यदि एक ही अनुरोध में X-Target-URL (हेडर) और target (क्वेरी पैरामीटर) दोनों मौजूद हैं, तो गेटवे हेडर मान का उपयोग करता है और क्वेरी पैरामीटर को अनदेखा कर देता है। इसका मतलब है कि आप हाइब्रिड वातावरण में दोनों को सुरक्षित रूप से मिला सकते हैं — हेडर हमेशा जीतते हैं।

खतरा

URL एन्कोडिंग अनिवार्य है। क्वेरी पैरामीटर के अंदर पास किया गया कोई भी URL (लक्षित एंडपॉइंट, कॉलबैक URL) URL-एन्कोडेड होना चाहिए। https:// को https%3A%2F%2F और / को %2F से बदलें। एन्कोड करने में विफल रहने के कारण गेटवे नेस्टेड URL को गलत तरीके से पार्स करेगा और अनुरोध को 400 Bad Request त्रुटि के साथ अस्वीकार कर देगा।

जावास्क्रिप्ट में encodeURIComponent() या पायथन में urllib.parse.quote() जैसे टूल का उपयोग करें।

संकेत

अवधि स्ट्रिंग्स (Duration Strings): सभी टाइमआउट और विलंब पैरामीटर मानक Go अवधि स्ट्रिंग्स स्वीकार करते हैं: 200ms, 5s, 1m, 1h30m। साधारण पूर्णांक अमान्य हैं — 5 नहीं, 5s का उपयोग करें।

---

पूर्ण हेडर → क्वेरी पैरामीटर मैपिंग

HTTP हेडर	क्वेरी पैरामीटर उपनाम (Alias)	विवरण
X-MirApi-Key	mirapi_key या apiKey	MirApi के लिए प्रमाणीकरण टोकन। प्रत्येक अनुरोध पर आवश्यक।
X-Target-URL	target_url या target	गंतव्य API एंडपॉइंट जहां अनुरोध रूट किया जाता है। URL-एन्कोडेड होना चाहिए।
X-Route-Key	route_key या route	आपके डैशबोर्ड से पूर्व-कॉन्फ़िगर कैस्केड रूट का चयन करता है।
X-Webhook-Callback	webhook_callback या callback	अतुल्यकालिक कतार (async queueing) मोड सक्षम करता है। कॉलबैक एंडपॉइंट को परिभाषित करता है। URL-एन्कोडेड होना चाहिए।
X-Failover-URL	failover_url	यदि सभी पुनः प्रयासों के बाद लक्ष्य विफल हो जाता है तो प्राथमिक फ़ॉलबैक एंडपॉइंट। URL-एन्कोडेड होना चाहिए।
X-Proxy-Timeout	proxy_timeout या timeout	कुल अनुरोध टाइमआउट (जैसे, 10s)। सभी पुनः प्रयास विलंबों सहित संपूर्ण निष्पादन को सीमित करता है।
X-Attempt-Timeout	attempt_timeout	प्रति-प्रयास टाइमआउट (जैसे, 2s)। यदि कोई एकल कॉल इससे अधिक हो जाती है, तो इसे विफलता माना जाता है और पुनः प्रयास किया जाता है।
X-Retry-Count	retry_count or retries	5xx या कनेक्शन विफलता पर पुनः प्रयास के अधिकतम प्रयासों की संख्या।
X-Retry-Delay	retry_delay या delay	घातीय पुनः प्रयास के लिए प्रारंभिक बैकऑफ़ विलंब (जैसे, 100ms)। प्रत्येक पुनः प्रयास विलंब को दोगुना करता है प्लस जिटर (jitter)।
X-Circuit-Breaker	circuit_breaker या cb	लक्षित होस्ट के लिए सर्किट ब्रेकर सक्षम करता है। on या true स्वीकार करता है।
X-Smart-Cache	smart_cache या cache	अंतिम सफल प्रतिक्रिया को कैश करता है और यदि अपस्ट्रीम विफल हो जाता है तो उसे परोसता है (जैसे, 60s)।
X-Extract-Map	extract_map या map	अपस्ट्रीम JSON प्रतिक्रिया से फ़ील्ड निकालता है और उनका नाम बदलता है (जैसे, $.id=>new_id)।
X-Extract-Redirect	extract_redirect या redirect	अपस्ट्रीम JSON प्रतिक्रिया से एक रीडायरेक्ट URL निकालता है और 302 Found लौटाता है।

---

उदाहरण

उदाहरण 1 — Shopify अतुल्यकालिक वेबहुक कतार (Shopify Async Webhook Queueing)

Shopify ऑर्डर दिए जाने पर वेबहुक ट्रिगर करता है। यदि आपका ERP या CRM अस्थायी रूप से बंद है, तो Shopify आपके एंडपॉइंट को विफल के रूप में चिह्नित करेगा और पर्याप्त विफलताओं के बाद इसे निष्क्रिय कर सकता है।

MirApi के अतुल्यकालिक वेबहुक मोड का उपयोग करके, Shopify गंतव्य के रूप में एक MirApi URL कॉन्फ़िगर करें। MirApi तुरंत Shopify को 202 Accepted लौटाता है (निष्क्रियता को रोकता है), पेलोड को Redis-समर्थित वर्कर कतार में संग्रहीत करता है, और इसे स्वचालित पुनः प्रयासों के साथ आपके ERP तक पहुंचाता है।

Shopify वेबहुक URL:

https://proxy.mirapi.io/v1/webhook?mirapi_key=your_api_key&callback=https%3A%2F%2Fmy-erp.com%2Fapi%2Forders&retries=10&delay=1s&timeout=5s

पैरामीटर विवरण:

पैरामीटर	मान	समकक्ष हेडर
mirapi_key	your_api_key	X-MirApi-Key
callback	https%3A%2F%2Fmy-erp.com%2Fapi%2Forders	X-Webhook-Callback
retries	10	X-Retry-Count
delay	1s	X-Retry-Delay
timeout	5s	X-Proxy-Timeout

क्या होता है:

1. Shopify ऑर्डर पेलोड के साथ MirApi URL पर POST करता है।
2. MirApi mirapi_key की पुष्टि करता है और तुरंत Shopify को 202 Accepted लौटाता है।
3. पेलोड को Redis वर्कर कतार में धकेल दिया जाता है।
4. वर्कर 1-सेकंड की प्रारंभिक देरी और घातीय बैकऑफ़ (प्रति प्रयास अधिकतम 5s) के साथ 10 बार तक पुनः प्रयास करते हुए POST https://my-erp.com/api/orders करने का प्रयास करता है।
5. सफलता पर, कार्य को पूर्ण चिह्नित किया जाता है। कुल विफलता पर, आपके कॉलबैक एंडपॉइंट को एक त्रुटि पेलोड प्राप्त होता है।

---

उदाहरण 2 — स्मार्ट कैशिंग के साथ सिंक्रोनस प्रॉक्सी (Synchronous Proxying with Smart Caching)

इसका उपयोग तब करें जब आप स्वचालित पुनः प्रयासों के साथ किसी तृतीय-पक्ष API से डेटा प्राप्त कर रहे हों और एक कैश चाहते हों जो अपस्ट्रीम डाउन होने पर अंतिम ज्ञात अच्छी प्रतिक्रिया प्रदान करे।

GET https://proxy.mirapi.io/v1/proxy?mirapi_key=your_api_key&target=https%3A%2F%2Fapi.external-service.com%2Fv1%2Fproducts&retries=3&cache=60s HTTP/1.1

क्या होता है:

1. MirApi https://api.external-service.com/v1/products पर GET को अग्रेषित (forward) करता है।
2. सफलता पर, प्रतिक्रिया को 60 सेकंड के लिए कैश किया जाता है और आपको लौटाया जाता है।
3. यदि अपस्ट्रीम 5xx लौटाता है या टाइमआउट हो जाता है, तो MirApi घातीय बैकऑफ़ के साथ 3 बार तक पुनः प्रयास करता है।
4. यदि सभी पुनः प्रयास विफल हो जाते हैं, तो MirApi अंतिम कैश की गई सफल प्रतिक्रिया (यदि उपलब्ध हो) परोसता है। प्रतिक्रिया में X-Rescued: cache शामिल होता है।

---

उदाहरण 3 — वेबहुक URL के माध्यम से डैशबोर्ड कैस्केड रूट (Dashboard Cascade Route via Webhook URL)

यदि आपके पास एक जटिल मल्टी-टारगेट कैस्केड है जिसमें अनुरोध बॉडी मैपिंग आपके MirApi डैशबोर्ड में पहले से कॉन्फ़िगर की गई है, तो इसे एक एकल route पैरामीटर के साथ संदर्भित करें।

Shopify वेबहुक URL:

https://proxy.mirapi.io/v1/webhook?mirapi_key=your_api_key&route=shopify_to_crm

यह गेटवे को आपके खाते से shopify_to_crm रूट को खोजने का निर्देश देता है, जिसमें शामिल हो सकते हैं:

• एकाधिक कैस्केड लक्ष्य (उदा. Salesforce → HubSpot → Pipedrive)
• अनुरोध बॉडी फ़ील्ड उपनाम (उदा. line_items => order_lines)
• प्रति-लक्ष्य टाइमआउट और फ़ॉलबैक रणनीति

प्रत्येक URL में लक्ष्य URL, टाइमआउट या मैपिंग नियमों को दोहराने की कोई आवश्यकता नहीं है।

---

चरण-दर-चरण: Shopify वेबहुक एकीकरण

Shopify को अतुल्यकालिक कतार (async queueing) और पुनः प्रयास सुरक्षा के साथ MirApi के माध्यम से आपके ERP में orders/create इवेंट देने के लिए कॉन्फ़िगर करें।

1. अपनी MirApi API कुंजी प्राप्त करें

   mirapi.io पर लॉग इन करें, अपना डैशबोर्ड खोलें, और अपनी API कुंजी कॉपी करें। यह la_5fa62960e7c9af7c*** जैसी दिखाई देगी।

2. अपने ERP वेबहुक एंडपॉइंट की पहचान करें

   यह वह URL है जहां Shopify ऑर्डर पेलोड अंततः वितरित किए जाने चाहिए। उदाहरण के लिए:

   https://my-erp.com/api/orders/shopify

3. अपने ERP एंडपॉइंट को URL-एन्कोड करें

   क्वेरी स्ट्रिंग में एम्बेड करने से पहले ERP URL को URL-एन्कोड करें:

   इनपुट:  https://my-erp.com/api/orders/shopify
   आउटपुट: https%3A%2F%2Fmy-erp.com%2Fapi%2Forders%2Fshopify

   अपनी पसंद की भाषा में त्वरित संदर्भ:

   • जावास्क्रिप्ट: encodeURIComponent('https://my-erp.com/api/orders/shopify')
   • पायथन: urllib.parse.quote('https://my-erp.com/api/orders/shopify', safe='')
   • Go: url.QueryEscape("https://my-erp.com/api/orders/shopify")

4. अपना MirApi वेबहुक URL बनाएं

   अपने लचीलेपन पैरामीटर के साथ अंतिम URL को असेंबल करें:

   https://proxy.mirapi.io/v1/webhook?mirapi_key=la_5fa62960e7c9af7c***&callback=https%3A%2F%2Fmy-erp.com%2Fapi%2Forders%2Fshopify&retries=10&delay=1s&timeout=5s&cb=on

   उपयोग किए गए पैरामीटर:

   पैरामीटर	मान	प्रभाव
   mirapi_key	la_5fa62960e7c9af7c***	अनुरोध को प्रमाणित करता है
   callback	https%3A%2F%2F...	ERP वितरण एंडपॉइंट (URL-एन्коडेड)
   retries	10	यदि ERP अनुपलब्ध है तो 10 पुनः प्रयास तक प्रयास
   delay	1s	1s प्रारंभिक बैकऑफ़, प्रत्येक प्रयास में दोगुना होता है
   timeout	5s	प्रत्येक वितरण प्रयास 5s के बाद टाइमआउट हो जाता है
   cb	on	ERP होस्ट पर सर्किट ब्रेकर सक्षम करता है

5. Shopify Admin में कॉन्ஃபिगर करें

   Settings → Notifications → Webhooks पर जाएं और एक नया वेबहुक बनाएं:

   • इवेंट: Order creation
   • प्रारूप: JSON
   • URL: (चरण 4 से अपना MirApi URL पेस्ट करें)

6. अपने MirApi डैशबोर्ड में सत्यापित करें

   Shopify में एक परीक्षण ऑर्डर बनाएं। अपने MirApi डैशबोर्ड में, आने वाले कार्य को खोजने के लिए Webhook Queue टैब खोलें। जॉब पैनल दिखाता है:

   • टाइमस्टैम्प के साथ वितरण प्रयास
   • प्रति प्रयास HTTP स्थिति कोड
   • अंतिम वितरण स्थिति और कोई भी त्रुटि पेलोड

संकेत

पेलोड रीमैपिंग की आवश्यकता है? यदि आपका ERP Shopify द्वारा भेजे जाने वाले JSON संरचना से भिन्न संरचना की अपेक्षा करता है (उदा. line_items → items), तो बॉडी उपनाम नियमों के साथ एक डैशबोर्ड रूट कॉन्फ़िगर करें और callback=... के बजाय route=shopify_to_erp पर स्विच करें। गेटवे प्रत्येक वितरण प्रयास से पहले पेलोड को स्वचालित रूप से रीमैप करता है।

---

सुरक्षा संबंधी विचार

URL में API कुंजी
mirapi_key सहित क्वेरी पैरामीटर, सर्वर एक्सेस लॉग में दिखाई देते हैं और ब्राउज़र इतिहास या तृतीय-पक्ष विश्लेषण में कैप्चर हो सकते हैं। वेबहुक URL को एक गुप्त (secret) मान की तरह मानें। यदि आपको संदेह है कि URL उजागर हो गया है, तो तुरंत अपनी API कुंजी को रोटेट करें।

हमेशा HTTPS का उपयोग करें
केवल https://proxy.mirapi.io/... का उपयोग करें। सादे HTTP पर प्रेषित क्वेरी पैरामीटर पारगमन में दिखाई देते हैं।

कॉलबैक एंडपॉइंट सत्यापन
यह पुष्टि करने के लिए कि आपके ERP पर आने वाले कॉलबैक वास्तव में MirApi से हैं और स्पूफ़ नहीं किए गए हैं, निम्न में से किसी एक का उपयोग करें:

• IP अनुमति सूची (allowlisting): इनबाउंड अनुरोधों को MirApi की प्रकाशित निकास (egress) IP सीमाओं तक सीमित करें।
• गुप्त पथ टोकन (Secret path token): अपने कॉलबैक URL पथ में एक गुप्त टोकन एम्बेड करें (उदा. /api/orders/shopify/s3cr3t-token) जिसे केवल MirApi जानता हो।