Measure Mapसहायता
Measure Map खोलें

REST API

अपने सॉफ़्टवेयर से अपने प्रोजेक्ट, फ़ोल्डर, उत्पाद और सदस्यों के साथ काम करें, डेवलपर पेज से अनुरोध आज़माएँ, और कुछ होने पर वेबहुक पाएँ।

REST API आपके अपने सॉफ़्टवेयर को आपके Measure Map Online खाते की चीज़ें पढ़ने और बदलने देता है: प्रोजेक्ट और उनके माप, फ़ोल्डर, उत्पाद सूची और, Enterprise पर, आपके संगठन के सदस्य। यह JSON में जवाब देता है। हर फ़ील्ड और उदाहरण के साथ पूरा संदर्भ API दस्तावेज़ीकरण है; यह पेज उसका अवलोकन है।

ऐप से दस्तावेज़ीकरण खोलने के लिए डेवलपर > REST API पर जाएँ और दस्तावेज़ीकरण देखें दबाएँ।

डेवलपर पेज का REST API अनुभाग

बेस URL#

हर अनुरोध यहाँ जाता है:

https://api.measuremaponline.com/api/v2

प्रमाणीकरण#

हर अनुरोध के Authorization हेडर में अपनी API कुंजी, जैसी है वैसी, भेजें। कुंजी डेवलपर पेज पर बनाएँ: देखें API कुंजियाँ।

curl https://api.measuremaponline.com/api/v2/projects/YOUR_PROJECT_ID \
  -H "Authorization: YOUR_API_KEY"

हर अनुरोध को कुंजी की पहुँच (उदाहरण के लिए, प्रोजेक्ट पढ़ना), आपकी सदस्यता और, किसी वेब पेज से भेजे गए अनुरोध के लिए, कुंजी के वेबसाइट प्रतिबंधों से जाँचा जाता है। डेटा बदल सकने वाली कुंजियाँ अपने सर्वर पर रखें: देखें अपनी कुंजी सुरक्षित रखें।

लाइव और सैंडबॉक्स#

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

API में क्या-क्या शामिल है#

समूह एंडपॉइंट कुंजी की ज़रूरी पहुँच
साइन-इन टोकन POST /auth/token, POST /auth/iframe/token एम्बेड किए गए मानचित्र
प्रोजेक्ट और फ़ोल्डर किसी व्यक्ति के प्रोजेक्ट (सभी, या पेज दर पेज, एक पेज में 200 तक) और फ़ोल्डर की सूची; कोई प्रोजेक्ट, उसके माप (/projects/{pid}/data), उसकी टिप्पणियाँ, या उसकी .mmp फ़ाइल (/projects/{pid}/mmp) पाना; कोई फ़ोल्डर पाना; प्रोजेक्ट और फ़ोल्डर बनाना, अपडेट करना और हटाना प्रोजेक्ट्स: पढ़ने के लिए पढ़ना, बदलने के लिए पढ़ना और बदलना
उत्पाद GET /products, GET /products/{id}, बनाना, अपडेट करना, और DELETE /products/{id} से संग्रहित करना उत्पाद: पढ़ना या पढ़ना और बदलना
सदस्य (Enterprise) GET /users, GET /users/{uid}, POST /users/new, PUT /users/{uid}, DELETE /users/{uid} उपयोगकर्ता: पढ़ना या पढ़ना और बदलना
सदस्य के रूप में साइन इन (Enterprise) POST /auth/{uid}/login आपके संगठन के किसी सदस्य के लिए साइन-इन टोकन देता है उपयोगकर्ता: पढ़ना और बदलना

कुछ बातें जो जानना ज़रूरी है:

  • कोई कुंजी अपने खाते के प्रोजेक्ट तक पहुँचती है और, Enterprise पर, संगठन के सदस्यों के प्रोजेक्ट तक भी।
  • API से किसी प्रोजेक्ट या फ़ोल्डर को हटाना स्थायी है: कुछ भी ट्रैश में नहीं जाता। फ़ोल्डर के साथ उसके अंदर के वे फ़ोल्डर और प्रोजेक्ट भी हट जाते हैं जो आपके खाते या आपके सदस्यों के हैं।
  • किसी प्रोजेक्ट के मापों में, हर आकृति अपने उत्पादों को क्रम से productIds में सूचीबद्ध करती है; productId उनमें से पहला है।
  • /projects/{pid}/mmp वही .mmp फ़ाइल देता है जो ऐप निर्यात करता है। इसका स्कीमा github.com/blueblinkone/mmp-validator पर प्रकाशित है। नए तत्व हमेशा वैकल्पिक तत्वों के रूप में ही जोड़े जाते हैं, इसलिए किसी पुरानी फ़ाइल के लिए लिखा गया रीडर काम करता रहता है।
  • Open Guest पर, API से Open Guest एक्सेस लेवल के साथ बनाया गया प्रोजेक्ट आपके Open Guest उपयोग और बजट में गिना जाता है, ठीक वैसे ही जैसे आपके अतिथि लिंक से शुरू हुआ प्रोजेक्ट।
  • Open Guest पर, अतिथि लिंक अनुभाग में Open Guest API गाइड है, जिसमें आपके सर्वर और पेज के लिए कोड है: आपका सर्वर आपकी लाइव कुंजी से POST /auth/token से टोकन लेता है और विज़िटर को उसके अपने नए प्रोजेक्ट पर भेजता है, जिसमें उसकी जानकारी पहले से भरी होती है।
  • POST /users/new से सदस्य बनाने पर एक सीट लगती है, जैसे आमंत्रण से, और उसे आपके संगठन की डिफ़ॉल्ट भूमिका मिलती है।
  • POST /auth/{uid}/login का टोकन उस सदस्य का खाता खोलता है, इसलिए इसके लिए ऐसी कुंजी चाहिए जो सदस्यों को बदल सके, कभी भी आपके एम्बेड वाली कुंजी नहीं। यह किसी एडमिन या प्रबंधक के लिए नहीं दिया जाता, और न ही सैंडबॉक्स कुंजी से।
  • API से उत्पाद कभी हटाए नहीं जाते, केवल संग्रहित किए जाते हैं, और किसी उत्पाद का लागत मूल्य कभी नहीं लौटाया जाता।
  • भूकर पार्सल API का हिस्सा नहीं हैं।

जवाब और त्रुटियाँ#

सफल अनुरोध स्टेटस 200 और JSON के साथ जवाब देता है (.mmp निर्यात XML के साथ जवाब देता है)। विफल अनुरोध एक त्रुटि स्टेटस और इस तरह के बॉडी के साथ जवाब देता है:

{"errorCode": "insufficient_scope", "errorMessage": "This API key does not have the scope required for this endpoint"}
स्टेटस errorCode क्या जाँचें
400 invalid_body, invalid_uid, invalid_project_id, pagination_invalid_page_number, pagination_invalid_page_limit अनुरोध में कोई मान नहीं है या स्वीकार नहीं किया गया, जैसे पेज दर पेज सूची का page और limit।
401 unauthorized_action अनुरोध किसी ऐसी वेबसाइट के वेब पेज से भेजा गया जिसकी कुंजी अनुमति नहीं देती, या आइटम न आपके खाते में है न आपके सदस्यों के।
402 budget_limit_reached Open Guest: आपकी बजट सीमा पूरी हो गई है, इसलिए इस अवधि में और अतिथि प्रोजेक्ट नहीं।
403 invalid_api_key Authorization हेडर में कोई कुंजी नहीं भेजी गई, या कुंजी अज्ञात है, रद्द की गई है, या बदले जाने के बाद के अपने 24 घंटे पार कर चुकी है।
403 api_key_suspended आपके खाते की API पहुँच निलंबित कर दी गई है। सहायता से संपर्क करें।
403 subscription_expired, invalid_subscription सदस्यता सक्रिय नहीं है, या उसके प्लान में API नहीं है।
403 insufficient_scope कुंजी के पास वह पहुँच नहीं है जो इस एंडपॉइंट को चाहिए।
403 scope_not_in_plan आपके प्लान में यह एंडपॉइंट शामिल नहीं है, उदाहरण के लिए Open Guest पर सदस्य।
404 not_found, project_not_found, user_not_found आइटम मौजूद नहीं है, या वह व्यक्ति आपके संगठन का सदस्य नहीं है।
409 enterprise_add_users_limit सदस्य बनाते समय: सभी सीटें भरी हुई हैं।
429 too_many_requests एक घंटे में 600 से ज़्यादा टोकन। थोड़ा रुककर फिर से प्रयास करें।
500 server_error अनुरोध पूरा नहीं हो सका। भेजी गई ID जाँचें, फिर से प्रयास करें, और अगर समस्या बनी रहे तो सहायता से संपर्क करें।

डेवलपर पेज से API आज़माएँ#

डेवलपर > API आज़माएँ आपकी कुंजी से असली अनुरोध भेजता है और ठीक-ठीक दिखाता है कि जवाब में क्या आया।

  1. लाइव या सैंडबॉक्स चुनें।
  2. कोई एंडपॉइंट चुनें, जैसे "सभी प्रोजेक्ट सूचीबद्ध करें" या "माप प्राप्त करें"।
  3. उसके पैरामीटर भरें। कोई प्रोजेक्ट या उत्पाद उन में से नाम से चुना जाता है जिन्हें कुंजी पढ़ सकती है; जहाँ किसी व्यक्ति की ज़रूरत है, वहाँ आपका अपना खाता आपके लिए भर दिया जाता है।
  4. अनुरोध भेजें दबाएँ। स्टेटस और जवाब नीचे दिखते हैं।

केवल पढ़ने वाले अनुरोध ही दिए जाते हैं, इसलिए आज़माने से कुछ नहीं बदलता, और ये अनुरोध आपके उपयोग में नहीं गिने जाते। अगर आपकी कुंजी के पास वह पहुँच नहीं है जो किसी एंडपॉइंट को चाहिए, तो पेज आपको चेतावनी देता है कि वह 403 जवाब देगा।

API आज़माएँ, जिसमें एक अनुरोध भेजा गया है और उसका JSON जवाब है

वेबहुक#

वेबहुक आपके सर्वर को बताता है कि कुछ हुआ है, जैसे सूचना ईमेल आपको बताते हैं। वेबहुक Enterprise और Open Guest प्लान का हिस्सा हैं।

वेबहुक सेट करें#

डेवलपर > वेबहुक में:

  1. अपना एंडपॉइंट URL टाइप करें: इंटरनेट पर एक https:// पता। निजी नेटवर्क के पते अस्वीकार कर दिए जाते हैं, और हर डिलीवरी से पहले इसे फिर से जाँचा जाता है।
  2. जो इवेंट आप चाहते हैं उन्हें चुनें (देखें इवेंट)। नया एंडपॉइंट उन इवेंट से शुरू होता है जो आपका प्लान भेजता है, और कम से कम एक चुना होना चाहिए।
  3. सहेजें दबाएँ। पहली बार, पेज आपका साइनिंग सीक्रेट पूरा दिखाता है। उसी समय उसे कॉपी करें: उसके बाद उसके केवल आख़िरी अक्षर दिखाए जाते हैं।
  4. परीक्षण इवेंट भेजें दबाएँ और कोई इवेंट चुनें।

परीक्षण उस इवेंट का एक नमूना, बनावटी मानों और उसके data में "test": true के साथ, आपके सहेजे गए एंडपॉइंट पर भेजता है, तब भी जब इवेंट चुना नहीं गया हो या एंडपॉइंट बंद हो। सभी डिलीवरी रोकने के लिए निकालें दबाएँ: एंडपॉइंट और उसका सीक्रेट हटा दिए जाते हैं।

सेटिंग्स के नीचे, वेबहुक संदर्भ में वह सब है जो आपको पाने वाला हिस्सा लिखने के लिए चाहिए: हेडर और बॉडी, Node.js, Python और PHP में सिग्नेचर जाँचने वाला कोड, और हर इवेंट का उदाहरण डेटा।

एक एंडपॉइंट और उसे मिलने वाले इवेंट के साथ वेबहुक

आपके सर्वर को क्या मिलता है#

हर इवेंट आपके एंडपॉइंट पर एक POST है, JSON बॉडी के साथ:

{"id": "evt_3f9a1c2b7d4e5f60718293a4", "type": "project.created", "created": 1790000000000, "data": { ... }}

id हर इवेंट के लिए अलग होता है, created बताता है कि इवेंट कब हुआ, 1 जनवरी 1970 (UTC) से मिलीसेकंड में, और data में क्या है यह इवेंट पर निर्भर करता है। अनुरोध में ये हेडर भी होते हैं:

हेडर मान
X-MMO-Event इवेंट का नाम, बॉडी के type जैसा।
X-MMO-Delivery इवेंट का id।
X-MMO-Signature t=<milliseconds>,v1=<hex>: डिलीवरी कब साइन हुई, और उसका सिग्नेचर।
User-Agent MeasureMapOnline-Webhooks/1
  • 8 सेकंड के अंदर 2xx स्टेटस के साथ जवाब दें, कोई भी धीमा काम करने से पहले। कोई और स्टेटस, रीडायरेक्ट या टाइमआउट विफलता गिना जाता है।
  • हर इवेंट एक बार भेजा जाता है और कभी दोबारा नहीं भेजा जाता। यह अनुभाग अंतिम डिलीवरी और लगातार विफलताएँ दिखाता है।
  • लगातार 10 विफलताओं के बाद एंडपॉइंट बंद कर दिया जाता है और स्वामी को ईमेल मिलता है। अपना सर्वर ठीक करें और उसे फिर से चालू करने के लिए सहेजें दबाएँ।
  • कभी-कभी कोई इवेंट दो बार या क्रम से बाहर आता है। दोहराव अनदेखा करने के लिए id और इवेंट को क्रम में रखने के लिए created का उपयोग करें।

सिग्नेचर जाँचें#

आपका पता जानने वाला कोई भी उस पर पोस्ट कर सकता है, इसलिए हर डिलीवरी पर भरोसा करने से पहले उसे जाँचें:

  1. X-MMO-Signature हेडर को कॉमा पर t और v1 में बाँटें।
  2. t, एक पूर्ण विराम (.) और अनुरोध की असली बॉडी का HMAC-SHA256 निकालें, अपने साइनिंग सीक्रेट को कुंजी बनाकर, हेक्साडेसिमल में लिखा हुआ।
  3. नतीजे की v1 से तुलना कॉन्स्टेंट-टाइम तुलना से करें।
  4. अगर t मौजूदा समय से 5 मिनट से ज़्यादा दूर है, तो डिलीवरी अस्वीकार करें। t मिलीसेकंड में है।

बॉडी को ठीक वैसे ही इस्तेमाल करें जैसी वह आई: JSON को पार्स करके फिर से लिखने से वह बदल जाती है, और सिग्नेचर मेल नहीं खाता।

सीक्रेट बदलें सीक्रेट को तुरंत बदल देता है और नया सीक्रेट एक बार पूरा दिखाता है। रोटेट करते ही अपना सर्वर अपडेट करें।

इवेंट#

इवेंट कब भेजा जाता है
project.created आपके खाते में कोई प्रोजेक्ट बनता है। ऐप में, API से या किसी एम्बेड से।
project.deleted कोई प्रोजेक्ट स्थायी रूप से हटाया जाता है (ट्रैश में ले जाना नहीं गिना जाता)।
project.comment.added कोई प्रोजेक्ट पर टिप्पणी करता है — आमतौर पर आपका ग्राहक जवाब देता है।
guest.project.created (ओपन अतिथि) कोई अतिथि आपके लिंक से या API के ज़रिए प्रोजेक्ट शुरू करता है। केवल तब, जब अतिथि का ईमेल पता मालूम हो।
guest.measurement.completed (ओपन अतिथि) कोई अतिथि माप पूरा करके अपना संपर्क विवरण छोड़ता है।
budget.warning_reached (ओपन अतिथि) मीटर्ड खर्च आपकी चेतावनी सीमा पार करता है।
budget.limit_reached (ओपन अतिथि) मीटर्ड खर्च आपकी सीमा तक पहुँचता है — आगे के गेस्ट प्रोजेक्ट अस्वीकार होते हैं।
enterprise.user.created (उद्यम) आपके संगठन में एक सीट जुड़ती है, सिंगल साइन-ऑन के ज़रिए भी।

अब भी मदद चाहिए?

हमारी सहायता टीम को लिखें और बताएँ कि आप क्या करने की कोशिश कर रहे थे। स्क्रीनशॉट से मदद मिलती है।

सहायता को ईमेल करें